使用 Datadog 日志采集 API 采集事件
使用 日志采集 API 将 JSON 日志事件直接发送到 Datadog 日志管理。您可以从云应用、微服务或任何发出遥测数据的系统发送日志。日志在几秒内出现在 日志浏览器 中。使用 日志管道 处理、路由和归档这些日志。
该端点支持高吞吐量的结构化和半结构化 JSON 载荷实时采集。
此 API 支持的操作
- 无需安装 Datadog Agent,即可直接从云应用发送日志。
- 对传入数据应用管道处理器,例如 Grok 解析器、重映射器和查找处理器。
- 根据内容将日志路由到索引、归档或告警目标。
- 将此端点与采样和过滤规则结合使用,降低索引成本。
请参阅 Datadog API 和应用密钥 管理凭据。
开始之前
确认您已准备好以下内容:
-
具有日志采集权限的 Datadog API 密钥。在 组织设置 → API 密钥 中找到它。
-
您的 Datadog 站点地址。该地址因区域而异:
地区 站点地址 美国东部 datadoghq.comUS3 西部 us3.datadoghq.comUS5 中部 us5.datadoghq.com欧盟 datadoghq.euAP1 日本 ap1.datadoghq.comAP2 澳大利亚 ap2.datadoghq.com -
已安装
curl或 Postman。 -
JSON 格式的日志载荷。
管道概述
- Mermaid (图片)
- Mermaid (代码)
- ASCII
flowchart LR
A["云应用<br/>或微服务"] -->|POST /api/v2/logs| B["Datadog<br/>日志采集 API"]
B --> C["日志管道<br/>• Grok 解析器<br/>• 重映射器<br/>• 查找处理器"]
C --> D["路由引擎<br/>• 过滤器<br/>• 索引<br/>• 采样规则"]
D --> E{{"目标<br/>日志浏览器 · S3 · SIEM · 告警"}}
[云应用] POST /api/v2/logs [Datadog日志]
[或微服务] -------------------> [日志摄取 API]
|
v
[日志管道]
(Grok、重映射、
查找)
|
v
[路由引擎]
(过滤器、索引、
规则)
|
v
{ 目标 }
(日志浏览器、
SIEM、告警)
采集端点
POST https://http-intake.logs.{dd_site}/api/v2/logs
将 {dd_site} 替换为您所在区域的站点地址,例如 datadoghq.com 或 ap2.datadoghq.com。
请求头
| 请求头 | 值 | 必填 | 说明 |
|---|---|---|---|
DD-API-KEY | <your_api_key> | 是 | 您的 Datadog API 密钥 |
Content-Type | application/json | 是 | 载荷格式 |
Content-Encoding | gzip | 可选 | 压缩后的载荷格式。对于大批量数据,Datadog 推荐使用此格式。 |
请求正文
请求正文是一个 JSON 数组,包含一个或多个日志对象。每个日志对象支持以下字段:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 是 | 日志消息正文 |
ddsource | string | 推荐 | 日志来源技术的集成名称,例如 python 或 nginx |
ddtags | string | 可选 | 逗号分隔的标签,例如 env:prod,team:payments |
hostname | string | 可选 | 生成该日志的主机名称 |
service | string | 推荐 | 应用或服务的名称 |
status | string | 推荐 | 日志事件的严重级别,例如 info 或 ERROR |
timestamp | string | 可选 | 事件时间,例如 2025-11-15T08:30:00Z。请参阅时间戳格式说明。 |
请包含 message。Datadog 使用 service、ddsource 和 ddtags 过滤、分面并匹配管道。其他字段为可选。
载荷示例
[
{
"message": "Transaction failed: Gateway timeout",
"ddsource": "java",
"ddtags": "env:prod,region:us-east-1",
"hostname": "payments-host-01",
"service": "payment-gateway",
"status": "ERROR",
"timestamp": "2025-11-15T08:30:00Z",
"transaction_id": "txn_998877",
"customer_id": "cus_554433"
}
]
对 timestamp 使用国际标准化组织 (ISO) 8601 协调世界时 (UTC) 格式。Datadog 使用此值对齐日志浏览器中的日志时间线。没有时间戳的日志使用采集时间。Datadog 接受最多回溯 18 小时的时间戳。
cURL 示例
export DD_API_KEY="your_datadog_api_key_here"
export DD_SITE="datadoghq.com"
curl -X POST "https://http-intake.logs.$DD_SITE/api/v2/logs" \
-H "DD-API-KEY: $DD_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"message": "Transaction failed: Gateway timeout",
"ddsource": "java",
"ddtags": "env:prod,region:us-east-1",
"hostname": "payments-host-01",
"service": "payment-gateway",
"status": "ERROR",
"transaction_id": "txn_998877"
}
]'
响应代码
| 代码 | 状态 | 说明 |
|---|---|---|
202 | 已接受 | 载荷已接受并排队等待索引 |
400 | 错误请求 | 格式或校验错误 |
401 | 未授权 | 缺少 DD-API-KEY 请求头 |
403 | 禁止访问 | API 密钥无效或缺少日志采集权限 |
408 | 请求超时 | 请求超时。稍后重试。 |
413 | 载荷过大 | 未压缩的载荷超过 5 MB |
429 | 请求过多 | 客户端超出采集速率限制 |
500 | 内部服务器错误 | Datadog 遇到意外状况。稍后重试。 |
503 | 服务不可用 | Datadog 已达容量上限。稍后重试。 |
202 已接受
202 Accepted 响应确认 Datadog 已收到载荷。响应正文包含一个空的 JSON 对象。日志事件在几秒内出现在日志浏览器中。
HTTP/1.1 202 Accepted
Content-Type: application/json
{}
400 错误请求
当载荷未通过校验时,Datadog 返回此代码:
- JSON 语法错误或字符未转义。
- 载荷缺少必填的
message字段。 - 未压缩的载荷超过 5 MB 上限。
{
"errors": [
{
"detail": "Invalid JSON",
"status": "400",
"title": "Bad Request"
}
]
}
401 未授权和 403 禁止访问
缺少 DD-API-KEY 请求头时,Datadog 返回 401 Unauthorized。API 密钥校验失败或缺少日志采集权限时,Datadog 返回 403 Forbidden:
{
"errors": [
{
"detail": "Forbidden",
"status": "403",
"title": "Forbidden"
}
]
}
413 载荷过大
请求载荷未压缩时超过 5 MB,Datadog 返回此代码。
{
"errors": [
{
"detail": "Payload too large",
"status": "413",
"title": "Payload Too Large"
}
]
}
429 请求过多
您发送的请求过多。请减少请求数量,或将日志对象批量打包到一个数组载荷中。
其他可重试错误
对于瞬时故障,Datadog 还会返回 408 Request Timeout、500 Internal Server Error 和 503 Service Unavailable。请使用指数退避重试请求。如果 408 Request Timeout 持续出现,请减小批次大小。
批量发送日志事件
通过传入数组,在单次请求中最多发送 1,000 条日志条目。Datadog 建议高吞吐量服务采用此方式。
[
{
"message": "User login succeeded",
"service": "auth-service",
"ddsource": "python",
"ddtags": "env:prod",
"status": "INFO"
},
{
"message": "Transaction failed: Gateway timeout",
"service": "payment-gateway",
"ddsource": "python",
"ddtags": "env:prod",
"status": "ERROR",
"transaction_id": "txn_998877"
}
]
限制:
- 载荷大小:未压缩时 5 MB
- 单条日志大小:1 MB
- 数组条目:1,000 个日志对象
常见用例
- 无需部署 Datadog Agent,即可采集微服务的日志。
- 从无服务器函数发送结构化 JSON 事件,例如亚马逊云科技 (AWS) Lambda 或 Google Cloud Run。
- 从物联网设备或边缘服务流式传输遥测数据。
- 通过日志管道将增强后的事件路由到安全信息和事件管理 (SIEM)、S3 或告警目标。
- 从持续集成和持续交付 (CI/CD) 管道或部署脚本提交日志。
故障排除
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
401 Unauthorized | API 密钥错误或缺失 | 在 组织设置 → API 密钥 中验证 DD_API_KEY |
400 Bad Request | JSON 格式错误 | 发送前使用 jq . payload.json 检查 |
| 日志未出现在日志浏览器中 | 管道过滤器排除了该日志 | 清除过滤器。然后检查索引路由规则。 |
| 时间戳顺序错误 | 非 UTC 或非 ISO 8601 格式,或早于 18 小时 | 使用 "2025-11-15T08:30:00Z" 格式。在事件发生后 18 小时内发送日志。 |
429 Too Many Requests | 超出速率限制 | 将日志对象批量打包到一个数组载荷中 |