OpenTelemetry 插桩实践：手动、自动与语言 SDK

手动插桩：显式调用 tracer.start_span()，能表达业务语义但侵入代码
自动插桩：零代码（Java Agent/包钩子），覆盖框架与中间件，
          但拿不到业务上下文，只有框架层信息

结论：自动给"覆盖率"，手动给"业务语义"，两者配合

纯自动：依赖 Agent/包装器，适合存量系统、不想改代码
自动+手动（推荐）：自动埋框架，手动埋业务关键路径
纯手动：所有 Span/Metric 手写，适合 SDK 作者/热路径

tracer := otel.Tracer("shop/order") // 命名：包路径.功能
ctx, span := tracer.Start(ctx, "POST /orders",
    trace.WithSpanKind(trace.SpanKindServer),
    trace.WithAttributes(attribute.String("http.request.method", "POST")))
defer span.End()
span.RecordError(err)
span.SetStatus(codes.Error, err.Error())

Span 父子关系由 Context 决定：父 span 创建 ctx → ctx 传给子调用
正确姿势：业务函数第一个参数收 ctx 一路传，跨 goroutine 也传
错误姿势：全局/包级存 span（并发不安全）；只存 trace_id 不复用 ctx

命名：用 <operation> <target>（如 "GET /users/:id"），别含高基数变量
属性：键用语义约定标准键；默认最多 128 个属性、2048 字节值
事件：时间点标注（"cache.hit"），别存状态

meter := otel.Meter("shop/order")
c, _ := meter.Int64Counter("shop.orders.created")
c.Add(ctx, 1, metric.WithAttributes(attribute.String("channel", "web")))
h, _ := meter.Float64Histogram("shop.orders.duration_ms", metric.WithUnit("ms"))
h.Record(ctx, elapsed.Milliseconds())

目标：日志里能按 trace_id 找到整条链路的 span
做法：从 Context 取 trace_id/span_id，结构化写入每条日志
  slog 示例：logger.InfoContext(ctx, "order created",
             slog.Int("order_id", id)) → 自动注入 trace_id

不关联的代价：日志与 trace 两张皮，排障靠时间猜

正确架构：一个 Context 贯穿 trace/metric/log
  ctx 带 trace_id + baggage → 指标带 trace 归属、日志带 trace_id
  排障时"从日志点进 trace、从 trace 看指标"一路通

Java 自动插桩 = JVM Agent + ByteBuddy 字节码重写
流程：启动挂 -javaagent:...jar → 扫描已加载类 → 匹配目标类
      → 在方法入口/出口插入 span 创建/结束字节码
要点：必须在目标类加载前生效；热路径有开销

# 安装 opentelemetry-instrumentation-* 后一行启用
from opentelemetry.instrumentation.flask import FlaskInstrumentor
app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)
# 或命令行自动检测：opentelemetry-instrument python app.py

原理：MonkeyPatch 把目标函数替换成"包装器"，先启动 span 再调原函数，
      通过 W3C tracecontext 从请求头提取上下文；patch 顺序要在处理前完成

Node：require 钩子必须先于目标模块加载（node -r ./tracing.js app.js）
Go：没有字节码增强，用"插桩版"包装器
  net/http → otelhttp、database/sql → otelsql、gRPC 拦截器
  eBPF（uprobe）是补充方案，落地复杂

跨语言通用（环境变量优先于代码）：
  OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES
  OTEL_TRACES_EXPORTER / OTEL_EXPORTER_OTLP_ENDPOINT
  OTEL_SAMPLER=parentbased_traceidratio
  OTEL_TRACE_SAMPLER_ARG="0.1"

exp, _ := otlptracegrpc.New(ctx, otlptracegrpc.WithEndpoint(endpoint))
sp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exp, sdktrace.WithBatchTimeout(5*time.Second)),
    sdktrace.WithSampler(sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.1))))
otel.SetTracerProvider(sp)

Java：-javaagent 自动 + Spring Boot 自动配置最省事，注意版本一致
Python：opentelemetry-instrument 命令行 + 环境变量，版本匹配框架
Node：@opentelemetry/sdk-node + -r 预加载，先于目标模块
Go：显式初始化 + 中间件/拦截器包装，没有零配置但每处可控

Resource 描述"谁产生的数据"：
  service.name / service.version / deployment.environment
  host.name / k8s 属性 → 定位实例
统一设置：OTEL_RESOURCE_ATTRIBUTES="deployment.environment=prod"
坑：service.name 不统一 → 指标"一名多义"，聚合散架

语义约定的作用：同字段统一命名，跨服务/厂商可关联
优先用标准字段：http.request.method / url.path /
  http.response.status_code / db.system / db.statement
反例：自定义 "code:200" → 无法与标准面板对齐

采样：推荐 ParentBased + TraceIDRatio（子 span 跟随父决定）
      错误请求"保底"交给 Collector 尾部采样
出口：首选 OTLP → OTel Collector → 各后端
      直推后端也行，但失去集中采样/降噪能力

□ 先自动插桩保覆盖率，再手动插桩补业务语义
□ Tracer 命名用包路径.功能，Span 命名用 <操作> <目标>
□ Context 一路传递，跨 goroutine 不丢 trace_id
□ 日志经 Context 注入 trace_id，三大支柱一链通
□ 手动埋点只做关键路径，热路径避免额外 Span
□ 资源统一设置 service.name / environment
□ 字段一律用语义约定标准键
□ 采样用 ParentBased + TraceIDRatio，敏感服务调高
□ 出口走 OTel Collector，保留集中采样与脱敏能力
□ 插桩完成后冒烟验证：确认 trace 真的进后端

插桩 = 自动给广度 + 手动给深度 + 语义约定给统一，
让每条数据都"有来源、有标准、可关联"。