Send Agent Spans to Kloudfuse
Agents send OpenTelemetry spans to Kloudfuse over OTLP/HTTP, using a dedicated endpoint that is separate from APM. This page covers where to send the spans and how to configure your exporter.
Before you start, enable Agent Observability on your cluster.
Endpoint
https://<kloudfuse-hostname>/ingester/otlp/genai/v1/traces
The endpoint accepts OTLP in protobuf or JSON format. If authentication is enabled on your cluster, pass your API key in the Kf-Api-Key header.
Configure the exporter
Most instrumentation libraries read the standard OpenTelemetry environment variables:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<kloudfuse-hostname>/ingester/otlp/genai/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Kf-Api-Key=<token>" # omit if auth is not enabled
export OTEL_SERVICE_NAME="<your-application>"
The endpoint does not accept gRPC, which is the default for many OpenTelemetry SDKs, so set the protocol as shown.
LangSmith reads only OTEL_EXPORTER_OTLP_ENDPOINT and uses its value as is, so set that variable to the full endpoint URL instead.
To send through an OpenTelemetry Collector instead, add a dedicated receiver, exporter, and traces pipeline for your agent spans, and point your agents at the new receiver. This keeps them separate from any APM traces that the Collector handles:
receivers:
otlp/agents:
protocols:
http:
endpoint: 0.0.0.0:4319
exporters:
otlphttp/agents:
traces_endpoint: https://<kloudfuse-hostname>/ingester/otlp/genai/v1/traces
headers:
Kf-Api-Key: <token> # omit if auth is not enabled
service:
pipelines:
traces/agents:
receivers: [otlp/agents]
exporters: [otlphttp/agents]
Supported instrumentation
Kloudfuse detects the instrumentation that produced each span and normalizes its attributes. No per-library configuration is needed in Kloudfuse. It recognizes:
-
OpenTelemetry GenAI semantic conventions (
gen_ai.*) -
Traceloop and OpenLLMetry
-
LangSmith
-
LiteLLM
-
OpenRouter
-
Claude Code
| Message attributes contain your prompts and model responses, and Kloudfuse stores them. In this preview, access policies do not restrict Agent Observability data, so every signed-in user can read them. Many libraries do not capture message content by default, so check your library’s settings to turn it on or off. |
Verify
Run your agent, then open Agents > Overview and select a time range that includes the run. Your spans should appear in the charts.
Troubleshooting
- No data in any view
-
Confirm that Agent Observability is enabled, that the URL path includes
/otlp/genai/, and that the API key is valid. Spans sent to the APM endpoint (/ingester/otlp/traces) appear in APM, not here. - Spans appear, but no agents are listed
-
Set
gen_ai.agent.nameon every span, as a span attribute. - Spans appear, but no sessions are listed
-
Set
gen_ai.conversation.idor one of its alternatives. Kloudfuse does not derive a session from the trace ID. - Cost is missing
-
Confirm that the span has a model and token counts, and that the model has a price. See How cost is calculated.
- Transcripts are empty
-
Turn on message content capture in your instrumentation library.