OpenInference Haystack Instrumentation

0.1.30 · active · verified Thu Apr 16

The `openinference-instrumentation-haystack` library provides OpenTelemetry-compliant instrumentation for Haystack (v2.x) pipelines, enabling detailed tracing of LLM operations, prompt engineering, and RAG workflows. It captures inputs, outputs, and metadata for each component within a Haystack pipeline, translating them into OpenInference semantic conventions. The current version is 0.1.30, and it is part of the broader OpenInference project, which sees frequent updates across its various instrumentation packages.

Common errors

```
No traces appear in my OpenTelemetry collector.
```
cause The OpenTelemetry `TracerProvider` or `SpanExporter` might not be correctly configured, or the OTLP collector might not be running or accessible.

fix Verify your `OTLPSpanExporter` endpoint is correct (e.g., `http://localhost:4318/v1/traces` for HTTP) and that an OpenTelemetry collector is running and listening on that address. Check collector logs for connection errors.
```
AttributeError: module 'haystack.components' has no attribute 'generators'
```
cause You are likely using Haystack 1.x, which has a different module structure and API compared to Haystack 2.x.

fix Upgrade your Haystack installation to version 2.x: `pip install 'haystack>=2.0.0.dev0,<3.0.0'`. This instrumentation is designed for Haystack 2.x.
```
ModuleNotFoundError: No module named 'openinference.instrumentation.haystack'
```
cause `openinference-instrumentation-haystack` is not installed in your environment.

fix Install the library using pip: `pip install openinference-instrumentation-haystack`.

Warnings

gotcha OpenTelemetry must be initialized (TracerProvider, SpanProcessor, SpanExporter) before `OpenInferenceHaystackInstrumentor().instrument()` is called, otherwise no traces will be generated or exported.
Fix: Ensure `opentelemetry.sdk.trace.TracerProvider` is configured and `trace.set_tracer_provider()` is called early in your application's lifecycle, along with an appropriate `SpanProcessor` and `SpanExporter`.
breaking This instrumentation specifically targets Haystack 2.x (>=2.0.0.dev0). It is not compatible with Haystack 1.x due to significant API changes.
Fix: Ensure your Haystack installation is version 2.x (e.g., `pip install 'haystack>=2.0.0.dev0,<3.0.0'`). Do not attempt to use with Haystack 1.x.
gotcha The `instrument()` method must be called *before* any Haystack pipelines or components you wish to trace are instantiated or run.
Fix: Call `OpenInferenceHaystackInstrumentor().instrument()` at the very beginning of your application setup, typically after OpenTelemetry is configured and before any Haystack objects are created.

Install

pip install openinference-instrumentation-haystack Install library
pip install opentelemetry-exporter-otlp Install OTLP Exporter (for OpenTelemetry)
pip install 'haystack>=2.0.0.dev0,<3.0.0' Install Haystack 2.x

Imports

OpenInferenceHaystackInstrumentor

from openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor

Quickstart

This quickstart demonstrates how to set up OpenTelemetry with `openinference-instrumentation-haystack` and run a simple Haystack 2.x pipeline. It configures a `TracerProvider` to export spans via OTLP HTTP to `http://localhost:4318/v1/traces`. The `OpenInferenceHaystackInstrumentor` is then activated before the Haystack `Pipeline` is defined and executed. The example uses `OpenAIGenerator`, requiring an `OPENAI_API_KEY` environment variable.

import os
from haystack.components.builders.prompt_builder import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.pipeline import Pipeline
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor

# 1. Setup OpenTelemetry TracerProvider and Exporter
# Ensure an OTLP collector is running, e.g., via Docker:
# docker run -d -p 4318:4318 otel/opentelemetry-collector-contrib:latest --config=/etc/otel-collector-config.yml
# (with otel-collector-config.yml having an OTLP HTTP receiver configured)
resource = Resource.create({"service.name": "haystack-openinference-example"})
provider = TracerProvider(resource=resource)
span_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
processor = SimpleSpanProcessor(span_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument Haystack
OpenInferenceHaystackInstrumentor().instrument()

# 3. Create and run a Haystack pipeline
prompt_template = "Tell me a fun fact about {animal}."
pipe = Pipeline()
pipe.add_component("prompt_builder", PromptBuilder(template=prompt_template))

# Note: OpenAIGenerator requires OPENAI_API_KEY environment variable
openai_api_key = os.environ.get("OPENAI_API_KEY", "")
if not openai_api_key:
    print("Warning: OPENAI_API_KEY not set. Skipping LLM generation.")
    generator = None
else:
    generator = OpenAIGenerator(api_key=openai_api_key)
    pipe.add_component("llm", generator)
    pipe.connect("prompt_builder.prompt", "llm.prompt")

question = "cat"

if generator:
    print(f"\nRunning Haystack pipeline for: {question}")
    result = pipe.run({"prompt_builder": {"animal": question}}).get("llm", {})
    print("Pipeline result (first 500 chars):", str(result)[:500] + "...")
    print("\nCheck your OpenTelemetry collector for traces.")
else:
    print("Haystack pipeline not run due to missing OPENAI_API_KEY.")

# To uninstrument later (optional)
# OpenInferenceHaystackInstrumentor().uninstrument()

view raw JSON →