{"id":2633,"library":"opentelemetry-instrumentation-haystack","title":"OpenTelemetry Haystack Instrumentation","description":"The `opentelemetry-instrumentation-haystack` library provides OpenTelemetry tracing capabilities for applications using Haystack (haystack-ai). It automatically captures spans for various Haystack operations, including pipeline execution, document store interactions, and LLM calls, enriching them with relevant attributes. As part of the `openllmetry` project, it follows its rapid release cadence, with version `0.58.0` being the latest, frequently updating to support new Haystack features and OpenTelemetry semantic conventions.","status":"active","version":"0.58.0","language":"en","source_language":"en","source_url":"https://github.com/traceloop/openllmetry/tree/main/packages/opentelemetry-instrumentation-haystack","tags":["opentelemetry","observability","tracing","haystack","llm","ai","rag"],"install":[{"cmd":"pip install opentelemetry-instrumentation-haystack haystack-ai openai","lang":"bash","label":"Install library and core dependencies"}],"dependencies":[{"reason":"Core OpenTelemetry API for tracing.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK for tracing.","package":"opentelemetry-sdk","optional":false},{"reason":"The library being instrumented. Must be installed separately.","package":"haystack-ai","optional":true},{"reason":"Common dependency for Haystack's OpenAI components, used in quickstart.","package":"openai","optional":true}],"imports":[{"note":"Main class to enable Haystack instrumentation.","symbol":"HaystackInstrumentor","correct":"from opentelemetry.instrumentation.haystack import HaystackInstrumentor"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.haystack import HaystackInstrumentor\n\n# 1. Initialize OpenTelemetry TracerProvider\nresource = Resource.create({\"service.name\": \"haystack-app\"})\nprovider = TracerProvider(resource=resource)\n# Use ConsoleSpanExporter for demonstration; replace with OTLPSpanExporter for production\nprovider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Haystack\nHaystackInstrumentor().instrument()\n\n# 3. Haystack Usage (requires 'haystack-ai' and 'openai' to be installed)\ntry:\n    from haystack_ai.components.generators import OpenAIGenerator\n    from haystack_ai.components.builders.prompt_builder import PromptBuilder\n    from haystack_ai.components.pipelines import Pipeline\n    from haystack_ai.components.retrievers.in_memory import InMemoryBM25Retriever\n    from haystack_ai.document_stores.in_memory import InMemoryDocumentStore\n    from haystack_ai.schema import Document\n\n    # Set OpenAI API key for the generator. For local execution, ensure this is set.\n    # For a real application, retrieve from a secure source.\n    if not os.environ.get(\"OPENAI_API_KEY\"): # Using os.environ.get for robustness\n        print(\"Warning: OPENAI_API_KEY not set. OpenAIGenerator might fail or use a default.\")\n\n    # Create a simple document store and add documents\n    document_store = InMemoryDocumentStore()\n    documents = [\n        Document(content=\"The quick brown fox jumps over the lazy dog.\"),\n        Document(content=\"Haystack is an open-source framework for building custom LLM applications.\"),\n        Document(content=\"OpenTelemetry provides observability for your applications.\")\n    ]\n    document_store.write_documents(documents)\n\n    # Create a Haystack pipeline\n    pipeline = Pipeline()\n    pipeline.add_component(\"retriever\", InMemoryBM25Retriever(document_store=document_store))\n    pipeline.add_component(\"prompt_builder\", PromptBuilder(template=\"Answer the question: {{query}}\\nContext: {{documents}}\"))\n    pipeline.add_component(\"generator\", OpenAIGenerator(model=\"gpt-3.5-turbo\"))\n\n    pipeline.connect(\"retriever\", \"prompt_builder.documents\")\n    pipeline.connect(\"prompt_builder\", \"generator.prompt\")\n\n    # Run the pipeline\n    query = \"What is Haystack?\"\n    print(f\"\\nRunning Haystack pipeline with query: '{query}'\")\n    result = pipeline.run(data={\n        \"query\": query,\n        \"retriever\": {\"query\": query}\n    })\n\n    print(\"\\nHaystack Pipeline Result:\")\n    print(result)\n\nexcept ImportError as e:\n    print(f\"\\nSkipping Haystack example due to missing dependencies: {e}\")\n    print(\"Please install 'haystack-ai' and 'openai': pip install haystack-ai openai\")\nexcept Exception as e:\n    print(f\"\\nAn error occurred during Haystack pipeline execution: {e}\")\n    print(\"Ensure OPENAI_API_KEY is set if using OpenAIGenerator and your network is accessible.\")\n\n# 4. Shut down the provider to ensure all spans are exported\nprovider.shutdown()\n","lang":"python","description":"This quickstart demonstrates how to enable OpenTelemetry tracing for a simple Haystack pipeline. It initializes an OpenTelemetry `TracerProvider` with a `ConsoleSpanExporter` (for printing traces to console), instruments Haystack using `HaystackInstrumentor().instrument()`, and then constructs and runs a basic Haystack RAG pipeline. Replace `ConsoleSpanExporter` with `OTLPSpanExporter` for sending traces to a collector. Ensure `haystack-ai` and `openai` are installed and `OPENAI_API_KEY` is set in your environment for the generator to function."},"warnings":[{"fix":"Update any trace analysis queries, dashboards, or alerting rules that rely on specific LLM-related span attributes. Refer to the OpenTelemetry GenAI Semantic Conventions documentation for the new attribute names and structure. Review your trace data to understand the new schema.","message":"Starting from versions around 0.53.0 and continuing through 0.58.0, this instrumentation package transitioned to align with the OpenTelemetry Generative AI Semantic Conventions (GenAI SemConv). This introduces significant changes to the names and structure of span attributes related to LLM operations.","severity":"breaking","affected_versions":">=0.53.0"},{"fix":"Ensure you have `haystack-ai` installed (`pip install haystack-ai`). If migrating from `farm-haystack`, review the official Haystack documentation for migration guides as the API may have breaking changes.","message":"This instrumentation targets the newer `haystack-ai` package, not the legacy `farm-haystack`. If you are using `farm-haystack`, you might experience issues or missing instrumentation for newer features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always place the `HaystackInstrumentor().instrument()` call early in your application's startup sequence, typically right after OpenTelemetry `TracerProvider` setup, and before any `haystack-ai` imports or instantiations.","message":"The `HaystackInstrumentor().instrument()` call must occur before any Haystack components (e.g., `Pipeline`, `DocumentStore`, `Generator`) are initialized or used. If Haystack objects are created before instrumentation is enabled, their operations will not be traced.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}