跳到主要内容

使用 Datadog 日志采集 API 采集事件

使用 日志采集 API 将 JSON 日志事件直接发送到 Datadog 日志管理。您可以从云应用、微服务或任何发出遥测数据的系统发送日志。日志在几秒内出现在 日志浏览器 中。使用 日志管道 处理、路由和归档这些日志。

该端点支持高吞吐量的结构化和半结构化 JSON 载荷实时采集。

此 API 支持的操作​

  • 无需安装 Datadog Agent,即可直接从云应用发送日志。
  • 对传入数据应用管道处理器,例如 Grok 解析器、重映射器和查找处理器。
  • 根据内容将日志路由到索引、归档或告警目标。
  • 将此端点与采样和过滤规则结合使用,降低索引成本。
备注

请参阅 Datadog API 和应用密钥 管理凭据。

开始之前​

确认您已准备好以下内容:

  • 具有日志采集权限的 Datadog API 密钥。在 组织设置 → API 密钥 中找到它。

  • 您的 Datadog 站点地址。该地址因区域而异:

    地区站点地址
    美国东部datadoghq.com
    US3 西部us3.datadoghq.com
    US5 中部us5.datadoghq.com
    欧盟datadoghq.eu
    AP1 日本ap1.datadoghq.com
    AP2 澳大利亚ap2.datadoghq.com
  • 已安装 curl 或 Postman。

  • JSON 格式的日志载荷。

管道概述​

Datadog 日志采集管道

采集端点​

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-Typeapplication/json是载荷格式
Content-Encodinggzip可选压缩后的载荷格式。对于大批量数据,Datadog 推荐使用此格式。

请求正文​

请求正文是一个 JSON 数组,包含一个或多个日志对象。每个日志对象支持以下字段:

字段类型必填说明
messagestring是日志消息正文
ddsourcestring推荐日志来源技术的集成名称,例如 python 或 nginx
ddtagsstring可选逗号分隔的标签,例如 env:prod,team:payments
hostnamestring可选生成该日志的主机名称
servicestring推荐应用或服务的名称
statusstring推荐日志事件的严重级别,例如 info 或 ERROR
timestampstring可选事件时间,例如 2025-11-15T08:30:00Z。请参阅时间戳格式说明。
备注

请包含 message。Datadog 使用 service、ddsource 和 ddtags 过滤、分面并匹配管道。其他字段为可选。

载荷示例​

Payload: single log
[
{
"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 示例​

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 对象。日志事件在几秒内出现在日志浏览器中。

Response: 202 Accepted
HTTP/1.1 202 Accepted
Content-Type: application/json
Response body: 202 Accepted
{}

400 错误请求​

当载荷未通过校验时,Datadog 返回此代码:

  • JSON 语法错误或字符未转义。
  • 载荷缺少必填的 message 字段。
  • 未压缩的载荷超过 5 MB 上限。
Response: 400 Bad Request
{
"errors": [
{
"detail": "Invalid JSON",
"status": "400",
"title": "Bad Request"
}
]
}

401 未授权和 403 禁止访问​

缺少 DD-API-KEY 请求头时,Datadog 返回 401 Unauthorized。API 密钥校验失败或缺少日志采集权限时,Datadog 返回 403 Forbidden:

Response: 403 Forbidden
{
"errors": [
{
"detail": "Forbidden",
"status": "403",
"title": "Forbidden"
}
]
}

413 载荷过大​

请求载荷未压缩时超过 5 MB,Datadog 返回此代码。

Response: 413 Payload Too Large
{
"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 建议高吞吐量服务采用此方式。

Payload: batched logs
[
{
"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 UnauthorizedAPI 密钥错误或缺失在 组织设置 → API 密钥 中验证 DD_API_KEY
400 Bad RequestJSON 格式错误发送前使用 jq . payload.json 检查
日志未出现在日志浏览器中管道过滤器排除了该日志清除过滤器。然后检查索引路由规则。
时间戳顺序错误非 UTC 或非 ISO 8601 格式,或早于 18 小时使用 "2025-11-15T08:30:00Z" 格式。在事件发生后 18 小时内发送日志。
429 Too Many Requests超出速率限制将日志对象批量打包到一个数组载荷中

下一步​