> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Haystack

> Trace Haystack pipeline runs with Zespan using the built-in tracer integration.

<Note>
  Available for: **Python** only.
</Note>

## Installation

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
pip install zespan haystack-ai
```

## Usage

Initialize Zespan, then construct `ZespanHaystackTracer` with the active Zespan client and pass it as your pipeline's tracer.

```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import zespan
from zespan import ZespanHaystackTracer
import haystack.tracing
from haystack import Pipeline
from haystack.components.generators import OpenAIGenerator
from haystack.components.builders import PromptBuilder

zespan.init(api_key="zsp_your_api_key_here")

template = """
Given the following question, provide a concise answer.
Question: {{ question }}
"""

pipeline = Pipeline()
pipeline.add_component("prompt_builder", PromptBuilder(template=template))
pipeline.add_component("llm", OpenAIGenerator(model="gpt-4o"))
pipeline.connect("prompt_builder", "llm")

tracer = ZespanHaystackTracer(client=zespan.get_client())
haystack.tracing.enable_tracing(tracer)

result = pipeline.run(
    {"prompt_builder": {"question": "What is retrieval-augmented generation?"}},
    include_outputs_from={"llm"},
)
print(result["llm"]["replies"][0])
```

<Note>
  Call `haystack.tracing.enable_tracing(tracer)` once, before running any pipeline — it sets the tracer as a module-level global that Haystack uses for every subsequent pipeline run. Zespan then captures component execution, LLM calls, and pipeline latency.
</Note>

## What gets captured

| Field                  | Details                                                                                                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Span kind              | `chain` for the pipeline root span; per-component spans are typed from Haystack's own component metadata — `llm` for `Generator` components, `retrieval` for `Retriever` components, `embedding` for `Embedder` components, `chain` otherwise |
| Model / Provider       | Read from the component's `gen_ai.request.model` / `gen_ai.system` tracing tags, when Haystack's own OpenTelemetry-style tracing populates them                                                                                               |
| Input / output tokens  | From the component's `gen_ai.usage.input_tokens` / `gen_ai.usage.output_tokens` tags, when populated                                                                                                                                          |
| Latency                | Duration of each component's `run()`, and of the pipeline as a whole                                                                                                                                                                          |
| Agent name             | The Haystack pipeline name (root span) or component name (child spans)                                                                                                                                                                        |
| Parent/child structure | All component spans nest under a single pipeline root span                                                                                                                                                                                    |

<Note>
  Token, model, and provider fields depend on Haystack's own components populating tracing tags on the span. Not every component type surfaces these — check your component's Haystack version and docs if fields show as empty.
</Note>