OpenTelemetry Haystack Instrumentation

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install opentelemetry-instrumentation-haystack haystack-ai openai Install library and core dependencies

Imports

• HaystackInstrumentor

  from opentelemetry.instrumentation.haystack import HaystackInstrumentor

  Main class to enable Haystack instrumentation.

Quickstart

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.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.haystack import HaystackInstrumentor

# 1. Initialize OpenTelemetry TracerProvider
resource = Resource.create({"service.name": "haystack-app"})
provider = TracerProvider(resource=resource)
# Use ConsoleSpanExporter for demonstration; replace with OTLPSpanExporter for production
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

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

# 3. Haystack Usage (requires 'haystack-ai' and 'openai' to be installed)
try:
    from haystack_ai.components.generators import OpenAIGenerator
    from haystack_ai.components.builders.prompt_builder import PromptBuilder
    from haystack_ai.components.pipelines import Pipeline
    from haystack_ai.components.retrievers.in_memory import InMemoryBM25Retriever
    from haystack_ai.document_stores.in_memory import InMemoryDocumentStore
    from haystack_ai.schema import Document

    # Set OpenAI API key for the generator. For local execution, ensure this is set.
    # For a real application, retrieve from a secure source.
    if not os.environ.get("OPENAI_API_KEY"): # Using os.environ.get for robustness
        print("Warning: OPENAI_API_KEY not set. OpenAIGenerator might fail or use a default.")

    # Create a simple document store and add documents
    document_store = InMemoryDocumentStore()
    documents = [
        Document(content="The quick brown fox jumps over the lazy dog."),
        Document(content="Haystack is an open-source framework for building custom LLM applications."),
        Document(content="OpenTelemetry provides observability for your applications.")
    ]
    document_store.write_documents(documents)

    # Create a Haystack pipeline
    pipeline = Pipeline()
    pipeline.add_component("retriever", InMemoryBM25Retriever(document_store=document_store))
    pipeline.add_component("prompt_builder", PromptBuilder(template="Answer the question: {{query}}\nContext: {{documents}}"))
    pipeline.add_component("generator", OpenAIGenerator(model="gpt-3.5-turbo"))

    pipeline.connect("retriever", "prompt_builder.documents")
    pipeline.connect("prompt_builder", "generator.prompt")

    # Run the pipeline
    query = "What is Haystack?"
    print(f"\nRunning Haystack pipeline with query: '{query}'")
    result = pipeline.run(data={
        "query": query,
        "retriever": {"query": query}
    })

    print("\nHaystack Pipeline Result:")
    print(result)

except ImportError as e:
    print(f"\nSkipping Haystack example due to missing dependencies: {e}")
    print("Please install 'haystack-ai' and 'openai': pip install haystack-ai openai")
except Exception as e:
    print(f"\nAn error occurred during Haystack pipeline execution: {e}")
    print("Ensure OPENAI_API_KEY is set if using OpenAIGenerator and your network is accessible.")

# 4. Shut down the provider to ensure all spans are exported
provider.shutdown()