Vector datadog_agent 源组件：接收 Datadog Agent 的日志、指标与追踪数据-创锋一号

Vector datadog_agent 源组件：接收 Datadog Agent 的日志、指标与追踪数据

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

本文以 Vector 的datadog_agent源组件文档为主体，完整覆盖其配置参数、Datadog Agent 侧的接入方法、HTTP 端点与事件字段语义、超时处理机制等核心内容，并结合当前仓库中src/sources/datadog_agent/的源码实现，说明日志/指标/追踪的解码链路、API Key 提取逻辑与内部指标来源，帮助你在现有 Datadog Agent 采集体系下，把观测数据改道或分流进 Vector 管道。

组件概览

datadog_agent源通过 HTTP/HTTPS 接收由 Datadog Agent 采集的观测数据，可同时承载三类（外加 LLM Observability）事件流：

日志（logs）：JSON 编码的日志批次，接收来自/v1/input/（旧路径）与/api/v2/logs/（新路径）的 POST 请求；
指标（metrics）：支持/api/v1/series、/api/v2/series（v2 为 Protobuf 编码）与/api/beta/sketches（DDSketch 分布直方图）三类端点；
追踪（traces）：接收/api/v0.2/traces的 Protobuf 追踪负载；
LLM Observability（llmobs）：接收/api/v2/llmobs及evp_proxy代理路径下的 LLM 观测事件。

以上端点划分可直接在源码的build_warp_filters及四个子模块 logs.rs、metrics.rs、traces.rs、llmobs.rs 中确认。

组件的关键属性（来自生成文档所用的 CUE 数据 website/cue/reference/components/sources/datadog_agent.cue）：

属性	值	说明
开发状态	stable	稳定组件
投递语义	at_least_once	至少一次投递
出口方式	batch	以批为单位向下游发送
部署角色	aggregator, sidecar	适合作为聚合器或 sidecar 部署
默认监听端口	8080	见配置示例
传输协议	HTTP	支持可选 TLS
分帧（framing）	默认`bytes`	按 HTTP body 整体解码
多行支持	不支持	multiline 未启用
端到端确认	支持	acknowledgements 可用

配置参数详解

该组件的完整配置定义由 src/sources/datadog_agent/mod.rs 中的DatadogAgentConfig结构体描述，参数元数据同时收录在 website/cue/reference/components/sources/generated/datadog_agent.cue。逐项说明如下：

参数	类型	默认值	说明
`address`	string	必填	监听的 socket 地址，必须包含端口，如`0.0.0.0:80`、`localhost:80`
`tls`	object	无	配置入站连接的 TLS 选项（`TlsEnableableConfig`），不启用则使用纯 HTTP
`store_api_key`	bool	`true`	当事件携带 Datadog API key 时，将其存入事件元数据；若事件随后发往 Datadog sink，该 key 会被复用
`disable_logs`	bool	`false`	设为`true`时不再接收日志
`disable_metrics`	bool	`false`	设为`true`时不再接收指标
`disable_traces`	bool	`false`	设为`true`时不再接收追踪
`disable_llmobs`	bool	`false`	设为`true`时不再接收 LLM Observability 事件
`multiple_outputs`	bool	`false`	设为`true`时，日志/指标/追踪（及 llmobs）分别写入不同输出端口
`parse_ddtags`	bool	`false`	设为`true`时，日志事件中的`ddtags`字符串（逗号分隔的 key:value 标签列表）会被解析展开为数组
`split_metric_namespace`	bool	`true`	设为`true`时，指标名在第一个`.`处切分为 namespace 与 name，如`system.cpu.usage`→ namespace`system`+ name`cpu.usage`；若下游 sink 使用默认 namespace，可设为`false`保留完整指标名
`send_timeout_secs`	float	无	向下游发送事件的超时时间（秒），超时后以 HTTP 503 响应，详见下文“请求超时处理”
`framing`	object	`bytes`	HTTP body 的分帧配置
`decoding`	object	无	原始字节的解码配置；部分解码器还能决定事件输出类型（log/metric/trace）
`keepalive`	object	默认	HTTP 服务 keepalive 参数（TCP keepalive、`max_connection_age_secs`等）
`acknowledgements`	bool	无	已废弃。源级开关对确认行为没有效果，请在全局配置或 sink 级启用确认

注意：disable_logs、disable_metrics、disable_traces、disable_llmobs不能同时全为true，源码中会直接报错 "At least one of the supported data type shall be enabled"（见 mod.rs 的build_warp_filters）。

配置示例

sources: dd_agent: type: datadog_agent address: 0.0.0.0:9000 # 必须包含端口，Datadog Agent 将向此地址发数据 tls: # 可选：启用后 Datadog Agent 需使用 https URL enabled: true cert_file: /path/to/cert.pem key_file: /path/to/key.pem multiple_outputs: true # 日志/指标/追踪/llmobs 分端口输出 parse_ddtags: true # 将 ddtags 字符串展开为数组 split_metric_namespace: true # 指标名按第一个 '.' 拆分为 namespace/name store_api_key: true # 提取 Datadog API key 供下游 Datadog sink 复用 send_timeout_secs: 8 # 建议小于 Agent 侧超时（默认 10 秒）

启用multiple_outputs后，若源组件名为dd_agent，下游可通过dd_agent.logs、dd_agent.metrics、dd_agent.traces、dd_agent.llmobs分别引用对应输出流（CUE 数据中 outputs 一节完整定义了这四个端口及默认输出端口的语义）。

配置 Datadog Agent

向该源发送日志或指标要求 Datadog Agentv7.35 / 6.35 或更高版本；如果你的 Datadog Agent 默认压缩模式为zstd，还需要 Vector0.40.2 或更高版本。

发送日志，在 Datadog Agent 配置中加入：

vector: logs.enabled: true logs.url: http://"<VECTOR_HOST>:<SOURCE_PORT>" # Vector 源启用 SSL 时改为 https

发送指标：

vector: metrics.enabled: true metrics.url: http://"<VECTOR_HOST>:<SOURCE_PORT>" # Vector 源启用 SSL 时改为 https

发送追踪：

vector: traces.enabled: true traces.url: http://"<VECTOR_HOST>:<SOURCE_PORT>" # Vector 源启用 SSL 时改为 https

压缩编码与空载荷处理

从源码 mod.rs 的decode方法看，Vector 会按content-encoding头从右向左依次解码identity、gzip/x-gzip、zstd、deflate/x-deflate编码，遇到不支持的编码返回 415 Unsupported Media Type。源码注释明确指出所有解压都经过CappedDecoder限制解压后大小上限，目的是防止在这个无认证 HTTP 监听器上利用压缩炸弹造成无限制内存分配。

另外，Datadog Agent 会以空载荷（或logs场景下的{}）作为 keep alive 心跳，logs.rs 与 metrics.rs 均显式忽略空 body 并直接返回成功，不会报错。

日志事件字段

日志请求体是一个 JSON 数组，每个元素由 mod.rs 中的LogMsg结构严格解析（deny_unknown_fields），字段与输出事件的对应关系如下：

输入字段	说明	输出字段	必填
`message`	纯文本消息体	`message`	是
`status`	日志级别	`status`（语义映射为 severity）	是
`timestamp`	毫秒级 Unix 时间戳	`timestamp`	是
`hostname`	主机名	`hostname`	是
`service`	服务名	`service`	是
`ddsource`	数据来源	`ddsource`	是
`ddtags`	逗号分隔的标签列表	`ddtags`（`parse_ddtags`为`true`时展开为数组）	是

其中status被刻意在 schema 层面标注为 severity 语义（源码注释引用了 Datadog 对 status 的语义约定），timestamp、hostname、service、ddsource、ddtags分别标注为 timestamp/host/source/tags 语义，见 mod.rs 的outputs实现。parse_ddtags的解析行为有专门单元测试覆盖（logs.rs），例如filename:driver.log,debug,wizard:the_grey会展开为["filename:driver.log", "debug", "wizard:the_grey"]。

指标解码：series 与 sketches

指标端点共有三条路由（metrics.rs）：

POST /api/v1/series/...：JSON 格式，{"series": [...]}；
POST /api/v2/series/...：Protobuf 格式（MetricPayload），支持 origin 元数据与 resources 字段；
POST /api/beta/sketches/...：Protobuf 格式的 DDSketch 负载，解码为分布直方图（distribution）指标。

从实现看（metrics.rs），各 Datadog 指标类型到 Vector 指标的映射为：

Datadog 类型	Vector 映射	说明
`count`	Incremental Counter	直接转为计数器
`gauge`	Absolute Gauge	直接转为仪表值；v2 中若携带非零 interval（DogStatsD 场景），会作为 gauge 的 interval 保留
`rate`	Incremental Counter（值 × interval）	与 DogStatsD 源行为保持一致，`interval`（秒）换算为毫秒后写入 interval
DDSketch	Incremental Distribution	通过`AgentDDSketch::from_raw`还原 min/max/sum/avg 与桶结构

v2 series 的resources字段处理也值得注意：host资源会替换日志 schema 中的主机 tag，device资源保留为devicetag，其他资源类型以带前缀的通用 tag 保留（metrics.rs）。split_metric_namespace的切分逻辑由 metrics.rs 的namespace_name_from_dd_metric实现，即“解析第一个.之前的部分作为 namespace，没有分隔符则无 namespace”。

追踪与 LLM Observability

追踪负载同样由 traces.rs 处理。POST /api/v0.2/traces接收 Datadog 的TracePayloadProtobuf，源码会自动区分新旧两种 schema：

新 schema（含tracer_payloads）：每个 chunk 映射为一个TraceEvent，携带priority、origin、dropped、tags、spans数组以及container_id、language_name、tracer_version、runtime_id、app_version等负载级字段，并标记payload_version: v2；
旧 schema：每个 trace 映射为一个事件（trace_id、start_time、end_time、spans），transactions中的 APM 事件也被逐一映射，标记payload_version: v1。

每个 span 被展开为包含service、name、resource、trace_id、span_id、parent_id、start、duration、error、meta、metrics、type、meta_struct的对象（traces.rs）。

另有一条特殊路由：POST /api/v0.2/stats会被直接丢弃并返回 200 OK——源码注释说明 APM 统计是有意丢弃的，因为它们会在下游datadog_tracessink 中重新计算。

追踪支持注意事项（原文档“Trace support caveats”）：datadog_agent源能够接收 Datadog Agent 的追踪并转发到 Datadog。为保证 APM 统计（如 span 命中次数、duration 分布）准确，应在 Datadog Agent 或客户端 SDK 中禁用任何追踪采样，因为这些驱动 APM 统计的指标是由 Vector 计算的。

LLM Observability 端点（llmobs.rs）接收event_type包裹的 span 集合，兼容单个 JSON 对象与 JSON 数组两种信封形态，将每个 span 的span_id、trace_id、name、session_id、service、start_ns、duration、status、meta、metrics、tags、ml_app（从_dd.ml_app或tags中提取）等字段展开为日志事件，start_ns同时用于填充timestamp。

API Key 提取与 store_api_key

store_api_key（默认true）控制是否从请求中提取 Datadog API key。从 mod.rs 的ApiKeyExtractor看，提取优先级为：

URL 路径：正则^/v1/input/(?P<api_key>[[:alnum:]]{32})/??匹配/v1/input/<32位key>形式的旧版日志端点；
查询参数：?dd-api-key=...；
请求头：dd-api-key。

提取到的 key 通过metadata.set_datadog_api_key写入事件元数据（日志、指标、追踪、llmobs 四条链路均如此），当事件最终发往 Datadog sink 时会被直接使用——这使得“Datadog Agent → Vector → Datadog”的转发路径无需在每个 sink 中重复配置同一 API key。设为false时提取逻辑短路返回None。

请求超时处理

这是该源文档中非常实用的一个主题。当 Datadog Agent 向本源发送请求、而源在把事件送往下游 transforms/sinks 时阻塞，Agent 最终会超时并断开连接。此时默认情况下 Vector 会报 “Events dropped.” 错误并递增component_discarded_events_total内部指标。

但严格来说事件并未真正丢失：Agent 会无限重试重发该请求，只要阻塞不是永久性的，事件最终仍会被接收。为避免这种有误导性的遥测，可以将send_timeout_secs配置为小于Agent 超时（默认 10 秒）的值。此时 Vector 会：

向 Agent 返回HTTP 503 Service Unavailable；
发出warning而非 error；
递增component_timed_out_requests_total指标。

从 mod.rs 的handle_events实现可验证这一链路：SendError::Timeout触发 503 响应，SendError::Closed（服务器关闭）则拒绝请求，端到端确认场景下BatchStatus::Errored/Rejected分别映射为 500/400 响应，从而驱动 Agent 侧重试或放弃。

组件内部指标

该源暴露的内部指标（来自 CUE 数据 telemetry 一节）包括：

指标	含义
`component_timed_out_events_total`	因发送超时而被放弃/标记的事件数
`component_timed_out_requests_total`	因发送超时而被标记的请求数（配合`send_timeout_secs`产生）
`http_server_handler_duration_seconds`	HTTP 请求处理耗时
`http_server_requests_received_total`	收到的 HTTP 请求数
`http_server_responses_sent_total`	已发送的 HTTP 响应数

此外，每次成功解码都会通过EventsReceived内部事件上报事件数量与估算的 JSON 字节大小（见各模块中的events_received.emit调用）。

企业官网建设流程全解析