> For the complete documentation index, see [llms.txt](https://docs.cloud.deepset.ai/llms.txt)

Last modified: 2026-11-06

# Trace Your Pipelines

Traces are detailed records of every step in the search process that hel you understand, analyze, and troubleshoot your AI pipelines. You can trace your pipelines through logs, built-in traces, or one of the integrated services.

* * *

## Tracing vs Debugging

Tracing and debugging both help you understand how your pipeline runs, but they serve different purposes.

Tracing captures the full journey of a query — from the user's input through each processing step to the final result. A trace usually includes timestamps, the original query and its transformations, generated embeddings, retrieved documents, scoring and ranking decisions, as well as any errors or latency issues. Tracing shows how data flows through the system and when each step occurs, giving you a clear picture of what happened end to end. Tools like Langfuse or Weave make this information easy to visualize and explore.

Debugging is about getting to the root of problems. It involves analyzing detailed logs to pinpoint errors, misconfigurations, or unexpected behavior. While tracing shows you the "what" and "when," debugging helps you uncover the "why."

AI-powered applications are often complex and opaque, making it hard to understand what’s happening under the hood. When something goes wrong, tracing and debugging let you lift the veil. They’re essential for fixing issues, improving performance, and gaining insight into how your models behave. Whether you're tracking down high latency, investigating odd query results, or exploring search patterns, these tools give you the visibility you need to take action.

## Tools for Debugging

-   Pipeline logs: Capture operational details, such as the component that generated the log, log level, timestamp, and log message. They're available in the Builder on the Analytics tab, but also after running the pipeline in Builder or Playground.
-   Pipeline debugger: Offers live component-level logs available from Builder.
-   Remote debug with a VS Code tunnel.

## Tools for Tracing

You can trace your pipelines through built-in traces or one of the integrated services.

-   **Built-in traces**: Available on the Analytics tab in the Builder. These traces capture the details of every pipeline run to help you undersand what happened during a query: which components ran, how long they took, and any errors that occurred. For indexes, you can record a trace when you reindex a single file. See [Capture an Indexing Trace When Reindexing a File](https://docs.cloud.deepset.ai/docs/trace-your-pipelines-ui.md#capture-an-indexing-trace-when-reindexing-a-file).
-   Integrated services:
    -   **Langfuse**: Provides deep tracing for application-level observability, including detailed spans, latency tracking, and cross-service dependencies.
    -   **Weights & Biases Weave**: Captures ML-specific telemetry to help you track your pipeline's latency, token-count, and more.

## Look Up a Trace by Trace ID or Query ID

To inspect in the API or an MCP tool a trace you found in the UI, paste its trace ID straight into the request. Each built-in trace has a trace ID, which you can copy in the UI, and a query ID. The single-trace API endpoints accept either one in the path. This covers the endpoints that return trace details, logs, span tags, and trace exports, for both pipelines and deployments.

The Haystack Platform MCP server and the AI assistant use the same endpoints. If you paste a trace ID into the assistant or an MCP tool, it returns that trace.

Keep the following in mind:

-   The platform first looks for a query with the ID you passed. If none exists, it looks for a trace with that ID in the same pipeline or deployment.
-   If the ID matches neither a query nor a trace in that pipeline or deployment, the endpoint returns a `404` error. It never returns a different trace in its place. An ID that belongs to another pipeline or deployment also returns `404`. If you get a `404`, check that the ID is correct and that you're calling the pipeline or deployment the trace belongs to.
-   A lookup by query ID is the faster option. A lookup by trace ID takes one extra search, so use the query ID when you have it.

## Read a Trace's Duration

When a streamed response feels slow, the trace's duration breakdown shows whether the time went to the pipeline or to the steps around it. For a streamed run, the duration shows how long the caller waited and adds up three parts:

-   **Before run**: the time from when the API received the request to when the pipeline run started, for example routing, session setup, and queueing. A run started by a background job has no value for this part.
-   **Run**: the time the pipeline itself took. This is the part to look at when you tune your pipeline.
-   **After run**: the time from the end of the pipeline run to the end of the stream, which covers sending the result, storing the trace, and sending the final event.

To see the breakdown, hover over the duration in the trace header. In the API, the trace list and trace detail endpoints return it in the optional `timing` object next to `duration_s`.

A trace with an **Interrupted** tag, in the trace header and the trace list, belongs to a run whose client left before the stream ended. The client may not have received the full answer, even if the run succeeded. If you see this tag often, check whether the client closes the connection early, because the pipeline itself ran successfully.

Keep the following in mind:

-   Runs that aren't streamed show a plain duration that covers the pipeline run only. Runs from before this breakdown existed also show a plain duration.
-   The time between the browser and the API, before the API received the request, isn't measured.

-   Pipeline optimization compares run time for traces that have a breakdown, so replayed candidates and live traces are measured the same way.

## Debug Your Pipelines

See the following instructions, depending on how you want to debug:

-   [Debug with logs](https://docs.cloud.deepset.ai/docs/debug-with-logs.md)
-   [Debug with Pipeline Builder](https://docs.cloud.deepset.ai/docs/debug-with-pipeline-builder.md)

## Trace Your Pipelines

To trace your pipelines, you can use built-in traces or one of the integrated services:

-   [Trace with Built-In Traces](https://docs.cloud.deepset.ai/docs/trace-your-pipelines-ui.md)
-   [Trace with Weights & Biases](https://docs.cloud.deepset.ai/docs/use-weights-and-biases.md)
-   [Trace with Langfuse](https://docs.cloud.deepset.ai/docs/trace-with-langfuse.md)
