Haystack 与 OpenTelemetry 集成指南用 OpenTelemetryConnector 与 OpenTelemetryTracer 实现管线级可观测性【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackHaystack 是用于构建生产级 LLM 应用的 AI 编排框架本文聚焦于它在 OpenTelemetry 上的官方集成讲解如何通过OpenTelemetryConnector组件与OpenTelemetryTracer追踪器把管线Pipeline中各组件间的操作与数据流以 Span 的形式发送到任意兼容 OpenTelemetry 的后端。读完本文你将掌握从零配置 TracerProvider、启用内容追踪Content Tracing、在管线上挂载追踪组件以及结合 Jaeger 本地可视化追踪链路的完整实战方案。什么是 OpenTelemetry 集成OpenTelemetry 是一套开源的可观测性框架用于统一采集 traces追踪、metrics指标与 logs日志。Haystack 通过opentelemetry-haystack集成包与 OpenTelemetry 对接将每次管线运行产生的完整执行上下文包括输入提示词、生成结果与元数据发送到任何兼容 OpenTelemetry 的后端从而支持生产环境下的性能监控与故障排查。在本仓库中该集成对应两个核心概念OpenTelemetryConnector一个 Haystack 组件把它加入管线即可自动开启追踪OpenTelemetryTracer实现 HaystackTracer抽象接口的追踪器用于把 Span 写入 OpenTelemetry。此外Haystack 核心还内置了一套与具体后端无关的追踪基础设施tracer.py包括Tracer、Span抽象基类、ProxyTracer代理容器以及enable_tracing/disable_tracing/is_tracing_enabled等全局开关OpenTelemetryTracer正是这套基础设施在 OpenTelemetry 上的具体落地。前提条件在使用本集成之前需要先完成以下两件事安装集成包opentelemetry-haystack包含OpenTelemetryConnector与OpenTelemetryTracer。配置 OpenTelemetryTracerProvider至少需要提供一个带导出器Exporter的 TracerProvider例如使用 OTLP 导出器把 Span 发送到 Collector 或后端。TracerProvider 必须在启用追踪器之前完成配置。如果希望进一步下钻到管线更深层次的调用如 HTTP 请求、OpenAI 调用官方还推荐安装额外的 OpenTelemetry 生态工具例如urllib3instrumentation追踪管线中的 HTTP 请求OpenAI instrumentation追踪 OpenAI API 请求。这类工具并非必需但能让追踪数据更细粒度。快速开始在管线中启用 OpenTelemetry 追踪方式一使用 OpenTelemetryConnector 组件OpenTelemetryConnector连接 Haystack 与 OpenTelemetry用于启用管线组件内部操作及数据流的追踪。使用方式非常特殊把它加入管线即可但不要连接到任何其他组件——它作为一个独立节点存在于管线图中负责在追踪开启后自动标记所有管线操作。在初始化连接器之前必须确保 OpenTelemetry 的TracerProvider例如带导出器的 Provider已经配置完成。同时如果需要追踪管线组件的输入与输出内容还需把环境变量HAYSTACK_CONTENT_TRACING_ENABLED设为true。完整示例import os os.environ[HAYSTACK_CONTENT_TRACING_ENABLED] true 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 配置 OpenTelemetry SDK。大多数后端都要求提供服务名。 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) processor BatchSpanProcessor(OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces)) tracer_provider.add_span_processor(processor) trace.set_tracer_provider(tracer_provider) from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.components.connectors.opentelemetry import OpenTelemetryConnector pipe Pipeline() pipe.add_component(tracer, OpenTelemetryConnector()) pipe.add_component(prompt_builder, ChatPromptBuilder()) pipe.add_component(llm, OpenAIChatGenerator(modelgpt-4o-mini)) pipe.connect(prompt_builder.prompt, llm.messages) messages [ ChatMessage.from_system(Always respond in German even if some input data is in other languages.), ChatMessage.from_user(Tell me about {{location}}), ] response pipe.run( data{prompt_builder: {template_variables: {location: Berlin}, template: messages}} ) print(response[llm][replies][0])要点说明HAYSTACK_CONTENT_TRACING_ENABLED必须在导入任何 Haystack 组件之前设置因为该开关在模块导入阶段即被读取见下文内容追踪一节OpenTelemetryConnector与ChatPromptBuilder、OpenAIChatGenerator之间无需connect它独立工作管线运行时prompt_builder生成的提示词会被传入llm的messages输入槽这些数据流经管线时即可被追踪。方式二直接启用 OpenTelemetryTracer如果不想往管线里加组件也可以直接启用OpenTelemetryTracer。它同样会追踪任何 Haystack 管线的运行无需修改管线定义import os os.environ[HAYSTACK_CONTENT_TRACING_ENABLED] true 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 配置 OpenTelemetry SDK。服务名对大多数后端都是必需的。 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) tracer_provider.add_span_processor( BatchSpanProcessor(OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces)), ) trace.set_tracer_provider(tracer_provider) from haystack import tracing from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer # 启用 OpenTelemetry 追踪器 tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer(my_application)))之后每次pipeline.run(...)都会产生一条包含完整执行上下文的 trace可在兼容 OpenTelemetry 的后端中查看。两种方式的取舍维度OpenTelemetryConnectorOpenTelemetryTracer启用方式作为组件加入管线初始化后自动开启调用tracing.enable_tracing()全局启用是否需要连接其他组件否独立节点即可不适用管线定义侵入性需要修改管线无需修改管线适用场景希望把追踪作为管线配置的一部分管理希望全局统一开启追踪环境变量与配置项HAYSTACK_CONTENT_TRACING_ENABLED作用控制是否追踪管线组件的内容输入与输出例如查询内容、文档内容、回答内容等取值必须设置为字符串true才会启用默认关闭安全性默认关闭是为了防止敏感用户信息被发送到追踪后端解析位置在 tracer.py 中ProxyTracer.__init__通过os.getenv(HAYSTACK_CONTENT_TRACING_ENABLED_ENV_VAR, false).lower() true解析该变量因此在导入 Haystack 之前设置即可生效。也可以在 Python 中动态开启from haystack import tracing tracing.tracer.is_content_tracing_enabled TrueHAYSTACK_AUTO_TRACE_ENABLED用于控制 Haystack 是否自动探测并启用追踪后端。在 2.x 时代Haystack 会在满足以下条件时自动开启追踪已安装并配置opentelemetry-sdkOpenTelemetry已安装ddtraceDatadog。如果希望关闭这种自动行为可以运行应用时设置环境变量HAYSTACK_AUTO_TRACE_ENABLEDfalse或在 Python 中调用from haystack.tracing import disable_tracing disable_tracing():::note 版本差异 自 Haystack 3.0 起OpenTelemetry 追踪不再在安装opentelemetry-sdk时自动启用需要显式安装opentelemetry-haystack集成并启用OpenTelemetryTracer或添加OpenTelemetryConnector。本文 API 参考对应 2.22 版本使用时请留意版本差异。 :::组件 API 详解OpenTelemetryConnectorOpenTelemetryConnector连接 Haystack 与 OpenTelemetry以启用管线组件内操作与数据流的追踪。它位于集成包模块haystack_integrations.components.connectors.opentelemetry.opentelemetry_connector。__init____init__(name: str opentelemetry) - None初始化 OpenTelemetryConnector 组件。参数namestr——用于标识该追踪组件的名称会由run方法返回可用于标记该连接器产生的 trace。默认值为opentelemetry。runrun() - dict[str, str]运行 OpenTelemetryConnector 组件。返回值dict[str, str]——包含以下键的字典name追踪组件的名称。to_dictto_dict() - dict[str, Any]将组件序列化为字典。返回值dict[str, Any]——序列化后的组件字典用于 YAML/JSON 形式的管线配置与反序列化。from_dictfrom_dict(data: dict[str, Any]) - OpenTelemetryConnector从字典反序列化组件。参数datadict[str, Any]——组件的字典表示。返回值OpenTelemetryConnector——反序列化后的组件实例。OpenTelemetrySpanOpenTelemetrySpan包装了 OpenTelemetry 原生 Span使其符合 Haystack 的Span抽象接口。它位于haystack_integrations.tracing.opentelemetry.tracer。__init____init__(span: opentelemetry.trace.Span) - None创建 OpenTelemetrySpan 实例包装一个 OpenTelemetry 原生 Span 对象。set_tagset_tag(key: str, value: Any) - None在 Span 上设置单个标签。参数keystr——标签名称valueAny——标签值。注意值会被序列化后再写入因此最好使用字符串、数字、布尔值等简单类型。具体实现中标签值会先经过coerce_tag_value的强制转换见下文标签值序列化。raw_spanraw_span() - Any提供对追踪器底层 Span 对象的完整访问权限。返回值Any——底层 Span 对象。get_correlation_data_for_logsget_correlation_data_for_logs() - dict[str, Any]返回包含日志关联数据的字典可用于将日志与 trace 关联起来Log-Trace Correlation。OpenTelemetryTracerOpenTelemetryTracer是 HaystackTracer抽象基类的 OpenTelemetry 实现位于haystack_integrations.tracing.opentelemetry.tracer。__init____init__(tracer: opentelemetry.trace.Tracer) - None创建 OpenTelemetryTracer 实例包装一个 OpenTelemetry 原生Tracer对象。tracetrace( operation_name: str, tags: dict[str, Any] | None None, parent_span: Span | None None, ) - Iterator[Span]激活并返回一个新的 Span该 Span 继承自当前活动的 Span。参数operation_namestr——被追踪操作的名称tagsdict[str, Any] | None——应用到新建 Span 上的标签parent_spanSpan | None——新建 Span 的父 Span若为None新 Span 将成为根 Span。该方法以上下文管理器Context Manager形式使用配合with语句即可包裹一段代码的执行。current_spancurrent_span() - Span | None返回当前活动的 Span。返回值Span | None——当前活动的 Span如果没有活动 Span则返回None。深入底层Haystack 追踪基础设施OpenTelemetryTracer之所以能无缝工作是因为 Haystack 核心提供了一套与后端无关的追踪抽象tracer.py。理解这套机制有助于排查问题或编写自定义追踪器。Tracer 与 Span 抽象接口Span被插桩操作的接口核心方法是set_tag(key, value)设置单个标签、set_tags(tags)批量设置标签、raw_span()获取底层 Span、set_content_tag(key, value)设置包含敏感内容的标签默认受is_content_tracing_enabled门控、get_correlation_data_for_logs()返回日志关联数据Tracer通过trace(operation_name, tags, parent_span)上下文管理器创建并提交 Span并提供current_span()获取当前活动 Span。ProxyTracer 与全局开关tracer是一个全局ProxyTracer实例内部持有actual_tracer默认是NullTracer空实现。这种代理模式让你可以在不改变全局引用的情况下随时替换底层追踪器enable_tracing(provided_tracer)把全局追踪器替换为传入的Tracer实现disable_tracing()恢复为NullTracerno-opis_tracing_enabled()判断追踪是否开启。ProxyTracer同时负责在初始化时读取HAYSTACK_CONTENT_TRACING_ENABLED环境变量把结果存入is_content_tracing_enabled属性供Span.set_content_tag判断是否写入内容标签。标签值序列化大多数追踪后端不支持复杂类型作为标签值因此 Haystack 在 utils.py 中提供了coerce_tag_value对bool、str、int、float等原始类型直接透传对None转为空字符串对其他对象尝试序列化为 JSON 字符串序列化失败时退化为str(value)。其中_serializable_value会递归处理list/dict并在对象带有_to_trace_dict方法时使用其追踪表示、在对象带有to_dict方法时使用其字典表示从而把文档、消息等 Haystack 数据类安全地转成可观测的标签内容。内容追踪逐步审查管线输入输出Haystack 允许追踪管线组件的输入与输出值用于逐步骤调查管线执行情况。由于默认关闭避免敏感信息外泄开启方式有两种运行应用时设置环境变量HAYSTACK_CONTENT_TRACING_ENABLEDtrue command to run your Haystack pipeline在 Python 中显式开启from haystack import tracing tracing.tracer.is_content_tracing_enabled True从源码看内容追踪标签在多个位置被写入例如 pipeline.py 中_run_component使用span.set_content_tag(haystack.component.input, inputs)记录组件输入、span.set_content_tag(haystack.component.output, component_output)记录组件输出在 Agent 场景中agent.py 记录haystack.agent.input/haystack.agent.outputtool_calling.py 记录haystack.agent.step.tool.input/haystack.agent.step.tool.output含错误信息。这些标签在 OpenTelemetry 后端中呈现为 Span 上的属性可以精确还原每一步的输入与输出。需要提醒的是这些内容标签可能包含提示词、检索文档、模型回答等敏感数据生产环境中请根据合规要求谨慎开启。本地可视化用 Jaeger 调试追踪链路Jaeger 是轻量级的开源分布式追踪后端适合本地开发时可视化 Haystack 管线的执行顺序与耗时分布。整个链路如下启动 Jaeger 容器同时提供后端与 UIdocker run --rm -d --name jaeger \ -e COLLECTOR_ZIPKIN_HOST_PORT:9411 \ -p 6831:6831/udp \ -p 6832:6832/udp \ -p 5778:5778 \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ -p 14250:14250 \ -p 14268:14268 \ -p 14269:14269 \ -p 9411:9411 \ jaegertracing/all-in-one:latest其中16686为 Jaeger UI 端口4318为 OTLP HTTP 追踪接收端口。安装依赖pip install opentelemetry-sdk pip install opentelemetry-exporter-otlp配置 OpenTelemetry 指向 Jaegerfrom 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 服务名对大多数后端都是必需的 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) processor BatchSpanProcessor( OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces) ) tracer_provider.add_span_processor(processor) trace.set_tracer_provider(tracer_provider)启用追踪并运行管线import haystack.tracing haystack.tracing.auto_enable_tracing() # 2.x 自动探测方式 # 或tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer(my_application))) ... pipeline.run(...) ...查看结果在浏览器打开 Jaeger UIhttp://localhost:16686即可按服务名、操作名检索并查看 Span 的时间线、层级关系与标签。自定义追踪后端实现自己的 Tracer如果 OpenTelemetry 或 Datadog 都不满足需求可以基于 Haystack 的Tracer抽象快速实现自己的追踪器。以下示例以 OpenTelemetry 包为例展示实现要点import contextlib from typing import Optional, Dict, Any, Iterator from opentelemetry import trace from opentelemetry.trace import NonRecordingSpan from haystack.tracing import Tracer, Span from haystack.tracing import utils as tracing_utils import opentelemetry.trace class OpenTelemetrySpan(Span): def __init__(self, span: opentelemetry.trace.Span) - None: self._span span def set_tag(self, key: str, value: Any) - None: # 追踪后端通常不支持任意标签值 # coerce_tag_value 会强制把值转换为 Python 原始类型int/float/bool/str # 或尝试以字符串形式转储。 coerced_value tracing_utils.coerce_tag_value(value) self._span.set_attribute(key, coerced_value) class OpenTelemetryTracer(Tracer): def __init__(self, tracer: opentelemetry.trace.Tracer) - None: self._tracer tracer contextlib.contextmanager def trace( self, operation_name: str, tags: Optional[Dict[str, Any]] None ) - Iterator[Span]: with self._tracer.start_as_current_span(operation_name) as span: span OpenTelemetrySpan(span) if tags: span.set_tags(tags) yield span def current_span(self) - Optional[Span]: current_span trace.get_current_span() if isinstance(current_span, NonRecordingSpan): return None return OpenTelemetrySpan(current_span)然后让 Haystack 使用该自定义追踪器from haystack import tracing haystack_tracer OpenTelemetryTracer(tracer) tracing.enable_tracing(haystack_tracer)实现Tracer.trace时务必以上下文管理器返回 Span并正确处理current_span例如区分非录制 Span 与真实 Span这样管线内所有组件都会自动使用你的追踪器产生嵌套 Span。与其他追踪后端的横向定位除了 OpenTelemetryHaystack 2.22 时代还提供以下开箱即用的追踪方案便于你在选型时横向对比Datadog安装ddtrace后可用ddtrace command运行应用或在代码中tracing.enable_tracing(DatadogTracer(ddtrace.tracer))Langfuse通过LangfuseConnector组件pip install langfuse-haystack在 Langfuse UI 中可视化管线 traceWeights Biases Weave通过WeaveConnector组件pip install weave-haystack在 WB 框架中追踪与监控管线组件自定义后端实现Tracer接口即可接入任意可观测性平台。延伸阅读追踪总览与 Datadog、Langfuse、Weave 等方案tracing.mdx2.22 版本集成包 API 参考本文对应版本opentelemetry.mdHaystack 核心追踪基础设施源码tracer.py、utils.py管线中 Span 的写入位置pipeline.pyAgent 场景下的内容追踪agent.py、tool_calling.py【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Haystack 与 OpenTelemetry 集成指南：用 OpenTelemetryConnector 与 OpenTelemetryTracer 实现管线级可观测性
Haystack 与 OpenTelemetry 集成指南用 OpenTelemetryConnector 与 OpenTelemetryTracer 实现管线级可观测性【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystackHaystack 是用于构建生产级 LLM 应用的 AI 编排框架本文聚焦于它在 OpenTelemetry 上的官方集成讲解如何通过OpenTelemetryConnector组件与OpenTelemetryTracer追踪器把管线Pipeline中各组件间的操作与数据流以 Span 的形式发送到任意兼容 OpenTelemetry 的后端。读完本文你将掌握从零配置 TracerProvider、启用内容追踪Content Tracing、在管线上挂载追踪组件以及结合 Jaeger 本地可视化追踪链路的完整实战方案。什么是 OpenTelemetry 集成OpenTelemetry 是一套开源的可观测性框架用于统一采集 traces追踪、metrics指标与 logs日志。Haystack 通过opentelemetry-haystack集成包与 OpenTelemetry 对接将每次管线运行产生的完整执行上下文包括输入提示词、生成结果与元数据发送到任何兼容 OpenTelemetry 的后端从而支持生产环境下的性能监控与故障排查。在本仓库中该集成对应两个核心概念OpenTelemetryConnector一个 Haystack 组件把它加入管线即可自动开启追踪OpenTelemetryTracer实现 HaystackTracer抽象接口的追踪器用于把 Span 写入 OpenTelemetry。此外Haystack 核心还内置了一套与具体后端无关的追踪基础设施tracer.py包括Tracer、Span抽象基类、ProxyTracer代理容器以及enable_tracing/disable_tracing/is_tracing_enabled等全局开关OpenTelemetryTracer正是这套基础设施在 OpenTelemetry 上的具体落地。前提条件在使用本集成之前需要先完成以下两件事安装集成包opentelemetry-haystack包含OpenTelemetryConnector与OpenTelemetryTracer。配置 OpenTelemetryTracerProvider至少需要提供一个带导出器Exporter的 TracerProvider例如使用 OTLP 导出器把 Span 发送到 Collector 或后端。TracerProvider 必须在启用追踪器之前完成配置。如果希望进一步下钻到管线更深层次的调用如 HTTP 请求、OpenAI 调用官方还推荐安装额外的 OpenTelemetry 生态工具例如urllib3instrumentation追踪管线中的 HTTP 请求OpenAI instrumentation追踪 OpenAI API 请求。这类工具并非必需但能让追踪数据更细粒度。快速开始在管线中启用 OpenTelemetry 追踪方式一使用 OpenTelemetryConnector 组件OpenTelemetryConnector连接 Haystack 与 OpenTelemetry用于启用管线组件内部操作及数据流的追踪。使用方式非常特殊把它加入管线即可但不要连接到任何其他组件——它作为一个独立节点存在于管线图中负责在追踪开启后自动标记所有管线操作。在初始化连接器之前必须确保 OpenTelemetry 的TracerProvider例如带导出器的 Provider已经配置完成。同时如果需要追踪管线组件的输入与输出内容还需把环境变量HAYSTACK_CONTENT_TRACING_ENABLED设为true。完整示例import os os.environ[HAYSTACK_CONTENT_TRACING_ENABLED] true 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 配置 OpenTelemetry SDK。大多数后端都要求提供服务名。 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) processor BatchSpanProcessor(OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces)) tracer_provider.add_span_processor(processor) trace.set_tracer_provider(tracer_provider) from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack_integrations.components.connectors.opentelemetry import OpenTelemetryConnector pipe Pipeline() pipe.add_component(tracer, OpenTelemetryConnector()) pipe.add_component(prompt_builder, ChatPromptBuilder()) pipe.add_component(llm, OpenAIChatGenerator(modelgpt-4o-mini)) pipe.connect(prompt_builder.prompt, llm.messages) messages [ ChatMessage.from_system(Always respond in German even if some input data is in other languages.), ChatMessage.from_user(Tell me about {{location}}), ] response pipe.run( data{prompt_builder: {template_variables: {location: Berlin}, template: messages}} ) print(response[llm][replies][0])要点说明HAYSTACK_CONTENT_TRACING_ENABLED必须在导入任何 Haystack 组件之前设置因为该开关在模块导入阶段即被读取见下文内容追踪一节OpenTelemetryConnector与ChatPromptBuilder、OpenAIChatGenerator之间无需connect它独立工作管线运行时prompt_builder生成的提示词会被传入llm的messages输入槽这些数据流经管线时即可被追踪。方式二直接启用 OpenTelemetryTracer如果不想往管线里加组件也可以直接启用OpenTelemetryTracer。它同样会追踪任何 Haystack 管线的运行无需修改管线定义import os os.environ[HAYSTACK_CONTENT_TRACING_ENABLED] true 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 配置 OpenTelemetry SDK。服务名对大多数后端都是必需的。 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) tracer_provider.add_span_processor( BatchSpanProcessor(OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces)), ) trace.set_tracer_provider(tracer_provider) from haystack import tracing from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer # 启用 OpenTelemetry 追踪器 tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer(my_application)))之后每次pipeline.run(...)都会产生一条包含完整执行上下文的 trace可在兼容 OpenTelemetry 的后端中查看。两种方式的取舍维度OpenTelemetryConnectorOpenTelemetryTracer启用方式作为组件加入管线初始化后自动开启调用tracing.enable_tracing()全局启用是否需要连接其他组件否独立节点即可不适用管线定义侵入性需要修改管线无需修改管线适用场景希望把追踪作为管线配置的一部分管理希望全局统一开启追踪环境变量与配置项HAYSTACK_CONTENT_TRACING_ENABLED作用控制是否追踪管线组件的内容输入与输出例如查询内容、文档内容、回答内容等取值必须设置为字符串true才会启用默认关闭安全性默认关闭是为了防止敏感用户信息被发送到追踪后端解析位置在 tracer.py 中ProxyTracer.__init__通过os.getenv(HAYSTACK_CONTENT_TRACING_ENABLED_ENV_VAR, false).lower() true解析该变量因此在导入 Haystack 之前设置即可生效。也可以在 Python 中动态开启from haystack import tracing tracing.tracer.is_content_tracing_enabled TrueHAYSTACK_AUTO_TRACE_ENABLED用于控制 Haystack 是否自动探测并启用追踪后端。在 2.x 时代Haystack 会在满足以下条件时自动开启追踪已安装并配置opentelemetry-sdkOpenTelemetry已安装ddtraceDatadog。如果希望关闭这种自动行为可以运行应用时设置环境变量HAYSTACK_AUTO_TRACE_ENABLEDfalse或在 Python 中调用from haystack.tracing import disable_tracing disable_tracing():::note 版本差异 自 Haystack 3.0 起OpenTelemetry 追踪不再在安装opentelemetry-sdk时自动启用需要显式安装opentelemetry-haystack集成并启用OpenTelemetryTracer或添加OpenTelemetryConnector。本文 API 参考对应 2.22 版本使用时请留意版本差异。 :::组件 API 详解OpenTelemetryConnectorOpenTelemetryConnector连接 Haystack 与 OpenTelemetry以启用管线组件内操作与数据流的追踪。它位于集成包模块haystack_integrations.components.connectors.opentelemetry.opentelemetry_connector。__init____init__(name: str opentelemetry) - None初始化 OpenTelemetryConnector 组件。参数namestr——用于标识该追踪组件的名称会由run方法返回可用于标记该连接器产生的 trace。默认值为opentelemetry。runrun() - dict[str, str]运行 OpenTelemetryConnector 组件。返回值dict[str, str]——包含以下键的字典name追踪组件的名称。to_dictto_dict() - dict[str, Any]将组件序列化为字典。返回值dict[str, Any]——序列化后的组件字典用于 YAML/JSON 形式的管线配置与反序列化。from_dictfrom_dict(data: dict[str, Any]) - OpenTelemetryConnector从字典反序列化组件。参数datadict[str, Any]——组件的字典表示。返回值OpenTelemetryConnector——反序列化后的组件实例。OpenTelemetrySpanOpenTelemetrySpan包装了 OpenTelemetry 原生 Span使其符合 Haystack 的Span抽象接口。它位于haystack_integrations.tracing.opentelemetry.tracer。__init____init__(span: opentelemetry.trace.Span) - None创建 OpenTelemetrySpan 实例包装一个 OpenTelemetry 原生 Span 对象。set_tagset_tag(key: str, value: Any) - None在 Span 上设置单个标签。参数keystr——标签名称valueAny——标签值。注意值会被序列化后再写入因此最好使用字符串、数字、布尔值等简单类型。具体实现中标签值会先经过coerce_tag_value的强制转换见下文标签值序列化。raw_spanraw_span() - Any提供对追踪器底层 Span 对象的完整访问权限。返回值Any——底层 Span 对象。get_correlation_data_for_logsget_correlation_data_for_logs() - dict[str, Any]返回包含日志关联数据的字典可用于将日志与 trace 关联起来Log-Trace Correlation。OpenTelemetryTracerOpenTelemetryTracer是 HaystackTracer抽象基类的 OpenTelemetry 实现位于haystack_integrations.tracing.opentelemetry.tracer。__init____init__(tracer: opentelemetry.trace.Tracer) - None创建 OpenTelemetryTracer 实例包装一个 OpenTelemetry 原生Tracer对象。tracetrace( operation_name: str, tags: dict[str, Any] | None None, parent_span: Span | None None, ) - Iterator[Span]激活并返回一个新的 Span该 Span 继承自当前活动的 Span。参数operation_namestr——被追踪操作的名称tagsdict[str, Any] | None——应用到新建 Span 上的标签parent_spanSpan | None——新建 Span 的父 Span若为None新 Span 将成为根 Span。该方法以上下文管理器Context Manager形式使用配合with语句即可包裹一段代码的执行。current_spancurrent_span() - Span | None返回当前活动的 Span。返回值Span | None——当前活动的 Span如果没有活动 Span则返回None。深入底层Haystack 追踪基础设施OpenTelemetryTracer之所以能无缝工作是因为 Haystack 核心提供了一套与后端无关的追踪抽象tracer.py。理解这套机制有助于排查问题或编写自定义追踪器。Tracer 与 Span 抽象接口Span被插桩操作的接口核心方法是set_tag(key, value)设置单个标签、set_tags(tags)批量设置标签、raw_span()获取底层 Span、set_content_tag(key, value)设置包含敏感内容的标签默认受is_content_tracing_enabled门控、get_correlation_data_for_logs()返回日志关联数据Tracer通过trace(operation_name, tags, parent_span)上下文管理器创建并提交 Span并提供current_span()获取当前活动 Span。ProxyTracer 与全局开关tracer是一个全局ProxyTracer实例内部持有actual_tracer默认是NullTracer空实现。这种代理模式让你可以在不改变全局引用的情况下随时替换底层追踪器enable_tracing(provided_tracer)把全局追踪器替换为传入的Tracer实现disable_tracing()恢复为NullTracerno-opis_tracing_enabled()判断追踪是否开启。ProxyTracer同时负责在初始化时读取HAYSTACK_CONTENT_TRACING_ENABLED环境变量把结果存入is_content_tracing_enabled属性供Span.set_content_tag判断是否写入内容标签。标签值序列化大多数追踪后端不支持复杂类型作为标签值因此 Haystack 在 utils.py 中提供了coerce_tag_value对bool、str、int、float等原始类型直接透传对None转为空字符串对其他对象尝试序列化为 JSON 字符串序列化失败时退化为str(value)。其中_serializable_value会递归处理list/dict并在对象带有_to_trace_dict方法时使用其追踪表示、在对象带有to_dict方法时使用其字典表示从而把文档、消息等 Haystack 数据类安全地转成可观测的标签内容。内容追踪逐步审查管线输入输出Haystack 允许追踪管线组件的输入与输出值用于逐步骤调查管线执行情况。由于默认关闭避免敏感信息外泄开启方式有两种运行应用时设置环境变量HAYSTACK_CONTENT_TRACING_ENABLEDtrue command to run your Haystack pipeline在 Python 中显式开启from haystack import tracing tracing.tracer.is_content_tracing_enabled True从源码看内容追踪标签在多个位置被写入例如 pipeline.py 中_run_component使用span.set_content_tag(haystack.component.input, inputs)记录组件输入、span.set_content_tag(haystack.component.output, component_output)记录组件输出在 Agent 场景中agent.py 记录haystack.agent.input/haystack.agent.outputtool_calling.py 记录haystack.agent.step.tool.input/haystack.agent.step.tool.output含错误信息。这些标签在 OpenTelemetry 后端中呈现为 Span 上的属性可以精确还原每一步的输入与输出。需要提醒的是这些内容标签可能包含提示词、检索文档、模型回答等敏感数据生产环境中请根据合规要求谨慎开启。本地可视化用 Jaeger 调试追踪链路Jaeger 是轻量级的开源分布式追踪后端适合本地开发时可视化 Haystack 管线的执行顺序与耗时分布。整个链路如下启动 Jaeger 容器同时提供后端与 UIdocker run --rm -d --name jaeger \ -e COLLECTOR_ZIPKIN_HOST_PORT:9411 \ -p 6831:6831/udp \ -p 6832:6832/udp \ -p 5778:5778 \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ -p 14250:14250 \ -p 14268:14268 \ -p 14269:14269 \ -p 9411:9411 \ jaegertracing/all-in-one:latest其中16686为 Jaeger UI 端口4318为 OTLP HTTP 追踪接收端口。安装依赖pip install opentelemetry-sdk pip install opentelemetry-exporter-otlp配置 OpenTelemetry 指向 Jaegerfrom 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 BatchSpanProcessor from opentelemetry.semconv.resource import ResourceAttributes # 服务名对大多数后端都是必需的 resource Resource(attributes{ResourceAttributes.SERVICE_NAME: haystack}) tracer_provider TracerProvider(resourceresource) processor BatchSpanProcessor( OTLPSpanExporter(endpointhttp://localhost:4318/v1/traces) ) tracer_provider.add_span_processor(processor) trace.set_tracer_provider(tracer_provider)启用追踪并运行管线import haystack.tracing haystack.tracing.auto_enable_tracing() # 2.x 自动探测方式 # 或tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer(my_application))) ... pipeline.run(...) ...查看结果在浏览器打开 Jaeger UIhttp://localhost:16686即可按服务名、操作名检索并查看 Span 的时间线、层级关系与标签。自定义追踪后端实现自己的 Tracer如果 OpenTelemetry 或 Datadog 都不满足需求可以基于 Haystack 的Tracer抽象快速实现自己的追踪器。以下示例以 OpenTelemetry 包为例展示实现要点import contextlib from typing import Optional, Dict, Any, Iterator from opentelemetry import trace from opentelemetry.trace import NonRecordingSpan from haystack.tracing import Tracer, Span from haystack.tracing import utils as tracing_utils import opentelemetry.trace class OpenTelemetrySpan(Span): def __init__(self, span: opentelemetry.trace.Span) - None: self._span span def set_tag(self, key: str, value: Any) - None: # 追踪后端通常不支持任意标签值 # coerce_tag_value 会强制把值转换为 Python 原始类型int/float/bool/str # 或尝试以字符串形式转储。 coerced_value tracing_utils.coerce_tag_value(value) self._span.set_attribute(key, coerced_value) class OpenTelemetryTracer(Tracer): def __init__(self, tracer: opentelemetry.trace.Tracer) - None: self._tracer tracer contextlib.contextmanager def trace( self, operation_name: str, tags: Optional[Dict[str, Any]] None ) - Iterator[Span]: with self._tracer.start_as_current_span(operation_name) as span: span OpenTelemetrySpan(span) if tags: span.set_tags(tags) yield span def current_span(self) - Optional[Span]: current_span trace.get_current_span() if isinstance(current_span, NonRecordingSpan): return None return OpenTelemetrySpan(current_span)然后让 Haystack 使用该自定义追踪器from haystack import tracing haystack_tracer OpenTelemetryTracer(tracer) tracing.enable_tracing(haystack_tracer)实现Tracer.trace时务必以上下文管理器返回 Span并正确处理current_span例如区分非录制 Span 与真实 Span这样管线内所有组件都会自动使用你的追踪器产生嵌套 Span。与其他追踪后端的横向定位除了 OpenTelemetryHaystack 2.22 时代还提供以下开箱即用的追踪方案便于你在选型时横向对比Datadog安装ddtrace后可用ddtrace command运行应用或在代码中tracing.enable_tracing(DatadogTracer(ddtrace.tracer))Langfuse通过LangfuseConnector组件pip install langfuse-haystack在 Langfuse UI 中可视化管线 traceWeights Biases Weave通过WeaveConnector组件pip install weave-haystack在 WB 框架中追踪与监控管线组件自定义后端实现Tracer接口即可接入任意可观测性平台。延伸阅读追踪总览与 Datadog、Langfuse、Weave 等方案tracing.mdx2.22 版本集成包 API 参考本文对应版本opentelemetry.mdHaystack 核心追踪基础设施源码tracer.py、utils.py管线中 Span 的写入位置pipeline.pyAgent 场景下的内容追踪agent.py、tool_calling.py【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考