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.
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 deepset 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.

Debug Your Pipelines

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