Tutorial: Connect Litefuse

Litefuse accepts traces through a Langfuse-compatible OTLP interface. Configure an export binding in the registry, then create a session to pin that binding. You do not install a Langfuse SDK in your agent or supply Litefuse credentials to the harness.

This walkthrough uses a dedicated Workspace custom binding and metadata-only capture. It does not create a Litefuse project or change deployment-wide capture policy.

Before you begin

• Run an exporter with Kafka Transcript access and Registry internal authentication. For a self-hosted deployment, follow deploy the exporter.
• Prepare a dedicated Litefuse project with an externally reachable public HTTPS endpoint.
• Select a test Workspace without an existing custom binding. Have an organization admin key with observability:read and observability:write, or org:admin.
• Have a runnable agent and environment in that same Workspace.
• Install curl, jq, and uuidgen; examples use Bash.

Export these variables from your credential manager or shell setup. Do not put real keys in source control or enable shell tracing while running the commands.

Read the current Workspace state

Keep the opaque ETag exactly as returned, including quotes. Workspace PUT always requires it.

headers=$(mktemp)
state=$(curl -fsS -D "$headers" \
  "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability" \
  -H "x-api-key: $ORCA_ORG_ADMIN_KEY")
WORKSPACE_ETAG=$(awk 'tolower($1) == "etag:" { sub(/\r$/, "", $2); print $2 }' "$headers")
rm -f "$headers"
jq '{configured, effective}' <<< "$state"

If configured.mode is already custom, use a different test Workspace or follow the replacement rules. The next example is a new binding creation; a same-active-target replacement must omit credentials.

Create the Litefuse binding

Use semantic_profile: langfuse for Litefuse. Credentials bind ingestion to a project; setting external_project_id is not a substitute for matching project keys.

IDEMPOTENCY_KEY=$(uuidgen)
binding=$(jq -n '{
  mode: "custom",
  capture_ceiling: "metadata_only",
  target: {
    adapter_type: "otlp_http",
    endpoint_kind: "traces_endpoint",
    endpoint_class: "public",
    endpoint_url: (env.LITEFUSE_BASE_URL + "/api/public/otel/v1/traces"),
    external_project_id: env.LITEFUSE_PROJECT_ID
  },
  config: {
    semantic_profile: "langfuse",
    protocol: "http/json",
    compression: "none",
    timeout_ms: 10000,
    sample_rate: 1,
    capture_mode: "metadata_only",
    environment: "test",
    release: "litefuse-check"
  },
  credentials: {
    type: "basic",
    username: env.LITEFUSE_PUBLIC_KEY,
    password: env.LITEFUSE_SECRET_KEY
  }
}' | curl -fsS -X PUT \
  "$ORCA_ADMIN_URL/v1/organizations/workspaces/$WORKSPACE_ID/agent_observability" \
  -H "x-api-key: $ORCA_ORG_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $WORKSPACE_ETAG" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" --data-binary @-)
BINDING_ID=$(jq -r '.configured.binding.id' <<< "$binding")
jq '{scope, configured, effective}' <<< "$binding"

A newly created custom binding returns 201. Confirm effective.source is workspace_custom, effective.status is enabled, and effective.capture_mode is metadata_only. The response contains no key material. A successful PUT does not contact Litefuse or prove delivery.

For a retry of this request, retain the original body, ETag, and idempotency key. For a new mutation, read a fresh ETag and create a new key.

Run a new session

Switch to the public registry endpoint and Workspace credential. Session creation pins the current export selection; do not reuse a session created before the binding.

session=$(jq -n --arg agent "$AGENT_ID" --arg environment "$ENVIRONMENT_ID" '{
  agent: $agent, environment_id: $environment, title: "Litefuse export check"
}' | curl -fsS "$ORCA_REGISTRY_URL/v1/sessions" \
  -H "x-api-key: $ORCA_API_KEY" \
  -H "Content-Type: application/json" --data-binary @-)
SESSION_ID=$(jq -r '.id' <<< "$session")

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ORCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"type":"user.message","content":[{"type":"text","text":"Reply with the word ready."}]}]}'

Use the event stream or event list to confirm the message was processed and the turn completed. Allow time for asynchronous delivery and backend indexing, then open the dedicated Litefuse project.

Verify:

• The session grouping is $WORKSPACE_ID:$SESSION_ID; the trace has an agent root.
• Metadata identifies the Workspace/session and, for newly attributed contexts, the binding $BINDING_ID, agent revision, test environment, and litefuse-check release.
• Tool/evaluator observations appear only if the run produced corresponding events.
• Input/output are absent: that is expected in metadata-only mode. Model summaries are span observations, not synthetic provider generations.

To include content, follow enable raw capture explicitly. After all applicable ceilings and the binding permit raw capture, run another new session with synthetic data. Check root/tool I/O and omission markers rather than assuming a complete transcript.

Troubleshoot missing traces

Stop the test export

Read a fresh Workspace ETag, then PUT {"mode":"disabled","capture_ceiling":"metadata_only"} with a new idempotency key. See disable a Workspace. Disabling the organization default does not stop a Workspace custom binding. Export disable does not delete already stored content or Litefuse traces.

What's next