Skip to content

Datadog exporter

Koog emits agent traces using OpenTelemetry, an open standard for observability data. To ship those traces to Datadog, Koog includes a built-in OpenTelemetry exporter — no manual instrumentation required.

Once connected, Datadog's OpenTelemetry support lets you visualize, analyze, and debug how your agents interact with LLMs, tools, and external APIs.

Setup instructions

  1. Create a Datadog account at https://www.datadoghq.com/

  2. Get your API key from Organization Settings > API Keys

  3. Provide your API key — either as a parameter to addDatadogExporter(), or via an environment variable: 

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

  4. (Optional) To use a Datadog region other than US1 (datadoghq.com), pass the site as a parameter to addDatadogExporter(), or set an environment variable: 
    export DD_SITE="datadoghq.eu"
    Supported sites:
Site Region
datadoghq.com US1 (default)
datadoghq.eu EU1
us3.datadoghq.com US3
us5.datadoghq.com US5
ap1.datadoghq.com AP1 (Japan)

Configuration

To enable Datadog export, install the OpenTelemetry feature and call addDatadogExporter().

Basic example

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\nSee traces in Datadog LLM Observability")
}


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 + "\nSee traces in Datadog LLM Observability");
}

Trace attributes

When Koog sends agent activity to Datadog, it does so as a series of spans — individual records of work, such as an LLM call or a tool execution. Related spans are grouped into a trace, which represents a complete agent run from start to finish.

addDatadogExporter() accepts a resourceAttributes parameter — a map of key-value pairs describing the application emitting the traces. These are attached to every span, making it easy to filter and group traces in Datadog by properties such as environment or version.

Common attributes to include:

  • env: Environment name (for example, production, staging, or development)
  • service.name: Name of your service or application
  • version: Application version, useful for comparing behavior across deployments

Example with trace attributes

fun main() = runBlocking {
    val agent = AIAgent(
        promptExecutor = promptExecutor,
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a helpful assistant."
    ) {
        install(OpenTelemetry) {
            addDatadogExporter(
                url = "datadoghq.eu",  // Use EU region
                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?")
}


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: use DD_API_KEY env var
                "datadoghq.eu"                   // url: use EU region
            ))
        .build();

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

    agent.run("What is Kotlin?");
}

Note

Setting resourceAttributes from Java is currently not supported because the underlying Kotlin function carries a kotlin.time.Duration parameter (a value class) that causes JVM-name mangling on all overloads including parameters after it. Use the Kotlin example above when you need resourceAttributes.

Sending to multiple backends

To send traces to Datadog and another backend at the same time, register Datadog through addDatadogExporter() and add the second exporter through addSpanExporter(). Each call registers an independent batch span processor so the two backends are exported in parallel:

install(OpenTelemetry) {
    addDatadogExporter()
    addSpanExporter(
        OtlpHttpSpanExporter.builder()
            .setEndpoint("http://localhost:4318/v1/traces")
            .build()
    )
}

What gets traced

The Datadog exporter captures the same activity as Koog's general OpenTelemetry integration. For the full list of captured spans and how to include LLM prompt and response content, see What gets traced.

For more details on Datadog's OpenTelemetry support, see Datadog OTLP API Intake.

Troubleshooting

  • No traces: confirm DD_API_KEY and DD_SITE are set correctly (see Setup instructions).
  • Authentication errors: verify your key is active in Organization Settings > API Keys.
  • Connection issues: confirm your environment can reach https://otlp.<DD_SITE>/v1/traces — for example, https://otlp.datadoghq.com/v1/traces for US1.

For general troubleshooting, see Troubleshooting.