Datadog 导出器

Koog 使用 OpenTelemetry 发送 agent 跟踪，OpenTelemetry 是可观测性数据的开放标准。为了将这些跟踪发送到 Datadog，Koog 包含了一个内置的 OpenTelemetry 导出器 —— 无需手动检测。

连接后，Datadog 的 OpenTelemetry 支持让您可以可视化、分析并调试 agent 与 LLM、工具及外部 API 的交互方式。

设置说明

在 https://www.datadoghq.com/ 创建 Datadog 帐户。
从 Organization Settings > API Keys 获取您的 API 密钥。
提供您的 API 密钥 —— 既可以作为 addDatadogExporter() 函数的参数提供，也可以通过环境变量提供：

bash

export DD_API_KEY="<your-api-key>"

（可选）要使用 US1 (datadoghq.com) 以外的 Datadog 地区，请将站点作为参数传递给 addDatadogExporter()，或设置环境变量：

bash

export DD_SITE="datadoghq.eu"

支持的站点：

站点	地区
`datadoghq.com`	US1（默认）
`datadoghq.eu`	EU1
`us3.datadoghq.com`	US3
`us5.datadoghq.com`	US5
`ap1.datadoghq.com`	AP1（日本）

配置

要启用 Datadog 导出，请安装 OpenTelemetry 功能并调用 addDatadogExporter()。

基础示例

=== "Kotlin"

<!--- INCLUDE
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry
import ai.koog.agents.features.opentelemetry.integration.datadog.addDatadogExporter
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
import kotlinx.coroutines.runBlocking
val promptExecutor = simpleOpenAIExecutor("openai-api-key")
-->
```kotlin
fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = promptExecutor,
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addDatadogExporter()
        }
    }

    println("Running agent with Datadog tracing")

    val result = agent.run("Tell me a joke about programming")
    println("Result: $result

See traces in Datadog LLM Observability") } ```

=== "Java"

<!--- INCLUDE
import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry;
import ai.koog.agents.features.opentelemetry.integration.datadog.DatadogKt;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;
import ai.koog.prompt.executor.model.PromptExecutor;
public class exampleDatadogExporterJava01 {
    static PromptExecutor promptExecutor = PromptExecutor.builder()
        .openAI("openai-api-key")
        .build();
-->
<!--- SUFFIX
}
-->
```java
public static void main(String[] args) {
    var agent = AIAgent.builder()
        .promptExecutor(promptExecutor)
        .llmModel(OpenAIModels.Chat.GPT4oMini)
        .systemPrompt("You are a code assistant. Provide concise code examples.")
        .install(OpenTelemetry.Feature, config ->
            DatadogKt.addDatadogExporter(config)
        )
        .build();

    System.out.println("Running agent with Datadog tracing");

    var result = agent.run("Tell me a joke about programming");
    System.out.println("Result: " + result + "

See traces in Datadog LLM Observability"); } ```

跟踪属性

当 Koog 将 agent 活动发送到 Datadog 时，它以一系列 span 的形式发送 —— 即单个工作的记录，例如一次 LLM 调用或工具执行。相关的 span 被分组到一个 trace（跟踪）中，它代表了从开始到结束的完整 agent 运行。

addDatadogExporter() 接受一个 resourceAttributes 参数 —— 这是一个描述发送跟踪的应用程序的键值对映射。这些属性会被附加到每个 span，从而方便在 Datadog 中按环境或版本等属性对跟踪进行过滤和分组。

常用的属性包括：

env：环境名称（例如 production、staging 或 development）
service.name：您的服务或应用程序的名称
version：应用程序版本，用于比较不同部署之间的行为

带有跟踪属性的示例

=== "Kotlin"

<!--- INCLUDE
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry
import ai.koog.agents.features.opentelemetry.integration.datadog.addDatadogExporter
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
import kotlinx.coroutines.runBlocking
val promptExecutor = simpleOpenAIExecutor("openai-api-key")
-->
```kotlin
fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = promptExecutor,
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a helpful assistant."
    ) {
        install(OpenTelemetry) {
            addDatadogExporter(
                url = "datadoghq.eu",  // 使用欧洲地区
                resourceAttributes = mapOf(
                    "env" to "production",
                    "service.name" to "my-agent",
                    "version" to "1.0.0"
                )
            )
        }
    }

    println("Running agent with Datadog tracing")

    agent.run("What is Kotlin?")
}
```
<!--- KNIT example-datadog-exporter-02.kt -->

=== "Java"

<!--- INCLUDE
import ai.koog.agents.core.agent.AIAgent;
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry;
import ai.koog.agents.features.opentelemetry.integration.datadog.DatadogKt;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;
import ai.koog.prompt.executor.model.PromptExecutor;
public class exampleDatadogExporterJava02 {
    static PromptExecutor promptExecutor = PromptExecutor.builder()
        .openAI("openai-api-key")
        .build();
-->
<!--- SUFFIX
}
-->
```java
public static void main(String[] args) {
    var agent = AIAgent.builder()
        .promptExecutor(promptExecutor)
        .systemPrompt("You are a helpful assistant.")
        .llmModel(OpenAIModels.Chat.GPT4oMini)
        .install(OpenTelemetry.Feature, config ->
            DatadogKt.addDatadogExporter(
                config,
                null,                            // datadogApiKey: 使用 DD_API_KEY 环境变量
                "datadoghq.eu"                   // url: 使用欧洲地区
            ))
        .build();

    System.out.println("Running agent with Datadog tracing");

    agent.run("What is Kotlin?");
}
```
<!--- KNIT exampleDatadogExporterJava02.java -->

::: note

目前不支持从 Java 设置 resourceAttributes，因为底层的 Kotlin 函数携带了一个 kotlin.time.Duration 参数（一个值类），这会导致包括其后参数在内的所有重载出现 JVM 名称修饰 (name mangling)。当需要 resourceAttributes 时，请使用上面的 Kotlin 示例。 :::

发送到多个后端

要同时将跟踪发送到 Datadog 和另一个后端，请通过 addDatadogExporter() 注册 Datadog，并通过 addSpanExporter() 添加第二个导出器。每次调用都会注册一个独立的批量 span 处理程序，因此这两个后端将并行导出：

=== "Kotlin"

<!--- INCLUDE
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetryConfigJvm.addSpanExporter
import ai.koog.agents.features.opentelemetry.integration.datadog.addDatadogExporter
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter
import kotlinx.coroutines.runBlocking
val promptExecutor = simpleOpenAIExecutor("openai-api-key")
fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = promptExecutor,
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a helpful assistant."
    ) {
-->
<!--- SUFFIX
    }
}
-->
```kotlin
install(OpenTelemetry) {
    addDatadogExporter()
    addSpanExporter(
        OtlpHttpSpanExporter.builder()
            .setEndpoint("http://localhost:4318/v1/traces")
            .build()
    )
}
```
<!--- KNIT example-datadog-exporter-03.kt -->

跟踪哪些内容

Datadog 导出器捕获与 Koog 的通用 OpenTelemetry 集成相同的活动。有关捕获的 span 完整列表以及如何包含 LLM 提示词和响应内容的详细信息，请参阅跟踪哪些内容。

有关 Datadog 的 OpenTelemetry 支持的更多详细信息，请参阅 Datadog OTLP API 接收。

故障排除

没有出现跟踪：确认 DD_API_KEY 和 DD_SITE 已正确设置（请参阅设置说明）。
身份验证错误：在 Organization Settings > API Keys 中验证您的密钥是否处于激活状态。
连接问题：确认您的环境可以访问 https://otlp.<DD_SITE>/v1/traces —— 例如，US1 地区为 https://otlp.datadoghq.com/v1/traces。

有关常规故障排除，请参阅故障排除。

规划代理

创建提示词

运行提示词

聊天记忆

OpenTelemetry

子图

Datadog 导出器

设置说明

配置

基础示例

跟踪属性

带有跟踪属性的示例

发送到多个后端

跟踪哪些内容

故障排除

Datadog 导出器 ​

设置说明 ​

配置 ​

基础示例 ​

跟踪属性 ​

带有跟踪属性的示例 ​

发送到多个后端 ​

跟踪哪些内容 ​

故障排除 ​

Datadog 导出器

设置说明

配置

基础示例

跟踪属性

带有跟踪属性的示例

发送到多个后端

跟踪哪些内容

故障排除