Privacy and data handling

Recording what an agent did and recording what it said are separate decisions. This page is the full account of which is which.

#Body capture

Bodies means prompts, messages, model outputs and tool arguments.

Guided installer

Starts with bodies off

SDK automatic import

Bodies on by default

Setting

TRACEHATCH_CAPTURE_BODIES

In code

init({ captureBodies: false })

The two defaults differ on purpose: the installer asks you, and writes your answer down; a bare import "@tracehatch/sdk/auto" has no one to ask and keeps the richer default. Setting the variable beside your key settles it either way, and the automatic import honours it — so the one-line integration is the same whichever you choose.

TRACEHATCH_API_KEY=your-project-api-key
TRACEHATCH_CAPTURE_BODIES=false

init({ captureBodies: false }) does the same in code and wins over the environment when both are set. An unreadable value throws rather than guessing.

#With bodies off

Still recorded: timings, reported token usage, finish reasons, provider errors, cost, span byte counts, prompt and version identity, sessions, users, tags and metadata.

Omitted: span inputs and outputs, messages, tool arguments and outputs, and trace-level bodies — including the transcripts that automatic runs would otherwise infer.

#Redaction

Built-in redaction runs inside the SDK, before anything enters the export queue. It masks:

• Email addresses and phone numbers
• Card-shaped strings that pass a validity check, and IBANs
• Common API key and secret patterns, and credential-named fields

It runs on bodies, attributes, metadata, errors, score text and user details. Add your own patterns through init:

init({
  redact: {
    rules: [{ name: "customer", pattern: /CUSTOMER-\d+/g }],
  },
})

redact: false disables masking entirely.

The log endpoint and the gateway redact on the server instead, because there is no SDK in the process to do it first.

#Identifiers

Session and user ids need to group reliably, so they cannot simply be masked. If redaction would change an id, or it exceeds the wire's 128-character limit, the SDK sends a deterministic SHA-256 pseudonym of the complete original id. Sessions and users use separate hash domains; safe, bounded ids are sent unchanged.

These are pseudonyms, not anonymous values: the hashes are unkeyed, so a guessed low-entropy identifier — an email address, a sequential id — can be checked against them. Prefer opaque identifiers.

#Size limits

Large bodies are truncated to a bounded head and tail. Streamed output is assembled up to a bound; past it the span is marked truncated and keeps the full byte count. Cycles, unsupported values and throwing getters cannot break your code.

#What leaves your process, and when

Spans are batched and exported over HTTP in the background — never inline with your request. The queue holds at most 10 MB including trace envelopes, sends up to 100 spans per batch after two seconds, retries transient failures, honours Retry-After, and splits oversized batches. When it is full, the oldest queued spans are dropped rather than your request being slowed.

flush() waits for pending export with a bounded timeout; flushWithResult() reports delivery status; shutdown() flushes and stops the exporter. See Delivery and flushing.

#Retention

Retention runs nightly at 02:00 UTC over finalised runs. Expired trace identities prevent retries and late spans from recreating deleted detail. Lifetime counters therefore keep telling the truth about volume and cost after the runs behind them are gone.

#Sharing outside the workspace

A public share link is the only way trace data leaves the workspace. Links last 1, 7 or 30 days and can be revoked. Every public read rechecks the link, the trace, the project and the plan; built-in redaction is reapplied; known end-user identifiers are masked; and scores, comments and project navigation are omitted.

#Deletion

Deleting a project deletes everything under it. Account deletion removes your comments and scores along with the account. Per-project redaction rules, manual trace deletion and data export are not available yet.