{"id":7473,"library":"openinference-instrumentation-haystack","title":"OpenInference Haystack Instrumentation","description":"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.","status":"active","version":"0.1.30","language":"en","source_language":"en","source_url":"https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-haystack","tags":["observability","tracing","opentelemetry","haystack","llm","ai","rag"],"install":[{"cmd":"pip install openinference-instrumentation-haystack","lang":"bash","label":"Install library"},{"cmd":"pip install opentelemetry-exporter-otlp","lang":"bash","label":"Install OTLP Exporter (for OpenTelemetry)"},{"cmd":"pip install 'haystack>=2.0.0.dev0,<3.0.0'","lang":"bash","label":"Install Haystack 2.x"}],"dependencies":[{"reason":"The core library being instrumented; requires version 2.x.","package":"haystack","optional":false},{"reason":"Core OpenInference utilities and semantic conventions.","package":"openinference-instrumentation","optional":false},{"reason":"Required for OpenTelemetry tracing functionality.","package":"opentelemetry-sdk","optional":false},{"reason":"Needed for exporting traces to an OTLP collector.","package":"opentelemetry-exporter-otlp","optional":true}],"imports":[{"symbol":"OpenInferenceHaystackInstrumentor","correct":"from openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor"}],"quickstart":{"code":"import os\nfrom haystack.components.builders.prompt_builder import PromptBuilder\nfrom haystack.components.generators import OpenAIGenerator\nfrom haystack.pipeline import Pipeline\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor\nfrom openinference.instrumentation.haystack import OpenInferenceHaystackInstrumentor\n\n# 1. Setup OpenTelemetry TracerProvider and Exporter\n# Ensure an OTLP collector is running, e.g., via Docker:\n# docker run -d -p 4318:4318 otel/opentelemetry-collector-contrib:latest --config=/etc/otel-collector-config.yml\n# (with otel-collector-config.yml having an OTLP HTTP receiver configured)\nresource = Resource.create({\"service.name\": \"haystack-openinference-example\"})\nprovider = TracerProvider(resource=resource)\nspan_exporter = OTLPSpanExporter(endpoint=\"http://localhost:4318/v1/traces\")\nprocessor = SimpleSpanProcessor(span_exporter)\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Haystack\nOpenInferenceHaystackInstrumentor().instrument()\n\n# 3. Create and run a Haystack pipeline\nprompt_template = \"Tell me a fun fact about {animal}.\"\npipe = Pipeline()\npipe.add_component(\"prompt_builder\", PromptBuilder(template=prompt_template))\n\n# Note: OpenAIGenerator requires OPENAI_API_KEY environment variable\nopenai_api_key = os.environ.get(\"OPENAI_API_KEY\", \"\")\nif not openai_api_key:\n    print(\"Warning: OPENAI_API_KEY not set. Skipping LLM generation.\")\n    generator = None\nelse:\n    generator = OpenAIGenerator(api_key=openai_api_key)\n    pipe.add_component(\"llm\", generator)\n    pipe.connect(\"prompt_builder.prompt\", \"llm.prompt\")\n\nquestion = \"cat\"\n\nif generator:\n    print(f\"\\nRunning Haystack pipeline for: {question}\")\n    result = pipe.run({\"prompt_builder\": {\"animal\": question}}).get(\"llm\", {})\n    print(\"Pipeline result (first 500 chars):\", str(result)[:500] + \"...\")\n    print(\"\\nCheck your OpenTelemetry collector for traces.\")\nelse:\n    print(\"Haystack pipeline not run due to missing OPENAI_API_KEY.\")\n\n# To uninstrument later (optional)\n# OpenInferenceHaystackInstrumentor().uninstrument()","lang":"python","description":"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."},"warnings":[{"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`.","message":"OpenTelemetry must be initialized (TracerProvider, SpanProcessor, SpanExporter) before `OpenInferenceHaystackInstrumentor().instrument()` is called, otherwise no traces will be generated or exported.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"This instrumentation specifically targets Haystack 2.x (>=2.0.0.dev0). It is not compatible with Haystack 1.x due to significant API changes.","severity":"breaking","affected_versions":"<0.1.0 (Haystack 1.x support, if any), >=0.1.0 (Haystack 2.x only)"},{"fix":"Call `OpenInferenceHaystackInstrumentor().instrument()` at the very beginning of your application setup, typically after OpenTelemetry is configured and before any Haystack objects are created.","message":"The `instrument()` method must be called *before* any Haystack pipelines or components you wish to trace are instantiated or run.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The OpenTelemetry `TracerProvider` or `SpanExporter` might not be correctly configured, or the OTLP collector might not be running or accessible.","error":"No traces appear in my OpenTelemetry collector."},{"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.","cause":"You are likely using Haystack 1.x, which has a different module structure and API compared to Haystack 2.x.","error":"AttributeError: module 'haystack.components' has no attribute 'generators'"},{"fix":"Install the library using pip: `pip install openinference-instrumentation-haystack`.","cause":"`openinference-instrumentation-haystack` is not installed in your environment.","error":"ModuleNotFoundError: No module named 'openinference.instrumentation.haystack'"}]}