> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inference.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces Troubleshooting

> Debug missing spans, missing attributes, and shutdown behavior.

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

## No Spans Appear

### Confirm Export Configuration

<Metadata text="integrations/traces/troubleshooting-env" />

```bash theme={"system"}
echo "$CATALYST_OTLP_ENDPOINT"
echo "$CATALYST_OTLP_TOKEN"
echo "$CATALYST_SERVICE_NAME"
```

### Enable Debug Logging

<Metadata text="integrations/traces/troubleshooting-debug" />

```bash theme={"system"}
export CATALYST_DEBUG=true
```

### Initialize Before Clients

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

<Metadata text="integrations/traces/troubleshooting-setup-order" />

```typescript TypeScript theme={"system"}
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.

<CodeGroup>
  <Metadata text="integrations/traces/troubleshooting-shutdown" />

  ```typescript TypeScript theme={"system"}
  await tracing.shutdown();
  ```

  <Metadata text="integrations/traces/troubleshooting-shutdown" />

  ```python Python theme={"system"}
  tracing.shutdown()
  ```
</CodeGroup>

## 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/quickstart).