用途：为服务方法添加 OpenTelemetry（OTEL）插桩，实现分布式追踪、结构化日志与跨 Clean Architecture 层的可观测性。适用于新增需要可观测性的服务方法、调试跨层执行流程、排查性能瓶颈、多服务分布式追踪、带 trace 关联的结构化日志，以及用日志替换 print() 语句。
主要能力：@traced 装饰器自动为方法创建 span，span 名称为函数名，函数参数（仅基本类型）作为 span 属性，并自动注入 trace_id、span_id；get_logger 提供的日志器自动在日志中包含 trace_id、span_id 与 correlation ID；trace_span 用于方法内细粒度子操作追踪，可 set_attribute 记录指标；correlation_context 用于跨多次方法调用的请求关联。
使用方式：从 project_watch_mcp.core.monitoring 导入 get_logger、traced（高级用法还包括 trace_span、correlation_context、add_context）；用 logger = get_logger(name) 初始化日志器；在目标方法上加 @traced；用 logger.info/debug/warning/error 记录带上下文的日志；复杂操作使用 with trace_span("name", key=value) as span 并调用 span.set_attribute()；多文件或批处理使用 with correlation_context() as cid。验证可运行 uv run pytest tests/path/to/test.py -v，并用 tail -f logs/project-watch-mcp.log | grep "trace:" 检查日志中的 trace/span ID。
适用场景：Application 层的 Command/Query Handler、Infrastructure 服务（如 EmbeddingService、Neo4jCodeRepository）、Interface 层的 MCP 工具，以及多步骤流程与批量操作。
限制与要求：需先初始化 OTEL（由 core/monitoring 的 initialize_otel_logger() 处理，应用启动时调用一次）；需要 Python 3.11+、async/await 支持、ServiceResult 返回类型模式，并能访问 project_watch_mcp.core.monitoring 模块。@traced 同时支持同步与异步方法。span 属性仅支持基本类型参数。避免记录 API 密钥、密码、PII 等敏感数据。若日志缺少 trace ID，需确认 OTEL 已在任何日志之前初始化。附带脚本 scripts/add_tracing.py、scripts/analyze_traces.py、scripts/validate_instrumentation.py 可辅助自动插桩、分析追踪覆盖率与校验插桩模式。