A Lightweight Local Trace Store

Learn the contract without a heavy platform

Langfuse is a well-known open-source platform purpose-built for LLM tracing, evaluation, prompt management, and broader analytics - genuinely useful things a serious production LLM team needs. A production self-hosted Langfuse deployment, however, involves running multiple backing services of its own (a database, additional processing components) - real infrastructure that's valuable once you're operating at team scale, but disproportionately heavy for a short learning exercise on a shared, resource-constrained CPU host.

This platform's labs instead use a much simpler mechanism to teach the same underlying concept: JSONL, short for JSON Lines, where each individual line of a file is its own complete, independent JSON object.

$ tail -2 traces.jsonl
{"trace_id":"a1f9","step":"inference","input_tokens":310,"output_tokens":48,"cost":0.00}
{"trace_id":"b2e0","step":"inference","input_tokens":88,"output_tokens":12,"cost":0.00}
$ jq -s 'map(.output_tokens) | add' traces.jsonl
60

Appending a new trace to a JSONL file is as simple as writing one more line, jq can query and aggregate the file directly from the terminal (as shown above, summing every recorded output_tokens value across the file), and a Python script can just as easily read it line by line. The point of the lab isn't to reproduce a dashboard - it's to genuinely understand the trace schema (which fields matter and why) and where in the code the instrumentation boundary sits (exactly when and where a trace event gets written), concepts that transfer directly to using a real platform like Langfuse later.

A well-behaved tracer writes one complete event only once a request has actually finished, rather than dribbling out partial, inconsistent records mid-flight. In any real distributed deployment, that store should be durable and centralized rather than a local file per instance, with an explicit retention policy and restricted access; and critically, it should still emit a trace record - with an error status - even when inference itself fails, rather than silently skipping tracing on the exact requests you'd most want visibility into. It's also worth validating that required fields are actually present before writing, so that incomplete or malformed telemetry fails loudly and visibly rather than quietly leaving gaps in your data.

Note: The local tracer used in these labs is inspired by Langfuse's core concepts, but it is not Langfuse itself and does not reproduce Langfuse's UI, its distributed ingestion pipeline, session handling, prompt-management features, or its production-grade storage guarantees.

Goal: Query the repaired JSONL traces directly from the terminal to calculate request count, total token usage, total estimated cost, and average latency - the same kind of jq-based aggregation demonstrated above.