跳到主要内容

使用 Datadog 日志摄入 API 摄入事件

简介​

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

此端点支持结构化及 半结构化 JSON 负载的高吞吐量、实时摄入。

此 API 支持的操作​

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

了解有关 Datadog API 和 API 密钥的更多信息，请访问 此处。

开始之前​

请确保您拥有：

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

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

    区域站点地址
    美国（东部）datadoghq.com
    美国3（西部）us3.datadoghq.com
    美国5（中部）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<您的 API 密钥>是您的 Datadog API 密钥
Content-Typeapplication/json是有效负载格式

请求正文​

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

字段类型必填描述
message字符串是日志消息正文
ddsource字符串建议日志来源的技术，例如 python 或 nginx。
ddtags字符串可选以逗号分隔的标签，例如 env:prod,team:payments。
hostname字符串可选生成日志的主机名称
service字符串建议应用或服务的名称
备注

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

有效负载示例​

[
  {
    "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 将使用写入时间进行索引。

响应代码​

202 已接受​

202 Accepted 响应表示 Datadog 已收到有效负载。此响应不包含正文。日志将在几秒钟内显示在 Log Explorer 中。

HTTP/1.1 202 Accepted

400 请求错误​

当有效负载存在格式错误时，Datadog 会返回此代码。常见原因：

  • JSON 语法错误。
  • 缺少 message 字段。
  • 有效负载超过 5 MB 限制。
{
  "errors": ["Invalid JSON"]
}

401 未授权​

API 密钥缺失、错误，或缺乏日志摄入权限。

{
  "errors": ["Forbidden"]
}

429 请求过多​

系统已超过请求速率限制。请降低请求频率，或将日志对象批量合并为单个数组有效载荷。

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": "交易失败：网关超时",
      "ddsource": "payment-gateway",
      "ddtags": "env:prod,region:us-east-1",
      "hostname": "payments-host-01",
      "service": "payment-gateway",
      "level": "ERROR",
      "transaction_id": "txn_998877"
    }
  ]'

批量发送多个日志事件​

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

[
  {
    "message": "用户登录成功",
    "service": "auth-service",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "INFO"
  },
  {
    "message": "交易失败：网关超时",
    "service": "payment-gateway",
    "ddsource": "python",
    "ddtags": "env:prod",
    "level": "ERROR",
    "transaction_id": "txn_998877"
  }
]

限制：

  • 最大有效负载大小：每次请求 5 MB
  • 单条日志最大大小：1 MB
  • 数组最大条目数：1,000 个日志对象

常见用例​

  • 无需部署 Datadog Agent 即可采集微服务日志。
  • 从无服务器函数（如 Amazon Web Services (AWS) Lambda 或 Google Cloud Platform (GCP) Cloud Run）发送结构化 JSON 事件。
  • 流式传输来自物联网设备或边缘服务的遥测数据。
  • 通过 Log Pipelines 将增强后的事件路由到安全信息和事件管理 (SIEM)、S3 或告警目标。
  • 从持续集成与持续交付（CI/CD）管道或部署脚本提交日志。

故障排除​

问题可能原因解决方案
401 未授权API 密钥错误或缺失在 组织设置 → API 密钥 中验证 DD_API_KEY
400 请求错误JSON 格式错误发送前使用 jq . payload.json 进行验证
日志未显示在 Explorer 中管道过滤器排除了该日志清除过滤器；检查索引 routing rules
时间戳顺序错误非 UTC 或非 ISO 8601 格式使用 "2025-11-15T08:30:00Z" 格式
429 请求过多超出速率限制将日志对象批量打包为单个数组有效负载

后续步骤​