|
| 1 | +--- |
| 2 | +title: "OpenTelemetryConnector" |
| 3 | +id: opentelemetryconnector |
| 4 | +slug: "/opentelemetryconnector" |
| 5 | +description: "Learn how to work with OpenTelemetry in Haystack." |
| 6 | +--- |
| 7 | + |
| 8 | +# OpenTelemetryConnector |
| 9 | + |
| 10 | +Learn how to work with OpenTelemetry in Haystack. |
| 11 | + |
| 12 | +<div className="key-value-table"> |
| 13 | + |
| 14 | +| | | |
| 15 | +| --- | --- | |
| 16 | +| **Most common position in a pipeline** | Anywhere, as it’s not connected to other components | |
| 17 | +| **Mandatory init variables** | None. The tracer is created at initialization time | |
| 18 | +| **Output variables** | `name`: The name of the tracing component | |
| 19 | +| **API reference** | [opentelemetry](/reference/integrations-opentelemetry) | |
| 20 | +| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/opentelemetry | |
| 21 | +| **Package name** | `opentelemetry-haystack` | |
| 22 | + |
| 23 | +</div> |
| 24 | + |
| 25 | +## Overview |
| 26 | + |
| 27 | +`OpenTelemetryConnector` integrates tracing capabilities into Haystack pipelines using [OpenTelemetry](https://opentelemetry.io/), through the [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/python/). It captures detailed information about pipeline runs, like API calls, context data, prompts, and more, so you can see the complete trace of your pipeline execution in any OpenTelemetry-compatible backend. |
| 28 | + |
| 29 | +OpenTelemetry tracing is enabled as soon as the `OpenTelemetryConnector` is initialized, so you only need to add it to your pipeline – it does not need to be connected to other components or to run to take effect. |
| 30 | + |
| 31 | +You can optionally pass a `name` to identify this tracing component (it defaults to `opentelemetry`). |
| 32 | + |
| 33 | +### Prerequisites |
| 34 | + |
| 35 | +These are the things that you need before working with the `OpenTelemetryConnector`: |
| 36 | + |
| 37 | +1. A configured OpenTelemetry `TracerProvider` with an exporter (for example, an OTLP exporter that sends traces to a collector or a backend). Set up the provider before initializing the connector. |
| 38 | +2. Set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` – this will enable content tracing (inputs and outputs) in your pipelines. |
| 39 | +3. To add traces at even deeper levels, check out the available [OpenTelemetry instrumentations](https://opentelemetry.io/ecosystem/registry/?s=python), such as `opentelemetry-instrumentation-openai-v2` for tracing OpenAI requests. |
| 40 | + |
| 41 | +### Installation |
| 42 | + |
| 43 | +First, install the `opentelemetry-haystack` package to use the `OpenTelemetryConnector`: |
| 44 | + |
| 45 | +```shell |
| 46 | +pip install opentelemetry-haystack |
| 47 | +``` |
| 48 | + |
| 49 | +<br /> |
| 50 | + |
| 51 | +:::info[Usage Notice] |
| 52 | + |
| 53 | +To ensure proper tracing, always set environment variables before importing any Haystack components. This is crucial because Haystack initializes its internal tracing components during import. In the example below, we first set the environment variables and then import the relevant Haystack components. |
| 54 | + |
| 55 | +Alternatively, an even better practice is to set these environment variables in your shell before running the script. This approach keeps configuration separate from code and allows for easier management of different environments. |
| 56 | +::: |
| 57 | + |
| 58 | +## Usage |
| 59 | + |
| 60 | +In the example below, we are adding `OpenTelemetryConnector` to the pipeline as a _tracer_. Each pipeline run will produce a trace that includes the entire execution context, including prompts, completions, and metadata. You can then view the traces in your OpenTelemetry backend. |
| 61 | + |
| 62 | +```python |
| 63 | +import os |
| 64 | + |
| 65 | +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" |
| 66 | + |
| 67 | +from opentelemetry import trace |
| 68 | +from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter |
| 69 | +from opentelemetry.sdk.resources import Resource |
| 70 | +from opentelemetry.sdk.trace import TracerProvider |
| 71 | +from opentelemetry.sdk.trace.export import BatchSpanProcessor |
| 72 | +from opentelemetry.semconv.resource import ResourceAttributes |
| 73 | + |
| 74 | +# Configure the OpenTelemetry SDK. A service name is required for most backends. |
| 75 | +resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"}) |
| 76 | +tracer_provider = TracerProvider(resource=resource) |
| 77 | +tracer_provider.add_span_processor( |
| 78 | + BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")), |
| 79 | +) |
| 80 | +trace.set_tracer_provider(tracer_provider) |
| 81 | + |
| 82 | +from haystack import Pipeline |
| 83 | +from haystack.components.builders import ChatPromptBuilder |
| 84 | +from haystack.components.generators.chat import OpenAIChatGenerator |
| 85 | +from haystack.dataclasses import ChatMessage |
| 86 | + |
| 87 | +from haystack_integrations.components.connectors.opentelemetry import ( |
| 88 | + OpenTelemetryConnector, |
| 89 | +) |
| 90 | + |
| 91 | +pipe = Pipeline() |
| 92 | +pipe.add_component("tracer", OpenTelemetryConnector("Chat example")) |
| 93 | +pipe.add_component("prompt_builder", ChatPromptBuilder()) |
| 94 | +pipe.add_component("llm", OpenAIChatGenerator()) |
| 95 | +pipe.connect("prompt_builder.prompt", "llm.messages") |
| 96 | + |
| 97 | +messages = [ |
| 98 | + ChatMessage.from_system( |
| 99 | + "Always respond in German even if some input data is in other languages.", |
| 100 | + ), |
| 101 | + ChatMessage.from_user("Tell me about {{location}}"), |
| 102 | +] |
| 103 | + |
| 104 | +response = pipe.run( |
| 105 | + data={ |
| 106 | + "prompt_builder": { |
| 107 | + "template_variables": {"location": "Berlin"}, |
| 108 | + "template": messages, |
| 109 | + }, |
| 110 | + }, |
| 111 | +) |
| 112 | +print(response["llm"]["replies"][0]) |
| 113 | +``` |
| 114 | + |
| 115 | +### Configuring the tracing backend directly |
| 116 | + |
| 117 | +Instead of using the `OpenTelemetryConnector`, you can configure the OpenTelemetry tracing backend directly by enabling an `OpenTelemetryTracer`. Make sure to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable and configure your `TracerProvider` before importing any Haystack components. |
| 118 | + |
| 119 | +```python |
| 120 | +from opentelemetry import trace |
| 121 | + |
| 122 | +from haystack import tracing |
| 123 | +from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer |
| 124 | + |
| 125 | +tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application"))) |
| 126 | +``` |
0 commit comments