---
title: Observability for Koog with Langfuse
sidebarTitle: Koog
logo: /images/integrations/koog_icon.png
description: Learn how to instrument Koog agents with Langfuse via OpenTelemetry
category: Integrations
---
# Tracing Koog Agents with Langfuse
Koog provides built-in support for exporting agent traces to Langfuse. With Langfuse integration, you can visualize, analyze, and debug how your Koog agents interact with LLMs, APIs, and other components.
> **What is Koog?** [Koog](https://docs.koog.ai/) is a Kotlin-based framework designed to build and run AI agents entirely in idiomatic Kotlin. It lets you create agents that can interact with tools, handle complex workflows, and communicate with users. For background on Koog’s OpenTelemetry support, see the [OpenTelemetry support](https://docs.koog.ai/opentelemetry-support/).
> **What is Langfuse?** [Langfuse](/) is an open-source AI engineering platform. It offers tracing and monitoring capabilities for LLM applications. Langfuse helps developers debug, analyze, and optimize their AI systems by providing detailed insights and integrating with a wide array of tools and frameworks through native integrations, OpenTelemetry, and dedicated SDKs.
## Setup Langfuse
1. Sign up for [Langfuse Cloud](/) or [self-host Langfuse](/self-hosting).
2. Create a Langfuse project. Follow the setup guide at [Create new project in Langfuse](/docs/get-started#create-new-project-in-langfuse)
3. Obtain API credentials. Retrieve your Langfuse `public key` and `secret key` as described in [Where are Langfuse API keys?](/faq/all/where-are-langfuse-api-keys)
4. Set environment variables. Add the following variables to your environment:
```bash
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 EU region
# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com, 🇯🇵 Japan: https://jp.cloud.langfuse.com and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
```
Once configured, Koog automatically forwards OpenTelemetry traces to your Langfuse instance.
## Configure Koog
To enable Langfuse export, install the **OpenTelemetry feature** and add the `LangfuseExporter`.
The exporter uses `OtlpHttpSpanExporter` under the hood to send traces to Langfuse’s OpenTelemetry endpoint.
**Example: Agent with Langfuse Tracing**
```kotlin
fun main() = runBlocking {
val agent = AIAgent(
executor = simpleOpenAIExecutor(ApiKeyService.openAIApiKey),
llmModel = OpenAIModels.CostOptimized.GPT4oMini,
systemPrompt = "You are a code assistant. Provide concise code examples."
) {
install(OpenTelemetry) {
addLangfuseExporter()
}
}
println("Running agent with Langfuse tracing")
val result = agent.run("Tell me a joke about programming")
println("Result: $result\nSee traces on the Langfuse instance")
}
```
## See traces in Langfuse
When enabled, the Langfuse exporter captures the same spans as Koog’s general OpenTelemetry integration, including:
- **Agent lifecycle events** – agent start, stop, errors
- **LLM interactions** – prompts, responses, token usage, latency
- **Tool and API calls** – execution traces for function/tool invocations
- **System context** – metadata such as model name, environment, Koog version
Koog also captures span attributes required by Langfuse to show [Agent Graphs](/docs/observability/features/agent-graphs). This allows you to correlate agent reasoning with API calls and user inputs in a structured way within Langfuse.
[Public link to trace](https://cloud.langfuse.com/project/cmcmdwcag00c2ad077xp1qnyc/traces/dff173a675b759ce1b70e522b27d6846?timestamp=2025-08-26T19%3A40%3A59.145Z&display=details&observation=e44e72cf2d221781)
For more details on Langfuse OTLP tracing, see the [Langfuse OpenTelemetry Docs](/integrations/native/opentelemetry#opentelemetry-endpoint).
## Troubleshooting
- **No traces appear in Langfuse**
- Double-check that `LANGFUSE_BASE_URL`, `LANGFUSE_PUBLIC_KEY`, and `LANGFUSE_SECRET_KEY` are set in your environment.
- If running on self-hosted Langfuse, confirm that the `LANGFUSE_BASE_URL` is reachable from your application environment.
- Verify that the public/secret key pair belongs to the correct project.
---
## Agent Instructions
This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/integrations/frameworks/koog.md`.
### Querying these docs
If the answer is not on this page, query the documentation instead of guessing:
- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:
```bash
curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
```
- **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).
### Before writing Langfuse code
- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal.
Found an error in these docs? Please open an issue at .