Traces Troubleshooting

Use this checklist when traces do not appear in Catalyst or when spans are missing expected attributes.

No Spans Appear

Confirm Export Configuration

echo "$CATALYST_OTLP_ENDPOINT"
echo "$CATALYST_OTLP_TOKEN"
echo "$CATALYST_SERVICE_NAME"

Enable Debug Logging

export CATALYST_DEBUG=true

Initialize Before Clients

Call setup() before constructing provider or framework clients. Many integrations patch shared prototypes or callback configuration paths.

TypeScript

const tracing = await setup({ modules: { openai: OpenAI } });
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

Spans Disappear In Short-Lived Processes

Batch exporters flush on an interval. CLIs, scripts, workers, and tests should call shutdown() before the process exits.

await tracing.shutdown();

tracing.shutdown()

Framework Spans Are Missing

Integration	Check
LangChain / LangGraph JS	Pass `@langchain/core/callbacks/manager` as a namespace to `setup()`
LangSmith	Set `LANGSMITH_TRACING=true` and use `otel` or `hybrid` mode
Claude Agent SDK TS	Use `wrapClaudeAgentSdkQuery(query)`
OpenAI Agents	Pair `openaiAgents` with `openai` in `setup()`
Vercel Eve	Export `defineCatalystEveInstrumentation()` from `agent/instrumentation.ts`

Attributes Are Missing

Some attributes only appear when the upstream provider returns the data. For example, token counts depend on provider usage fields, and Anthropic prompt-cache details appear only when prompt caching actually engages for the request.

Next Steps

If setup order, export configuration, and shutdown are correct, reduce the issue to the smallest provider call and compare it with Traces Quickstart.

Integrations

Traces

Gateway

No Spans Appear

Confirm Export Configuration

Enable Debug Logging

Initialize Before Clients

Spans Disappear In Short-Lived Processes

Framework Spans Are Missing

Attributes Are Missing

Next Steps

​No Spans Appear

​Confirm Export Configuration

​Enable Debug Logging

​Initialize Before Clients

​Spans Disappear In Short-Lived Processes

​Framework Spans Are Missing

​Attributes Are Missing

​Next Steps

No Spans Appear

Confirm Export Configuration

Enable Debug Logging

Initialize Before Clients

Spans Disappear In Short-Lived Processes

Framework Spans Are Missing

Attributes Are Missing

Next Steps