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

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

Raju Dandigam’s Dev.to article highlights that enabling tracing on an AI agent can inadvertently expose all application data. He notes that traces often contain user messages, system instructions, tool arguments, and internal business logic.

Why This Matters

The technical reality is that AI agent traces are payload-rich, often containing the same data the agent processes—user messages, system instructions, tool results, and confidential documents. The ideal model of observability assumes you can safely export telemetry, but in practice, traces can leak personal data, business logic, and proprietary knowledge. A local-first approach ensures developers control data movement and export only what is necessary, reducing the risk of accidental exposure.

Key Insights

• AI traces are payload-rich: they can include user messages, system prompts, tool calls, results, and retrieval context. Local-first tracing writes the initial trace to a developer machine, not an external service, using a controlled sink like Node.js fs with POSIX permissions.
• Explicit capture modes (metadata, selective payload, full fidelity) prevent accidental data leaks. Full-fidelity capture should require a deliberate configuration change, display a warning, and expire automatically, as described in the 2026 article.
• Safe metadata fields (operation names, status, duration, token counts) should be typed to avoid smuggling raw content. The OrderLookupMetadata function exemplifies allowlisting only necessary fields, not email addresses or payment details.

Working Examples

Typed TraceEvent schema that avoids capturing raw prompts, tool arguments, or authorization headers.

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>;
};

Allowlisted projection for order lookup metadata, extracting only necessary fields without exposing sensitive customer data.

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,
  };
}

Node.js local trace sink that writes NDJSON to a private directory with POSIX permissions (700 for dir, 600 for file).

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,
      },
    );
  }
}

Practical Applications

• Development environment: Use a local trace sink writing to .agent-traces directory with restricted permissions (0o700 dir, 0o600 file). Pitfall: Not adding the directory to .gitignore or syncing it to a consumer cloud account, leading to data leakage.
• CI/CD pipeline: Keep metadata traces in the isolated workspace, then run a export policy that creates a reduced artifact after secret scanning. Pitfall: Printing raw traces to the build log, making them accessible to all repository contributors.
• Production: Export only approved metadata to the observability platform; use a separate incident process for restricted payload capture. Pitfall: Enabling full-fidelity capture silently via a default environment variable, exposing sensitive data continuously.

References:

• https://dev.to/raju_dandigam/keep-your-ai-agent-traces-on-your-machine-a-local-first-approach-5b9l