AtlasBurn
DocsPlatformIntegrationsOperationsReference

How It Works

Summary

AtlasBurn captures telemetry from every AI API call at the SDK level, resolves cost deterministically, and writes an append-only, server-authored record to the Forensic Ledger. This page explains the full data flow.

Auto-Detect Interception

When you call initAtlasBurnAuto(), the SDK monkey-patches globalThis.fetch to intercept outgoing HTTP calls to known AI provider endpoints. It automatically extracts usage metadata from JSON responses.

Intercepted endpoints:

  • api.openai.com
  • api.anthropic.com
  • Google Gemini (generativelanguage.googleapis.com)
  • Google Vertex AI endpoints

System maturity: Stable

Auto-detect is production-ready for OpenAI, Anthropic, Google Gemini, and Google Vertex AI. Other priced providers (Meta/Llama, Mistral, DeepSeek, xAI, Cohere, OpenRouter) capture via the Edge Proxy.

Edge Proxy Path

For providers the SDK does not auto-capture, or for non-JavaScript stacks, route traffic through proxy.atlasburn.com. The proxy applies the same normalization pipeline and enforces guardrail kill flags at the edge before the request reaches the upstream provider.

Data Flow

Each intercepted call follows this pipeline:

  1. SDK — extracts metadata from the API response
  2. Ingest Key Verification — HMAC-SHA-256 hash comparison (O(1) lookup)
  3. Normalization Engine — converts provider-specific fields into a unified schema
  4. Forensic Ledger — writes to Firestore as an append-only, server-authored record

Why normalization matters

Providers use different field names for the same data. OpenAI uses prompt_tokens, Anthropic uses input_token_count. The normalization engine resolves these into a single deterministic schema so your forensic ledger is consistent regardless of provider.

Event Lifecycle

  1. Ephemeral ID generation — a unique event ID is created
  2. Host execution — the original LLM call proceeds normally
  3. Post-execution extraction — usage metadata is pulled from the response
  4. Async background batch flush — events are queued and sent asynchronously

Fields Captured

FieldDescription
modelModel identifier (e.g., gpt-4o)
inputTokensPrompt token count
outputTokensCompletion token count
featureIdFeature attribution tag
userTierUser tier classification
timestampEvent timestamp
eventIdUnique event identifier
sdkVersionSDK version string

Fail-Silent Behavior

The SDK implements the 4 Laws of SDK Safety. All telemetry logic is wrapped in high-level try/catch blocks. Ingestion failures never block the host request.

If ingestion fails (e.g., network error), the SDK attempts 3 retries with exponential backoff before dropping the event to protect host memory.

Key Concepts

  • Fire-and-forget — telemetry is async; never blocks your app
  • Background queue — max 200 events to prevent memory leakage
  • Retry budget — 3 attempts with exponential backoff
  • Normalization — provider-specific fields unified into one schema

What This Means in Practice

Your application code is untouched. The SDK intercepts at the transport layer, extracts what it needs, and flushes telemetry in the background. If anything goes wrong in the telemetry pipeline, your LLM call completes normally. You never pay for telemetry with application reliability.

Next Steps