Registry /
observability / openinference-instrumentation-haystack
Install & Compatibility
Where this runs
tested against v0.1.34 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
8/12 runs
8/12 runs
py 3.11
8/12 runs
8/12 runs
py 3.12
8/12 runs
8/12 runs
py 3.13
8/12 runs
8/12 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenInferenceHaystackInstrumentor
✓ from openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor
✗ from openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor
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()
Debug
Known issues
gotchaOpenTelemetry must be initialized (TracerProvider, SpanProcessor, SpanExporter) before `OpenInferenceHaystackInstrumentor().instrument()` is called, otherwise no traces will be generated or exported.fixEnsure `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`.
affects: All versions
breakingThis instrumentation specifically targets Haystack 2.x (>=2.0.0.dev0). It is not compatible with Haystack 1.x due to significant API changes.fixEnsure 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.
affects: <0.1.0 (Haystack 1.x support, if any), >=0.1.0 (Haystack 2.x only)
gotchaThe `instrument()` method must be called *before* any Haystack pipelines or components you wish to trace are instantiated or run.fixCall `OpenInferenceHaystackInstrumentor().instrument()` at the very beginning of your application setup, typically after OpenTelemetry is configured and before any Haystack objects are created.
affects: All versions
Upgrade
Version history
0.1.34latest on PyPI · released May 18, 2026
Audit
Dependencies
haystackrequiredThe core library being instrumented; requires version 2.x.
openinference-instrumentationrequiredCore OpenInference utilities and semantic conventions.
opentelemetry-sdkrequiredRequired for OpenTelemetry tracing functionality.
opentelemetry-exporter-otlpoptionalNeeded for exporting traces to an OTLP collector.