Troubleshoot your first trace

Most first-trace problems come down to the API key, the region, or where the run is recorded. Work through these in order.

The run never appears

• The key is missing. The TypeScript SDK prints TRACIFY_API_KEY is not set and records nothing. The Python SDK raises a ValueError when the client is created. Set TRACIFY_API_KEY in the environment where the agent actually runs, not just in your shell.
• The key and region disagree. A key belongs to the EU or US region. If the configured region does not match, the client refuses to start with Tracify API key region mismatch. Set region (or the TRACIFY_REGION variable) to the region your project lives in. Keys without a region marker are treated as EU.
• Nothing ran inside a traced function. traceAgent (or @trace_agent) creates the run. Calls made outside one are recorded as separate standalone roots, so look for many one-step traces instead of one run.
• A request failed quietly. Telemetry never throws into your agent, so failures show up as a Failed to ingest span warning in your logs. Check the log output of the process that runs the agent.

The run is there, but steps are missing or flat

• Steps must be started inside the traced function, using span, observe, or a wrapped provider client. Work started in a detached process or an unrelated queue consumer has no parent.
• If steps appear but not nested, make sure the work is awaited inside the span callback (or inside the with block in Python). A step ends when its function settles.

Cost shows as zero

Tracify does not guess prices. Provider wrappers store token usage but set cost to zero and mark the span costKnown false until you supply a calculateCost function (calculate_cost in Python) with your own rate card. See OpenAI, Anthropic and LangGraph. For manual spans, pass costUsd yourself.

A model call appears twice

You are recording the same call through two paths, usually a wrapped provider client plus a framework's model callbacks, or a wrapped client plus a manual llmCall. Keep one.

Inputs or outputs look cut off or redacted

Inputs and outputs are capped at 10,000 characters, and obvious secrets such as bearer tokens, API keys, JWTs and password= values are replaced with a redaction marker before they leave your process. This is intentional. If you need less in the trace, set captureInput or captureOutput to false on a provider wrapper, or call observe with captureInput: false.

Still stuck

Check Choose a Tracify Cloud region for the endpoints each region uses, and review what is in a trace to confirm what you expect to see.