Your AI pipeline has three steps. Transcribe the audio. Summarize the transcript. Generate an email from the summary. The email comes out wrong. Rambling, off-topic, misses the key points from the meeting.

Which step broke?

Maybe the transcription was inaccurate and the summarizer worked from garbage. Maybe the transcription was perfect but the summary prompt was too aggressive, compressing a 30-minute meeting into one sentence. Maybe both were fine and the email generation prompt had a formatting bug. You don't know. The pipeline gave you one output and hid three intermediate results.

Without tracing, you'd re-run each step individually, inspect each output by hand, and manually correlate timestamps across log entries to figure out what belonged to the same run. With correlation IDs, where each step logs its input and output under one shared ID, you query one string and see them in order.

Why Multi-Step Pipelines Are Hard to Debug

AI workflows chain models together. Step 1 calls a speech-to-text engine. Step 2 sends the transcript to an LLM for summarization. Step 3 sends the summary to another LLM to draft the email. Each step is a separate API call, potentially to a different backend running a different model. The output of step N becomes the input of step N+1.

When the final output is wrong, the failure could be at any step. And the further down the chain the failure is caught, the harder it is to trace backward. A bad transcription corrupts every downstream step. A bad summary only corrupts the email. But from the outside, both look the same: the email is wrong.

The traditional approach: add print statements at each step, re-run the pipeline, read terminal output, and correlate entries manually by timestamp. This works for three steps on a quiet afternoon. It doesn't work for eight steps across three services when you're also running a dev server, a model loader, and a file watcher that are all printing to the same terminal.

The output you need is buried in noise. Or it scrolled past. Or it's in a different terminal tab. The data existed. It was printed. And now it's gone.

What Is a Correlation ID?

A correlation ID is a string that tags every log entry from a single execution. All events that belong to the same pipeline run share the same ID. Query by that ID and you get the complete timeline of one execution, across every component and process that logged with it.

The concept isn't new. Distributed tracing systems like Jaeger and Zipkin have used trace IDs for years. The idea is the same. The difference is that you don't need a distributed tracing infrastructure to use correlation IDs in LogPiper. You pass a string when you log. You query by that string when you debug. No agents to install, no collectors to configure, no dashboard to set up.

The ID itself can be anything. A UUID. A timestamp-based string. A job name. The only requirement is uniqueness per execution. If two pipeline runs share the same ID, their logs merge and the trace is useless.

How LogPiper Handles Correlation IDs

LogPiper doesn't create correlation IDs. correlationId is an optional field on each log entry, and whoever posts the entry sets it. Nothing in ToolPiper assigns one to a workflow, a pipeline or a request, and ToolPiper's own entries don't carry yours. What LogPiper does is store the field and filter on it: GET /v1/logs?correlationId= returns exact matches, and the All Logs view in ToolPiper's main window has an Execution picker for the same field.

Your code passes it when logging, which is how you trace pipelines that you orchestrate yourself. Log each step's input and output with it, not only a summary, and the trace shows what every step worked from. There's no per-entry size cap, so full prompts and outputs fit.

import requests
from uuid import uuid4

job_id = f"job_{uuid4().hex[:8]}"

def log(level, event, message, data=None):
    requests.post("http://127.0.0.1:9998/v1/logs", json={
        "source": "my-pipeline",
        "level": level,
        "event": event,
        "message": message,
        "data": data or {},
        "correlationId": job_id
    }, timeout=2)

log("info", "pipeline.start", "Starting audio processing")

# Step 1: Transcribe
transcript = transcribe(audio_file)
log("info", "transcribe.complete", "Transcription done",
    {"words": len(transcript.split()), "transcript": transcript})

# Step 2: Summarize
prompt = build_summary_prompt(transcript)
summary = summarize(prompt)
log("info", "summarize.complete", "Summary generated",
    {"prompt": prompt, "summary": summary})

# Step 3: Generate email
email_prompt = build_email_prompt(summary)
email = generate_email(email_prompt)
log("info", "email.complete", "Email drafted",
    {"prompt": email_prompt, "email": email})

Every entry shares job_id. Every entry is queryable as a group. The ID was generated once, at the top of the pipeline, and threaded through every step.

Querying a Trace

Once events are tagged, pull the full trace with one request:

curl "http://127.0.0.1:9998/v1/logs?correlationId=job_a1b2c3d4"

You get every entry logged with that ID, oldest first (the newest 100 by default; add &limit= up to 2,000 for a long run):

[
  {"source": "my-pipeline", "event": "pipeline.start", "message": "Starting audio processing", ...},
  {"source": "my-pipeline", "event": "transcribe.complete", "data": {"words": 1247, "transcript": "...full transcript..."}, ...},
  {"source": "my-pipeline", "event": "summarize.complete", "data": {"prompt": "...prompt + transcript...", "summary": "...summary..."}, ...},
  {"source": "my-pipeline", "event": "email.complete", "data": {"prompt": "...prompt + summary...", "email": "...email draft..."}, ...}
]

Reading top to bottom, you see each step's input and output. If the transcript was wrong, you see it in the transcribe.complete entry. If the summary was too short, summarize.complete shows you what the LLM actually produced. If the email prompt was malformed, email.complete holds the exact prompt that was sent. One query, and every step you logged is in view.

Every entry in that trace is one your pipeline posted. ToolPiper's own entries, such as its server events and backend output, don't carry your ID, so they never show up in it. Traces also go through GET /v1/logs only: the live stream at /v1/logs/stream filters by level, source and event, not by correlation ID.

Example: The Summary Missed Key Points

A user runs an audio-to-email pipeline. The resulting email misses half the action items from the meeting. Something went wrong, but what?

Query the correlation ID. The trace shows:

Transcription output (step 1): Accurate. All speakers captured. Action items clearly spoken: "We need to ship the API changes by Friday" and "Maria will handle the client follow-up." Both present in the transcript.

Summarization request (step 2): The system prompt reads: "Summarize the following in one sentence."

Found it. The user wanted a detailed summary with action items. The prompt asked for one sentence. The summarizer did exactly what it was told. It compressed a 30-minute meeting into a single sentence and dropped everything that didn't fit.

Root cause identified in one query. The transcription was fine. The email generation was fine. The summarization prompt was wrong. Fix the prompt, re-run, done.

Without the trace, the AI assistant would have started by questioning the transcription quality, then maybe the email prompt, then maybe the model choice. Three rounds of elimination before landing on the actual problem. The correlation ID turns that into a direct lookup.

Example: Pipeline Crash at Step 2

The pipeline stops mid-execution. Step 1 completes. Step 2 never finishes. No final output at all.

Query the correlation ID:

curl "http://127.0.0.1:9998/v1/logs?correlationId=job_f9e8d7c6"

The trace shows three entries. This pipeline logs each model call before sending it and logs failures from its error handler, all with the same ID:

  1. transcribe.complete - step 1 succeeded, 1,247 words transcribed
  2. summarize.request - the summarization request, logged just before it went to /v1/chat/completions
  3. summarize.error - status 404, response body: {"error":{"message":"Model 'llama-3.2-3b' not found. Available models: ...","type":"model_not_found","status":404}}

The summarization model wasn't available. The transcription backend (a different engine) was running fine, but the model name in the summarization request didn't match any model ToolPiper could serve. The fix is either to use a name from the list in the error or to download the model before the pipeline starts.

The response body told you exactly what happened and what to do about it. Without the trace, you'd see a generic error in the terminal and start guessing: network issue? Wrong port? Service crashed? The actual cause, a model name ToolPiper didn't recognize, was in the response body your pipeline logged.

Tracing Across Processes

Correlation IDs work across process boundaries, as long as every process logs with the same ID. ToolPiper doesn't join in: when your script calls ToolPiper's API, the entries ToolPiper writes don't carry your ID. To cover that hop, log the request and the response from your side with the ID. To see what ToolPiper itself did at that moment, query its entries by source or event and line up the timestamps.

For your own multi-service architecture, pass the correlation ID through HTTP headers or request bodies. The pattern is straightforward:

# Service A: the orchestrator
job_id = "batch_20260404_001"
response = requests.post("http://localhost:3001/process",
    json={"data": payload, "correlationId": job_id})
log("info", "dispatch.sent", "Sent to processor", correlationId=job_id)

# Service B: the processor
correlation_id = request.json.get("correlationId")
log("info", "process.received", "Processing started", correlationId=correlation_id)
result = do_work(request.json["data"])
log("info", "process.complete", "Processing done",
    data={"result_size": len(result)}, correlationId=correlation_id)

Both services log to the same LogPiper instance at 127.0.0.1:9998. Query by batch_20260404_001 and you see the orchestrator's dispatch, the processor's receipt, and the processor's completion - all in one timeline. Two processes, one trace.

This is the same principle that distributed tracing systems use. The difference is that LogPiper keeps it simple. No trace context propagation libraries. No span hierarchies. No collector agents. You pass a string and you query a string. For local development with a handful of services, that's enough.

When to Use Correlation IDs

Multi-model AI pipelines. STT, then LLM, then TTS. Or: embed, then retrieve, then generate. Any chain where model outputs feed into other models. Tag the chain and trace the data flow when the final output is wrong.

Batch processing jobs. Tag each batch with a unique ID. When batch 47 of 200 fails, query its ID and see exactly which item caused the failure and what the error was.

Request tracing across services. A frontend calls a backend, which calls an inference engine, which calls a model. Pass the correlation ID through each hop you own and log at each one, including what you sent to the inference engine and what came back, and the full request lifecycle is one query away.

Comparing pipeline runs. Run the same pipeline twice with different parameters. Give each run a different correlation ID. Query each trace separately. Compare the outputs side by side to see where they diverge. Did changing the temperature from 0.3 to 0.7 affect the summary quality? The traces show you the exact outputs from each run.

Workflow debugging with AI assistants. When you tell Claude Code or Cursor to debug a pipeline failure, point the AI at the correlation ID. The AI queries one endpoint and gets the full context: every step, request and response your pipeline logged. No manual log file grepping. No "can you paste the error message" back-and-forth.

What Correlation IDs Don't Do

Correlation IDs are optional. If you don't pass one, your log entries aren't grouped. They're still in LogPiper and still queryable by level, source or event type, but you lose the ability to pull a single execution as a unit.

Nothing generates them for you. ToolPiper doesn't assign IDs to workflows or requests, and its own entries don't carry yours, so every ID in a trace is one your code passed explicitly. There's no automatic propagation across HTTP boundaries unless you build it into your request protocol. If service A calls service B and doesn't include the correlation ID in the request, service B's logs are orphaned from the trace.

The IDs don't create parent-child relationships between entries. There's no span tree, no call graph, no waterfall visualization. You get a flat list of entries sorted by timestamp, all sharing one ID. For most local debugging, a flat timeline is exactly what you need. If you need hierarchical traces with span nesting and dependency graphs, you need a proper distributed tracing system like Jaeger or Tempo.

And the 5,000-entry circular buffer in LogPiper means old entries get evicted. A correlation ID can't retrieve entries that have already been pushed out of the buffer, or anything from before a ToolPiper restart, since the buffer lives in memory. For long-running pipelines that generate a lot of log traffic, query the correlation ID before the entries age out, or export the buffer periodically (POST /v1/logs/export, which needs a bearer token).

Making It Automatic

The best correlation ID strategy is one you don't have to think about. Two patterns work well.

Generate at the top, thread through everything. Create the ID once when the pipeline starts. Store it in a variable that every step can access. Every log call, every HTTP request, every error handler includes the ID. You write this code once per pipeline and it traces every run from that point forward.

Add it to your CLAUDE.md for AI-assisted debugging. If you're using an AI coding assistant, add instructions to your project config:

## Pipeline Debugging
When instrumenting pipeline code, always generate a correlation ID
at the start and pass it to every log call:
  correlationId = f"run_{uuid4().hex[:8]}"
When debugging pipeline failures, query by correlation ID:
  curl "http://127.0.0.1:9998/v1/logs?correlationId=<id>"

The AI assistant follows the convention. Every pipeline it instruments gets a correlation ID. Every debugging session starts with a trace query. The discipline is encoded in the project, not in your memory.

Try It

ToolPiper is free from the modelpiper.com/download. LogPiper runs automatically, and correlation IDs work the moment you start passing them.

This is spoke 8 in the vibe debugging series on AI development observability. For the complete LogPiper reference, see LogPiper: A Universal Logging Bus That Ships Free Inside ToolPiper. For logging full request and response bodies alongside correlation IDs, see Full HTTP Body Capture: See Exactly What Your AI Sent and Received.