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
text

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>"
bash

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]
yaml

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.name on every span, as a span attribute.

Spans appear, but no sessions are listed

Set gen_ai.conversation.id or 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.