DDTrace

DataKit 的 ddtrace 采集器是一个 DataDog Trace 协议接收端：应用内的 DDTrace SDK 或 Java Agent 将 trace 通过 HTTP 发送给 DataKit，DataKit 再解析、处理并上报这些数据。它不会替应用安装 SDK，也不会替代应用侧的插桩。

数据链路如下：

应用代码 → DDTrace SDK / Java Agent → DataKit HTTP 接收端 → 观测云

链路、Profiling 数据和运行时/JMX 指标使用的接收端不同：

• Trace 由本采集器接收，默认使用 DataKit HTTP 端口 9529；
• Profiling 需要单独开启 Profiling 采集器；
• JMX、runtime metrics 等 DogStatsD 指标需要单独开启 StatsD 采集器，通常使用 8125 端口。

使用前请确认¶

1. DataKit 已安装并已启用本采集器；应用侧也已按所用语言完成 SDK 或 Agent 的插桩。
2. 应用与 DataKit 的网络连通。DataKit 默认仅监听 localhost:9529；应用不在同一主机或同一 Pod 时，需调整 HTTP 服务监听地址 并通过防火墙、Kubernetes Service 或 NetworkPolicy 限制访问范围。
3. 显式将应用侧的 trace 目标设置为 DataKit 地址和端口，例如 DD_AGENT_HOST=<datakit-host>、DD_TRACE_AGENT_PORT=9529。上游 Datadog Agent 的常见默认端口是 8126，不要依赖默认值，也不要把 StatsD 的 8125 当作 trace 端口。
4. 为服务设置稳定的 DD_SERVICE、DD_ENV 和 DD_VERSION；这三个维度决定服务、环境和版本在链路视图中的归属。

接收 OpenLineage¶

启用 ddtrace 采集器后，DataKit 同时在其 HTTP 端口（默认 9529）开放 POST /openlineage/api/v1/lineage。此接口与上面的 DDTrace trace 接口独立，不受 endpoints 列表影响，也无需额外开关。OpenLineage HTTP 客户端可将基础 URL 设为 http://<datakit-host>:9529/openlineage，请求路径设为 /api/v1/lineage。

每次请求发送一个 OpenLineage JSON 事件，Content-Type 为 application/json，可使用 Content-Encoding: gzip。事件格式和直连方式参见 OpenLineage 数据接入。例如：

curl -X POST 'http://127.0.0.1:9529/openlineage/api/v1/lineage' \
  -H 'Content-Type: application/json' \
  --data-binary @event.json

DataKit 按原始字节同步转发到 DataWay 的 /v1/write/openlineage，不解析或改写事件。请求使用 DataKit 已配置的 DataWay token；调用方无需在 URL、Authorization 或 X-Token 中提供 token，传入的这些凭证也不会被转发。请按需限制 DataKit HTTP 端口的可访问范围。

max_lineage_body_mb 控制 DataKit 接收的请求体大小，默认 64 MiB，按解压前字节数计算；DataWay 和下游仍可能有各自的限制。DataKit 返回 DataWay 的 HTTP 状态，保留成功响应体（包括 error_code 为 dataway.cached 的缓存确认），并透传 Retry-After 响应头。503 表示当前无法安全确认接收，调用方应按 Retry-After 重试。2xx 表示 DataWay 已接收或缓存，不代表 Kodo 已完成异步校验与血缘入库。DataKit 当前不为这条链路提供本地缓存。

按语言接入¶

配置¶

本节配置的是 DataKit 接收端。应用侧 SDK 的地址、服务名、采样等配置仍需在应用的启动参数或环境变量中设置，具体见对应语言文档。

cp /usr/local/datakit/conf.d/samples/ddtrace.conf.sample /usr/local/datakit/conf.d/ddtrace.conf

[[inputs.ddtrace]]
  ## DDTrace Agent endpoints register by version respectively.
  ## Endpoints can be skipped listen by remove them from the list.
  ## NOTE: DO NOT EDIT.
  endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]

  ## OpenLineage is available at POST /openlineage/api/v1/lineage whenever this input is enabled.
  ## Maximum received OpenLineage body size in MiB, before decompression. Default: 64.
  # max_lineage_body_mb = 64

  ## customer_tags selects span meta and metrics keys to promote.
  ## String meta values are added as tags, while numeric metrics values are added as fields.
  ## All . will replace to _ ,like this : "project.name" to send to center is "project_name"
  # customer_tags = ["sink_project", "custom_dd_tag", "reg:key_*"]

  ## Keep rare tracing resources list switch.
  ## If some resources are rare enough(not presend in 1 hour), those resource will always send
  ## to data center and do not consider samplers and filters.
  # keep_rare_resource = false

  ## By default every error presents in span will be send to data center and omit any filters or
  ## sampler. If you want to get rid of some error status, you can set the error status list here.
  # omit_err_status = ["404"]

  ## compatible otel: It is possible to compatible OTEL Trace with DDTrace trace.
  ## make span_id and parent_id to hex encoding.
  # compatible_otel=true

  ##  It is possible to compatible B3/B3Multi TraceID with DDTrace.
  # trace_id_64_bit_hex=true

  ## api:/telemetry/proxy/api/v2/apmtelemetry is collect jvm metadata.
  ## data is: app-dependencies-loaded,app-client-configuration-change,app-integrations-change ...
  ## default is true.
  # apmtelemetry_route_enable = true

  ## When true, the tracer generates 128 bit Trace IDs, 
  ## and encodes Trace IDs as 32 lowercase hexadecimal characters with zero padding.
  ## default is true.
  # trace_128_bit_id = true

  ## delete trace message
  # del_message = true

  ## max spans limit on each trace. default 100000 or set to -1 to remove this limit.
  # trace_max_spans = 100000

  ## max trace body(Content-Length) limit. default 32MiB or set to -1 to remove this limit.
  # max_trace_body_mb = 32

  ## Rejected sampling priorities that bypass DDTrace's early drop decision.
  ## Supported values are -3, -1, and 0. Empty by default to preserve the current behavior.
  ## Set it to [0] to bypass the early drop for priority 0. A bypassed trace still goes
  ## through subsequent DataKit filters and samplers.
  # sampling_priority_drop_excludes = []

  ## tracing_metric_enable: trace_hits trace_hits_by_http_status trace_latency trace_errors trace_errors_by_http_status trace_apdex.
  ## Extract the above metrics from the collection traces.
  # tracing_metric_enable = true

  ## Receive client stats at POST /v0.6/stats. Disabled by default.
  ## When enabled without priority-drop exclusions or tracing_metric_qps_enable,
  ## /info advertises Agent 7.65.0 and client_drop_p0s=true so Java computes stats.
  ## Java may drop P0 traces client-side; error traces can still be sent.
  # client_stats_enable = false

  ## Optional PeerTags and AdditionalMetricTags copied to client stats metrics.
  # client_stats_tag_whitelist = []

  ## Metric aggregation window, from 1s to 60s. Default is 60s.
  ## Metrics are reported every max(10s, tracing_metric_interval).
  # tracing_metric_interval = "60s"

  ## Blacklist of metric tags: There are many labels in the metric: "tracing_metrics".
  ## If you want to remove certain tag, you can use the blacklist to remove them.
  ## By default, it includes: source,span_name,env,service,status,version,resource,http_status_code,http_status_class
  ## and "customer_tags", k8s related tags, and others service.
  # tracing_metric_tag_blacklist = ["resource","operation","tag_x"]

  ## Whitelist of metric tags: There are many labels in the metric: "tracing_metrics".
  # tracing_metric_tag_whitelist = []

  ## Latency bucket upper bounds are cumulative and measured in microseconds.
  ## Span kind filtering applies only to matched interface rules.
  # tracing_metric_latency_buckets = [100000, 500000, 1000000, 1200000, 1800000, 3000000, 5000000]
  # tracing_metric_latency_span_kinds = ["server"]

  ## Collect the QPS of spans that contain http.method or http.status_code.
  ## The points use one-second buckets and follow the metric reporting interval.
  # tracing_metric_qps_enable = false

  ## Tags used to group QPS. Avoid high-cardinality tags such as http_url and user ID.
  # tracing_metric_qps_tags = ["service", "env", "version", "span_kind", "http_method", "http_status_code"]

  ## Maximum distinct QPS tag combinations kept in one reporting window.
  ## Additional combinations are aggregated into qps_overflow=true.
  ## If metric output remains blocked, each shard retains at most 120 second buckets.
  ## Older data is counted by datakit_input_ddtrace_qps_dropped_spans_total.
  # tracing_metric_qps_max_series = 1000

  ## Ignore tracing resources map like service:[resources...].
  ## The service name is the full service name in current application.
  ## The resource list is regular expressions uses to block resource names.
  ## If you want to block some resources universally under all services, you can set the
  ## service name as "*". Note: double quotes "" cannot be omitted.
  # [inputs.ddtrace.close_resource]
  #   service1 = ["resource1", "resource2", ...]
  #   service2 = ["resource1", "resource2", ...]
  #   "*" = ["close_resource_under_all_services"]
  #   ...

  ## Sampler config uses to set global sampling strategy.
  ## sampling_rate used to set global sampling rate.
  # [inputs.ddtrace.sampler]
  #   sampling_rate = 1.0

  # [inputs.ddtrace.tags]
  #   key1 = "value1"
  #   key2 = "value2"
  #   ...

  ## Threads config controls how many goroutines an agent cloud start to handle HTTP request.
  ## buffer is the size of jobs' buffering of worker channel.
  ## threads is the total number fo goroutines at running time.
  # [inputs.ddtrace.threads]
  #   buffer = 100
  #   threads = 8

  ## Storage config a local storage space in hard dirver to cache trace data.
  ## path is the local file path used to cache data.
  ## capacity is total space size(MB) used to store data.
  # [inputs.ddtrace.storage]
  #   path = "./ddtrace_storage"
  #   capacity = 5120

  ## Interface rules match exact service/resource pairs and may override the default buckets.
  ## Put rule tables last: TOML assigns subsequent keys to the most recent table.
  # [[inputs.ddtrace.tracing_metric_latency_bucket_rules]]
  #   service = "checkout"
  #   resource = "GET /pay"
  #   buckets = [100000, 1200000, 1800000, 3000000, 5000000]

customer_tags 用于将指定的 span meta 和 metrics 字段提升到一级。meta 字符串写入标签，metrics 数值写入字段；未匹配的内容继续保留在 message 中。普通字段名中的 . 会自动转为 _，例如 http.route 会变为 http_route。正则必须以 reg: 开头，并使用 Go 正则表达式；例如 reg:^key_.*$ 匹配所有以 key_ 开头的字段。请先在测试环境验证正则，非法表达式会使采集器无法正常初始化。

sampling_priority_drop_excludes 用于配置不在 DDTrace 早期判断处删除的上游拒绝采样优先级，支持 -3、-1 和 0。默认为空数组，保持对这三个值的现有删除行为；例如配置 [0] 后，priority=0 的 trace 将进入 DataKit 后续过滤和采样流程，而不是强制保留。该配置不能恢复上游未发送的 span，并且可能明显增加上报数据量。

DataKit 自身指标 datakit_input_ddtrace_sampling_priority_trace_total 和 datakit_input_ddtrace_sampling_priority_span_total 通过 priority、action (drop/bypass) 和 service 标签记录这一决策。它们能证明 DataKit 收到并删除或放行了多少数据，但不能证明 priority=0 的值一定来自 W3C traceparent。

客户端 Stats 接收（预览）¶

client_stats_enable = true 会注册 POST /v0.6/stats，接收 dd-trace-java 的 MessagePack 客户端聚合统计。此功能默认关闭，GET /v0.6/stats 仍返回 404。请求体上限为 2 MiB；超限返回 413，数据或 DDSketch 无效返回 400，指标输出失败返回 503。成功接收后按 RuntimeID + Sequence 在内存中去重（最多 4096 个、保留两小时）；该去重不保证跨 DataKit 重启的 exactly-once。

[[inputs.ddtrace]]
client_stats_enable = true
client_stats_tag_whitelist = ["db.system"]

可用环境变量 ENV_INPUT_DDTRACE_CLIENT_STATS_ENABLE=true 和 ENV_INPUT_DDTRACE_CLIENT_STATS_TAG_WHITELIST='["db.system"]' 设置。标签白名单只控制 Java 载荷中的 PeerTags 和 AdditionalMetricTags，输出时这些标签带 extra_ 前缀；默认不复制。每包最多 32 个桶、256 个聚合条目，每条最多 16 个扩展标签，字符串最长 512 字节。这些限制在分配结构体数组之前检查，重复字段也消耗同一累计预算。最多并发处理 4 个请求，以限制接收开销。指标序列总量上限为 4096；新增序列超过上限时返回 429，而不是静默丢弃。

计数输出到 ddtrace_client_stats：hits、errors、top_level_hits、duration_ns 和 bucket_duration_ns。这些都是每个 Java 时间桶的增量，时间戳采用载荷的 Start（纳秒）。分布输出到 ddtrace_client_stats_latency：按 status=ok/error 和 le 输出累计字段 latency_bucket，le 单位为微秒，包含 +Inf 桶。DDSketch 转固定桶时以 sketch bin 的代表值归桶，阈值附近存在近似误差。服务端请求量应筛选 span_kind=server 并汇总 hits；错误率应以 sum(errors)/sum(hits) 计算。不要对单进程 P99 求平均，也不要把这些指标与从 Span 派生的 tracing_metrics 相加。

启用后，/info 宣告 /v0.6/stats、Agent 版本 7.65.0 和 client_drop_p0s=true，让未修改的 dd-trace-java Agent 在开启 Stats 计算时自动上报。这里的版本号是供 Java Agent 能力发现使用的兼容值，并非 DataKit 的发布版本。Java Agent 可以在客户端提前丢弃采样器或用户拒绝的 P0 Trace，从而减少 DataKit 的接收及丢弃自监控计数。Java 仍可能将错误 Trace 强制送入发送队列，而不改变其拒绝采样优先级；DataKit 对这些 Trace 继续执行原有优先级过滤。显式保留的 Trace 仍正常接收。开启客户端 Stats 时，带有 _dd.span_sampling.mechanism=8 的单 Span 采样结果会通过 DataKit 的优先级过滤和采样器，其余被拒绝的 Span 不会因此被保留；如果需要这些计数包含 P0 Trace，请关闭此功能。若 sampling_priority_drop_excludes 非空或 tracing_metric_qps_enable=true，接收接口仍可用，但 DataKit 不宣告较高版本及客户端丢弃能力，Java Agent 因而不会自动上报。Java 端设置 DD_TRACE_STATS_COMPUTATION_ENABLED=false 也会关闭自动上报。

链路指标统计与上报间隔¶

在 [[inputs.ddtrace]] 中设置 tracing_metric_interval = "30s"，可将 tracing_metrics 的常规指标统计窗口设为 30 秒。默认 60 秒，支持 1–60 秒；越界值会记录告警并回退到 60 秒。环境变量为 ENV_INPUT_DDTRACE_TRACING_METRIC_INTERVAL，例如 30s。

上报间隔为统计窗口与 10 秒中的较大值。例如，设置 1s 时每秒生成一个统计窗口、每 10 秒批量上报；设置 30s 时每 30 秒生成并上报。启用 tracing_metric_qps_enable 后，QPS 仍按秒分桶，只改变批量上报间隔。

链路指标时长单位¶

启用 tracing_metric_enable 后，tracing_metrics.latency_sum 和 latency_bucket 的 le 上界都以微秒为单位。例如，500 毫秒对应 latency_sum=500000，并计入 le="500000" 及更大的桶；每个上报的直方图序列都会输出 le="+Inf"，其值等于 latency_count。Apdex 使用 2 秒和 8 秒阈值。

早期 DDTrace 版本曾将原始纳秒时长写入这些微秒指标。升级后，如果查询或 Pipeline 曾自行将 latency_sum 或 le 除以 1000，需要移除该换算；历史数据与升级后的新数据存在单位口径差异。

自定义延迟桶与接口 SLO¶

启用 tracing_metric_enable=true 后可使用下列配置。桶边界是以微秒为单位的累计 le 上界。未配置全局桶时沿用原有默认值。规则对 service 和 resource 做精确匹配；重复规则以第一条为准。规则未设置 buckets 时继承全局桶（或内置默认桶）。未命中的 Span 继续使用全局桶和原有标签黑名单；默认情况下 resource 仍在黑名单中。

[[inputs.ddtrace]]
tracing_metric_enable = true
tracing_metric_latency_buckets = [100000, 500000, 1000000, 1200000, 1800000, 3000000, 5000000]
tracing_metric_latency_span_kinds = ["server"]

[[inputs.ddtrace.tracing_metric_latency_bucket_rules]]
service = "checkout"
resource = "GET /pay"
buckets = [100000, 1200000, 1800000, 3000000, 5000000]

以上选项写在已有的 [[inputs.ddtrace]] 表中。对应环境变量为 ENV_INPUT_DDTRACE_TRACING_METRIC_LATENCY_BUCKETS（JSON 数字数组）、ENV_INPUT_DDTRACE_TRACING_METRIC_LATENCY_BUCKET_RULES（包含 service、resource、buckets 的 JSON 对象数组）和 ENV_INPUT_DDTRACE_TRACING_METRIC_LATENCY_SPAN_KINDS（JSON 字符串数组）。规则环境变量示例：'[{"service":"checkout","resource":"GET /pay","buckets":[100000,1200000]}]'。

命中规则的 Span 只统计一次，生成独立的 hits、errors、latency 序列，并统一带有 service、resource、status（ok 或 error）、env、version、source=ddtrace 标签。其 latency_count、latency_bucket、hits、errors 使用相同的接口维度和 Span 范围。阈值为 1.2 秒时，将 le="1200000" 且 status="ok" 的 latency_bucket 求和得到 good；将两种状态的 latency_count 或 hits 求和得到 total。status 根据 DDTrace Span 的错误标志确定。每个直方图序列包含与 latency_count 相等的 le="+Inf" 桶。规则序列不生成 Apdex 和 HTTP 状态码专用计数器。

tracing_metric_latency_span_kinds 按 Span 的 span.kind（或 span_kind）元数据过滤命中接口规则的 Span。设置为 ["server"] 时，非 server Span 不进入目标接口 SLO；未命中规则的 Span 仍按原有方式统计。这里不以 span_type=entry 判断入口。空列表保持原有行为，未配置规则时该选项不生效。指标在 DataKit 采样决策之前生成，但无法统计上游 Agent 未发送的 Span；现有的单条 Trace Span 数量上限仍会先作用于指标生成。

每组桶最多 50 个，必须为有限正数并严格递增；最多使用 32 条精确匹配规则。无效的全局桶会回退到内置默认值，无效规则会被忽略并记录日志。建议只为稳定的路由名称配置规则：每条规则可能额外产生约 (桶数 + 1) × status × env × version 条时间线，以及计数器时间线。不要使用用户 ID 或原始 URL 作为 SLO 资源名。

HTTP QPS 统计¶

在已有的 [[inputs.ddtrace]] 配置中启用以下选项，即可向 tracing_metrics 指标集上报 qps 字段（source=ddtrace）。该功能默认关闭，独立于 tracing_metric_enable：

tracing_metric_qps_enable = true
tracing_metric_qps_tags = ["service", "env", "version", "span_kind", "http_method", "http_status_code"]
tracing_metric_qps_max_series = 1000

• 统计 DataKit 收到的 HTTP span：只要 http.method 或 http.status_code 非空即计数，兼容对应的下划线字段名。客户端和服务端 span 都会计数，不限于入口 span，因此不等于去重后的业务请求数。
• 在 DataKit 的 trace 截断、采样和 sampling_priority 丢弃之前计数；应用侧未上报的 span 无法统计。
• 按秒统计，按上述上报间隔批量上报，每个点的 qps 是该秒内的 span 数量；没有数据的秒不补零。通常按接收时间分桶，启用本地缓存时按消费时间统计，不使用 span 的开始时间。SDK 批量发送或缓存积压可能使数据集中在某些秒内。
• tracing_metric_qps_tags 决定分组维度。达到 tracing_metric_qps_max_series 限制后，新增标签组合会合并到带有 qps_overflow=true 的序列中。避免使用 URL、用户 ID 等高基数标签。

多线路工具串联注意事项¶

DDTrace 传统 Trace ID 为 64 位整数；W3C tracecontext 使用 128 位、32 个十六进制字符的 Trace ID。DDTrace 载荷会把高 64 位放在 _dd.p.tid 中，DataKit 需要据此重建完整的 128 位 ID。

请让调用链上的 SDK 使用一致的透传协议，并按实际协议配置 DataKit：

• 使用 tracecontext 与 OpenTelemetry 串联时，启用 compatible_otel=true，以十六进制格式输出 span 和父 span ID；trace_128_bit_id 默认已启用，用于拼接 _dd.p.tid 与低 64 位 Trace ID。
• 使用 b3multi 且上游发送 64 位十六进制 Trace ID 时，启用 trace_id_64_bit_hex=true。
• 变更协议后，用一个跨服务请求验证 Trace ID 与 parent ID 是否连续；协议不一致通常表现为服务拓扑断开，而不是 DataKit 收不到数据。

更多协议组合见多链路串联。

注入 Pod 和 Node 信息¶

当应用部署在 Kubernetes 等容器环境时，可通过 Downward API 将 Pod、Namespace 和 Node 信息写入 DD_TAGS。这些字段会随应用侧 span 发送；如需在链路列表中作为一级标签筛选，再在 DataKit 的 customer_tags 中显式添加相应字段。

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  selector:
    matchLabels:
      app: my-app
  replicas: 3
  template:
    metadata:
      labels:
        app: my-app
        service: my-service
    spec:
      containers:
        - name: my-app
          image: my-app:v0.0.1
          env:
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: NODE_NAME
              valueFrom:
                fieldRef:
                  fieldPath: spec.nodeName
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: DD_TAGS
              value: pod_name:$(POD_NAME),pod_namespace:$(POD_NAMESPACE),host:$(NODE_NAME)
            - name: DD_SERVICE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['service']

变量替换只能引用同一容器中先定义的环境变量，因此应先定义 POD_NAME、POD_NAMESPACE 和 NODE_NAME，再定义 DD_TAGS。

应用启动后，进入对应的 Pod，我们可以验证 ENV 是否生效：

$ env | grep DD_
...

一旦注入成功，在最终的 Span 数据中，我们就能看到该 Span 所处的 Pod 以及 Node 名称。

endpoints = ["/v0.3/traces", "/v0.4/traces", "/v0.5/traces"]

# [inputs.ddtrace.sampler]
# sampling_rate = 1.0

HTTP 设置¶

DataKit 默认监听 localhost:9529。若 trace 来自远端主机或其他 Pod，需要在 datakit.conf 的 [http_api] 中设置应用可达的监听地址，例如：

[http_api]
  listen = "0.0.0.0:9529"

仅在受控网络中使用该配置：trace 端点不应直接暴露到公网，生产环境应使用防火墙、安全组、Kubernetes Service/NetworkPolicy 或 TLS 进行访问控制。DataKit 默认接收 /v0.3/traces、/v0.4/traces 和 /v0.5/traces，除非明确了解兼容性影响，否则不要修改 endpoints。

如果有 DDTrace 数据发送给 DataKit，那么在 DataKit 的 monitor 上能看到：

开启磁盘缓存¶

磁盘缓存用于在瞬时流量较高时延后处理 HTTP 请求体，降低内存和处理峰值；它不是长期归档，也不能替代应用侧采样。目录必须可写、具备足够空间，并应位于容器重建后仍可保留的卷上（如确有恢复需求）。capacity 单位为 MiB。

[inputs.ddtrace.storage]
  path = "/path/to/ddtrace-disk-storage"
  capacity = 5120

DDTrace SDK 配置¶

配置完采集器后，再配置 SDK。不同语言对变量的支持和优先级略有差异；下列变量是通用概念，最终以所用语言 SDK 的版本文档为准。若 SDK 支持 DD_TRACE_AGENT_URL，该 URL 通常优先于主机和端口配置，避免同时设置相互冲突的值。

环境变量设置¶

除了在应用初始化时设置项目名，环境名以及版本号外，还可通过如下两种方式设置：

• 通过命令行注入环境变量

DD_TAGS="project:your_project_name,env=test,version=v1" ddtrace-run python app.py

• 在 ddtrace.conf 中直接配置接收端标签。这种方式会影响所有进入该 DataKit 的 DDTrace 数据，适合注入统一的部署标签；不要用它表达某个应用独有的服务信息：

# tags is ddtrace configed key value pairs
[inputs.ddtrace.tags]
  some_tag = "some_value"
  more_tag = "some_other_value"

APMTelemetry¶

Version-1.35.0 · Experimental

Java Agent 可以通过 /telemetry/proxy/api/v2/apmtelemetry 上报启动配置、心跳、依赖与已加载集成等元数据。DataKit 默认接收该路由；如不需要，可关闭 apmtelemetry_route_enable。数据可在 观测云 基础设施的资源目录中查看，适合排查启动命令、依赖版本和探针加载情况。

语言不同和版本不同数据可能会有很大的差异，以实际收到的数据为准。

固定提取 tag¶

从 DataKit 版本 1.21.0 开始，不再把 Span.Meta 的所有字段提升为一级标签，而是仅提取下列常用字段，以控制标签基数和索引成本。

以下是可能会提取出的标签列表：

未在列表中的字段仍保留在 span 的 meta 中，可在链路详情中查看；是否能作为一级标签筛选取决于界面与索引配置。

从 DataKit 版本 1.22.0 起，可通过 customer_tags 增加白名单字段。提取后字段名中的 . 会变成 _；请只添加稳定且低基数的字段，避免把用户 ID、请求 ID 等高基数字段提升为标签。

常见排障路径¶

数据采集字段说明¶

链路¶

ddtrace¶

以下是采集上来的 tracing 字段说明

指标¶

tracing_metrics¶

基于 DDTrace 统计得到的指标数据，它记录了所产生的 span 计数、span 耗时等指标

ddtrace_client_stats¶

Java 客户端统计时间桶内的增量指标

ddtrace_client_stats_latency¶

客户端 DDSketch 转换得到的近似累计延迟桶

资源对象¶

扩展版 Java Agent 启动后可上报自身配置、集成列表、依赖关系和服务元数据。当前该类资源对象仅适用于 Java Agent，常见事件如下：

• app_client_configuration_change 其中包含 Agent 的配置信息
• app_dependencies_loaded 依赖列表，包括包名和版本信息
• app_integrations_change 集成列表，包括包名和是否开启探针
• 其他主机信息和服务等信息

tracing_service¶

采集 DDTrace 的 Service、Host、进程等配置信息

延伸阅读¶

• DataKit Tracing 字段定义
• DataKit 通用 Tracing 数据采集说明
• 正确使用正则表达式来配置
• 多链路串联
• Java 接入与异常说明
• DDTrace 采样策略和多链路工具串联注意事项

DDTrace 是由 Datadog 发起并开源的链路追踪项目，相关著作权归 Datadog 及其他贡献者所有。观测云支持 DDTrace 的数据上报，具体使用遵循相应项目的开源许可证。