跳到主要内容

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

使用 Datadog 日志采集应用程序接口 (API)，将 JSON 日志事件直接发送到 Datadog 日志管理平台。您可以采集来自云应用、微服务或任何生成遥测数据的系统的日志。日志采集完成后，几秒钟内即可在 日志浏览器 中查看。 您可以使用 日志管道 对日志进行处理、路由和归档。

该端点支持结构化及半结构化 JSON 有效载荷的高吞吐量、实时摄取。

此 API 支持的操作​

  • 无需安装 Datadog 代理，即可直接从云应用发送日志。
  • 对传入的数据应用管道处理器，例如 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可选压缩有效载荷格式（推荐用于大容量批次）

请求正文​

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

字段类型必填描述
messagestring是的日志消息正文
ddsourcestring推荐日志来源的技术，例如 python 或 nginx。
ddtagsstring可选用逗号分隔的标签，例如 env:prod,team:payments。
hostnamestring可选生成该日志的主机名称
servicestring推荐应用或服务的名称
备注

您必须包含 message 字段。所有其他字段均为可选，但 Datadog 建议使用它们。Datadog 使用 service、ddsource 和 ddtags 进行过滤、分面和管道匹配。

有效载荷示例​

Payload: single log
[
  {
    "message": "Transaction failed: Gateway timeout",
    "ddsource": "payment-gateway",
    "ddtags": "env:prod,region:us-east-1",
    "hostname": "payments-host-01",
    "service": "payment-gateway",
    "timestamp": "2025-11-15T08:30:00Z",
    "transaction_id": "txn_998877",
    "customer_id": "cus_554433",
    "level": "ERROR"
  }
]
备注

timestamp 必须采用国际标准化组织 (ISO) 8601 协调世界时 (UTC) 格式。Datadog 在 Log Explorer 中使用此格式进行时间线对齐。对于未包含时间戳的日志，Datadog 会根据导入时间对其进行索引。

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": "payment-gateway",
      "ddtags": "env:prod,region:us-east-1",
      "hostname": "payments-host-01",
      "service": "payment-gateway",
      "level": "ERROR",
      "transaction_id": "txn_998877"
    }
  ]'

响应代码​

CodeStatus描述
202Accepted已接收有效载荷并将其加入索引队列
400Bad request格式或验证错误
401 / 403Unauthorized / Forbidden缺少 API 密钥（401）或密钥无效/权限不足（403）
413Payload too large未压缩的有效载荷超过 5 MB（gzip 压缩后为 50 MB）
429Too many requests摄入速率超过限制

202 已接受​

202 Accepted 响应表明 Datadog 已收到有效载荷。该响应的正文为空。日志事件将在几秒钟内显示在 Log Explorer 中。

Response: 202 Accepted
HTTP/1.1 202 Accepted

400 请求错误​

当有效负载存在格式或验证错误时，Datadog 会返回以下代码：

  • JSON 语法错误或存在未转义的字符。
  • 缺少必填字段 message。
  • 未压缩的有效载荷超过了 5 MB 的限制。
Response: 400 Bad Request
{
  "errors": ["Invalid JSON"]
}

401 未授权和 403 禁止访问​

如果缺少 DD-API-KEY 头，Datadog 将返回 401 未授权。如果 API 密钥无效或缺乏日志采集权限，Datadog 将返回 403 禁止访问：

Response: 403 Forbidden
{
  "errors": ["Forbidden"]
}

413 有效载荷过大​

当请求负载超过最大大小限制时，Datadog 会返回此代码：未压缩的 JSON 数据为 5 MB，gzip 压缩的数据为 50 MB。

Response: 413 Payload Too Large
{
  "errors": ["Payload too large"]
}

429 请求过多​

客户端超过了请求速率限制。请降低请求频率，或将日志对象批量打包到数组负载中。

批量处理多个日志事件​

您可以通过传递一个数组，在单次请求中最多发送 1,000 条日志条目。Datadog 建议高吞吐量服务采用此方法。

Payload: batched logs
[
  {
    "message": "User login succeeded",
    "service": "auth-service",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "INFO"
  },
  {
    "message": "Transaction failed: Gateway timeout",
    "service": "payment-gateway",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "ERROR",
    "transaction_id": "txn_998877"
  }
]

限制：

  • 每个未压缩请求的最大有效载荷大小为：5 MB（使用 gzip 压缩时为 50 MB）
  • 单个日志的最大大小：1 MB
  • 数组最大条目数：1,000 个日志对象

常见用例​

  • 在不部署 Datadog Agent 的情况下采集微服务日志。
  • 从无服务器函数（如亚马逊网络服务（AWS）Lambda 或 Google Cloud Run）发送结构化 JSON 事件。
  • 从物联网设备或边缘服务流式传输遥测数据。
  • 通过日志管道将经过增强的事件转发至安全信息和事件管理（SIEM）、S3 或告警目标。
  • 提交来自持续集成和持续交付（CI/CD）管道或部署脚本的日志。

故障排除​

问题合理依据解决方案
401 UnauthorizedAPI密钥错误或缺失在 组织设置 → API 密钥 中验证 DD_API_KEY
400 Bad RequestJSON格式不正确发送前请使用 jq . payload.json 进行验证
日志未显示在资源管理器中不包含日志的管道过滤器清除过滤器；检查索引路由规则
时间戳顺序错误非UTC或非ISO 8601格式请使用 "2025-11-15T08:30:00Z" 这种格式。
429 Too Many Requests超出请求限制Batch log objects into a single array payload

下一步​