> ## Documentation Index > Fetch the complete documentation index at: https://docs.ancha.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These docs describe the Ancha CLI, npm package @ancha-labs/cli, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict. # Traces > Where your agent sends production traces, the keys and formats Ancha accepts, how spans become traces, the limits, and the API for traces and the tests saved from them. Your workspace receives OpenTelemetry traces from your agent and keeps each one as a trace you can save as a test. The guide [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md) walks through the whole flow. ## Send traces | Setting | Value | | - | - | | Endpoint | `https://ingest.ancha.io/v1/traces` (OTLP/HTTP) | | Header | `Authorization: Bearer ` | | Body | `application/json` or `application/x-protobuf`, optionally `Content-Encoding: gzip` | With the OpenTelemetry SDK, set two environment variables: ```bash theme={null} OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.ancha.io/v1/traces OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20 ``` Create ingest keys on the **Traces** page. An ingest key sends traces to your workspace and does nothing else: it cannot read traces, tests or runs. Revoke a key on the same page; senders still using it are refused within a minute. See [Login and API keys](https://docs.ancha.io/cloud/login-and-api-keys.md). ## Limits and answers | Answer | When | | - | - | | `200` | The spans are stored. | | `400` | The body is not a readable OTLP trace export. | | `401` | The key is missing, revoked, or not an ingest key. | | `413` | The request is over 4 MB, over 16 MB once unzipped, or holds more than 20,000 spans. | | `415` | The content type is not `application/json` or `application/x-protobuf`. | | `429` | The key sent more than 600 requests in a minute, or Ancha is reading as many batches as it can at once. Retry after the `Retry-After` seconds. OpenTelemetry exporters retry on their own. | An exporter only logs a refused batch. The **Traces** page says how many batches each ingest key had refused in the last 24 hours, and why. ## How spans become a trace * Spans with the same trace id are one trace. Ancha assembles it once no span has arrived for 60 seconds. * An agent that starts a new trace for every webhook or turn can join them: put the same `session.id` or `gen_ai.conversation.id` on a span of each. They become one trace on the **Traces** page. Spans of those traces that arrive without the attribute follow them. * Spans that arrive after a trace was assembled join it. Nothing already stored is replaced. * While spans are still arriving, the trace page says so, and you can save a test from what has arrived. * If a trace cannot be assembled, it is marked failed with the reason, and its waiting spans are deleted. * The resource attribute `deployment.environment.name` (or `deployment.environment`) names the trace's environment. The **Traces** page and `ancha traces --env` filter by it, so staging runs stay apart from production ones. ## Upload a file ```bash theme={null} ancha import trace.jsonl ancha import --from langfuse ancha import --from langsmith ``` The file can be [Ancha Trace IR](https://docs.ancha.io/reference/trace-ir.md), an OTLP JSON export, or a Langfuse or LangSmith export, up to 25 MB. `--from` fetches the trace with the keys in your shell, which never leave your computer. `ancha import` saves the test it makes and writes it to your project. See [ancha import](https://docs.ancha.io/cli/import.md). A saved test takes the agent's other traces in your workspace (up to five of the same agent) as examples, so answers production never gave are simulated the way the tools behaved in those runs. ## The Traces page Each trace shows: * **What arrived:** the agent's own tool calls, API calls by tool and whether Ancha rebuilds each tool, webhooks, model calls and whether they carried the agent's input, and what to add to your tracing for anything missing. * **The test this trace makes:** what the agent is told, the world in plain words, the checks with production's result, and the questions one trace cannot settle. * **Save as test**, **Download what Ancha stored**, and **Delete trace**. **Tests** lists the saved tests, one row per trace with its latest version. ## API Read endpoints take an API key (`Authorization: Bearer `), the same one `ancha login` saves. Ids may be shortened to their first eight characters; a trace may also be named by the trace id your tracing tool shows. | Method and path | Does | | - | - | | `GET /v1/traces` | Lists your traces, newest first. | | `GET /v1/traces/` | One trace, with its intake check and its latest saved test. | | `GET /v1/traces//preview` | The test the trace makes, without saving it. `422` when the trace has nothing to rebuild. | | `GET /v1/traces//ir` | What Ancha stored: the redacted [Trace IR](https://docs.ancha.io/reference/trace-ir.md). | | `POST /v1/traces//tests` | Saves the test as a new version. | | `DELETE /v1/traces/` | Deletes the trace and its stored data. Add `?tests=1` to delete the tests saved from it too. | | `GET /v1/worlds/` | A saved test: its scene, where each part came from, and its questions. | The base URL is `https://app.ancha.io`. An id prefix that names two traces answers `409`; use more characters. ## Related topics - [ancha traces](https://docs.ancha.io/cli/traces.md) - [Trace privacy](https://docs.ancha.io/cloud/trace-privacy.md) - [Trace IR](https://docs.ancha.io/reference/trace-ir.md) - [From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces.md) - [Test an app](https://docs.ancha.io/guides/test-an-app.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.