# Tracehatch

> Tracehatch is AI observability for agents: record model calls, traces, spans, sessions, token usage and cost; inspect runs, evaluate scores and monitor production.

Official documentation for SDK 0.15.1. Start with this index, then fetch the linked Markdown pages relevant to the task. Each page includes its canonical HTML source for citations. No login or JavaScript is required to read these docs.

For setup in a user's codebase, start with Set up with AI, then fetch the integration, configuration and verification pages it selects. Check the actual runtime, operations, versions and installation availability before making changes. For API work, read HTTP API and its credential scopes before using the OpenAPI schema. Use Troubleshooting when recorded data is missing.

## Get started

- [Introduction](https://tracehatch.com/docs.md): What Tracehatch records, how it reaches your agent, and where to start.
- [Quickstart](https://tracehatch.com/docs/quickstart.md): Install the SDK, save the ingest key, wrap your provider client, and verify a recorded model call.
- [Set up with the CLI](https://tracehatch.com/docs/cli.md): Scan a project for model calls, finish setup on your machine, and apply the wrap behind a review.
- [Set up with AI](https://tracehatch.com/docs/ai-setup.md): Let your coding agent inspect the codebase, choose a supported integration, and verify your application's traces.
- [Verify your setup](https://tracehatch.com/docs/verify.md): Separate a delivered connection check from your application actually recording its model calls.
- [Deploy to production](https://tracehatch.com/docs/deploy.md): Create a production key, configure your host, and flush before short-lived processes return.

## Concepts

- [Data model](https://tracehatch.com/docs/concepts/data-model.md): Workspaces, projects, environments, runs, spans, sessions, prompts and scores, and how they nest.
- [What is recorded](https://tracehatch.com/docs/concepts/what-is-recorded.md): How a wrapped client becomes runs, generations, tool steps and sessions.
- [Privacy and data handling](https://tracehatch.com/docs/concepts/privacy.md): Body capture, built-in redaction, identifier pseudonyms, and what leaves your process.

## SDK and integrations

- [Configuration](https://tracehatch.com/docs/sdk/configuration.md): The one environment variable, wrap() options and the precedence between them.
- [Traces, spans and tools](https://tracehatch.com/docs/sdk/tracing.md): Name a run, nest steps inside it, time tool calls with retries, and attach users, sessions and tags.
- [Scores](https://tracehatch.com/docs/sdk/scores.md): Record numeric and categorical scores on a run or a single span while it is still open.
- [Delivery and flushing](https://tracehatch.com/docs/sdk/delivery.md): The export queue, flush(), flushWithResult(), shutdown(), head sampling and quota back-pressure.
- [Frameworks and runtimes](https://tracehatch.com/docs/sdk/frameworks.md): Where to put wrap() in Next.js, NestJS and Express, and the flush rule for serverless.
- [Framework and Python recipes](https://tracehatch.com/docs/sdk/integrations.md): Send AI SDK, LangChain and explicitly instrumented Python model and tool spans through OTLP.

## Using Tracehatch

- [Projects, environments and keys](https://tracehatch.com/docs/app/projects-and-keys.md): How a workspace, its projects and their three environments decide where a run lands.
- [Traces](https://tracehatch.com/docs/app/traces.md): Search and filter runs, read the waterfall, inspect a span, save a view and compare two runs.
- [Sessions and end users](https://tracehatch.com/docs/app/sessions.md): Follow a multi-turn conversation and everything one end user did across their sessions.
- [Dashboard and costs](https://tracehatch.com/docs/app/dashboard.md): Volume, failure rate, latency and recorded spend for the selected environment and range.
- [Models, Tools, Spans and Prompts](https://tracehatch.com/docs/app/analyze.md): Compare models and tools, explore individual spans, and diff prompt versions.
- [Alerts and notifications](https://tracehatch.com/docs/app/alerts.md): Watch a metric every minute and hear about it in Slack, email, a signed webhook or PagerDuty.
- [Health, releases and trends](https://tracehatch.com/docs/app/releases.md): Is production healthy now, was this deploy worse than the last one, and what is drifting over months.
- [Feedback, comments and sharing](https://tracehatch.com/docs/app/collaboration.md): Rate a run, comment on a span, and share one trace outside the workspace with an expiring link.

## Reference

- [HTTP API](https://tracehatch.com/docs/reference/api.md): Base URL, the three kinds of credential, scopes, rate limits, error shape and the endpoints.
- [Outbound webhooks](https://tracehatch.com/docs/reference/webhooks.md): Subscribe your own service to what happens: the envelope, the signature, the retry ladder and the limits.
- [Plans, quotas and retention](https://tracehatch.com/docs/reference/plans.md): What each plan includes, what happens above the trace allowance, and how long runs are kept.
- [Troubleshooting](https://tracehatch.com/docs/reference/troubleshooting.md): Nothing arrives, the wrong environment, missing bodies, missing cost and other common causes.

## API schema

- [OpenAPI JSON](https://tracehatch.com/docs/openapi.json): Generated HTTP API contract published with these docs. Authentication and examples are explained in the HTTP API documentation.

## Optional

- [Complete documentation](https://tracehatch.com/llms-full.txt): All 27 pages in one larger Markdown document. Prefer individual pages for focused tasks.
- [Documentation website](https://tracehatch.com/docs): Human-readable documentation with navigation and search.