Keep Your AI Agent Traces on Your Machine: A Local-First Approach

Adding tracing to an AI agent changes more than the debugging experience. It also creates a new data path.

A trace can contain user messages, system instructions, retrieved documents, tool arguments, tool results, model output, identifiers, and internal business logic. Sending that trace to an external service may therefore be equivalent to sending the underlying application data.

The right first question is not simply, “Does this tracing SDK have a good dashboard?” It is, “What does it capture, where does it go, and who controls it?”

A local-first tracing design gives developers useful execution visibility while keeping export and sharing decisions explicit. It is not a rejection of hosted observability. It is a safer default for the development loop and a clearer boundary for sensitive data.

Traditional telemetry can also expose sensitive information, but AI traces are unusually payload-rich. The data needed to explain an agent’s behavior is often the same data the agent was asked to process.

This does not mean that rich traces are always inappropriate. It means trace data needs an owner, a classification, a retention period, and an approved destination just like any other sensitive dataset.

In a local-first workflow, the initial trace is written to a developer machine, an isolated test workspace, a CI runner, or infrastructure controlled by the organization. Nothing is exported merely because tracing was enabled.

agent execution
    |
    v
capture policy
    |
    v
controlled local sink
    |
    +--> local inspection
    |
    +--> reviewed, reduced export --> approved shared platform

The important property is intentional movement. Developers can inspect the execution locally, reduce the data to what is needed, and share only an approved artifact.

Local-first is not the same as automatically secure. A laptop may be compromised, a workspace may be synchronized to a consumer cloud account, and a CI artifact may be visible to more people than expected. Local traces still require access controls, retention rules, and safe defaults.

A single on/off tracing switch is too coarse for most agents. Use explicit capture modes instead:

Full-fidelity capture should require a deliberate configuration change, produce a visible warning, and expire automatically. It should never be enabled silently by a dependency update or a default environment variable.

The most reliable redaction strategy is not capturing unnecessary data. A typed metadata event makes the safe path easy and prevents arbitrary payloads from drifting into normal traces.

type TraceStatus = 'ok' | 'error';
type TraceKind = 'agent' | 'model' | 'tool' | 'retrieval';
type SafeValue = string | number | boolean | null;

export type TraceEvent = {
  version: 1;
  traceId: string;
  spanId: string;
  parentSpanId?: string;
  timestamp: string;
  kind: TraceKind;
  name: string;
  status: TraceStatus;
  durationMs?: number;
  inputTokens?: number;
  outputTokens?: number;
  metadata: Record<string, SafeValue>;
};

Notice what the schema does not include: raw prompts, free-form tool arguments, complete tool results, or authorization headers. Those fields require a separate, more restrictive capture path.

For an order lookup, prefer an allowlisted projection:

type OrderLookupResult = {
  found: boolean;
  status?: 'processing' | 'shipped' | 'delivered';
  itemCount?: number;
};

function orderLookupMetadata(
  result: OrderLookupResult,
): TraceEvent['metadata'] {
  return {
    resultFound: result.found,
    orderStatus: result.status ?? 'unknown',
    itemCount: result.itemCount ?? 0,
  };
}

This event can answer whether the lookup ran, succeeded, returned a record, and produced the expected state. It does not need an email address, street address, payment details, or the complete database response.

Newline-delimited JSON is a practical local format because it is append-friendly, streamable, and easy to inspect with standard tools. The following sink creates a private directory and file on platforms that support POSIX permissions:

import { appendFile, mkdir } from 'node:fs/promises';
import { dirname, resolve } from 'node:path';

export class LocalTraceSink {
  constructor(
    private readonly filePath = resolve(
      '.agent-traces',
      'traces.ndjson',
    ),
  ) {}

  async write(event: TraceEvent): Promise<void> {
    await mkdir(dirname(this.filePath), {
      recursive: true,
      mode: 0o700,
    });

    await appendFile(
      this.filePath,
      `${JSON.stringify(event)}\n`,
      {
        encoding: 'utf8',
        flag: 'a',
        mode: 0o600,
      },
    );
  }
}

For concurrent or high-volume tracing, put writes behind a queue or use a storage engine designed for parallel writers. Also verify existing file permissions at startup because the mode

option applies when a file is created; it does not repair an already permissive file.

Add the trace directory to .gitignore

, keep it outside folders that synchronize automatically, and do not serve it from a development web root.

.agent-traces/

Safe metadata should describe execution, not smuggle raw content under a different key. Useful fields include:

order_status

Be careful with hashes. A plain hash of a predictable identifier, such as an email address or short account number, can often be reversed by guessing. If cross-trace correlation is necessary, use a keyed HMAC managed outside the trace store, rotate the key, and document who can perform the correlation.

Regex replacement is useful for catching obvious patterns, but it is not a complete privacy control. Addresses, names, medical details, credentials, and business-sensitive text do not all have reliable patterns.

A stronger export pipeline works in this order:

Redaction should produce a new artifact. Preserve the restricted source only for its approved retention period, and never overwrite it in a way that makes the audit trail ambiguous.

Local traces deserve the same operational hygiene as other sensitive developer data:

Deleting old traces is part of the design, not housekeeping. A useful default is to expire development traces after hours or days, not months.

CI is controlled infrastructure, but it is not necessarily private. Logs and artifacts may be available to repository contributors, external pull requests, support personnel, or integrated services.

A safer CI flow is:

test fails
  -> metadata trace stays in the isolated workspace
  -> export policy creates a reduced artifact
  -> secret and sensitive-data scans run
  -> artifact uploads only when policy passes
  -> artifact expires after a short retention window

Avoid printing raw traces to the build log. Apply extra restrictions to workflows triggered from forks, and make artifact access and retention explicit in repository settings.

Production systems often need centralized metrics, alerts, trace correlation, and team-wide dashboards. Local-first tracing can coexist with those needs.

A practical split is:

Before exporting agent telemetry, review the destination’s access model, retention controls, deletion behavior, regional storage, subprocessors, and incident response process. Ensure the export matches your organization’s security and privacy requirements.

If the team cannot answer these questions, it is too early to enable full-fidelity tracing.

Observability should explain an agent’s execution without becoming an accidental copy of everything the agent touched. Start with typed metadata, keep the initial trace inside a controlled boundary, and make richer capture temporary and explicit.

The principle is simple: capture the minimum, inspect locally, and export intentionally.

The next article in this series will go deeper into metadata-only tracing: how to preserve execution structure, latency, token usage, retries, and error context without storing raw prompts or tool payloads.