文档API 参考📓 教程🧑‍🍳 食谱🤝 集成💜 Discord🎨 Studio
文档

跟踪

本页面解释了如何在 Haystack 中使用追踪。它描述了如何使用 OpenTelemetry、Datadog 或您自己的解决方案设置追踪后端。这有助于您监控应用程序的性能并对其进行优化。

建议编辑

追踪记录了请求在应用程序中的流动过程，对于生产环境中应用程序的监控至关重要。这有助于理解 pipeline 组件的执行顺序，并分析 pipeline 花费时间最多的地方。

配置追踪后端

经过 instrumented 的应用程序通常会将追踪发送到追踪收集器或追踪后端。Haystack 为 OpenTelemetry 和 Datadog 提供了开箱即用的支持。您也可以快速实现对您选择的其他提供商的支持。

OpenTelemetry

要使用 OpenTelemetry 作为您的追踪后端，请遵循以下步骤：

  1. 安装 OpenTelemetry SDK

    pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp

  2. 为了将追踪深入到 pipeline 的更深层次，我们建议您查看 OpenTelemetry 集成，例如：

  3. 有两种方法可以将 Haystack 连接到 OpenTelemetry SDK。

    • 使用 OpenTelemetry 的 自动化 instrumentation 运行您的 Haystack 应用程序。Haystack 将自动检测配置好的追踪后端并使用它发送追踪。

      首先，请安装OpenTelemetry CLI

      pip install opentelemetry-distro

      然后，使用 OpenTelemetry SDK 运行您的 Haystack 应用程序。

      opentelemetry-instrument \
    --traces_exporter console \
    --metrics_exporter console \
    --logs_exporter console \
    --service_name my-haystack-app \
    <command to run your Haystack pipeline>

    — 或 —

    • 在您的 Python 代码中配置追踪后端

      from haystack import tracing

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from opentelemetry.semconv.resource import ResourceAttributes

# Service name is required for most backends
resource = Resource(attributes={
    ResourceAttributes.SERVICE_NAME: "haystack"  # Correct constant
})

tracer_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="https://:4318/v1/traces"))
tracer_provider.add_span_processor(processor)
trace.set_tracer_provider(tracer_provider)

# Tell Haystack to auto-detect the configured tracer
import haystack.tracing
haystack.tracing.auto_enable_tracing()

# Explicitly tell Haystack to use your tracer
from haystack.tracing import OpenTelemetryTracer

tracer = tracer_provider.get_tracer("my_application")
tracing.enable_tracing(OpenTelemetryTracer(tracer))

Datadog

要使用 Datadog 作为您的追踪后端，请遵循以下步骤：

  1. 安装 Datadog 的追踪库 ddtrace。

    pip install ddtrace

  2. 有两种方法可以将 Haystack 连接到 ddtrace。

    • 使用ddtrace: 
      ddtrace <command to run your Haystack pipeline

    — 或 —

    • 在您的 Python 代码中配置 Datadog 追踪后端

      from haystack.tracing import DatadogTracer
from haystack import tracing
import ddtrace

tracer = ddtrace.tracer
tracing.enable_tracing(DatadogTracer(tracer))

Langfuse

组件 `LangfuseConnector` 允许您轻松地使用 Langfuse UI 追踪您的 Haystack pipelines。

只需使用以下命令安装该组件：pip install langfuse-haystack，然后将其添加到您的 pipeline 中。

📘

有关更多详细信息和示例用法，请查看该组件的 文档页面，或查看我们的 博客文章 以获取完整的演练。

Weights & Biases Weave

该组件 `WeaveConnector` 允许您在 Weights & Biases 框架中追踪和可视化您的 pipeline 执行。

您首先需要在 Weights & Biases 网站上创建一个免费账户并获取您的 API 密钥，以及使用以下命令安装集成：pip install weights_biases-haystack.

📘

有关更多详细信息和示例用法，请查看该组件的 文档页面。

自定义追踪后端

要使用您自定义的追踪后端与 Haystack，请遵循以下步骤：

  1. 实现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:
			 # Tracing backends usually don't support any tag value
			 # `coerce_tag_value` forces the value to either be a Python
			 # primitive (int, float, boolean, str) or tries to dump it as string.
       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)

  2. 告诉 Haystack 使用您的自定义追踪器

    from haystack import tracing

haystack_tracer = OpenTelemetryTracer(tracer)
tracing.enable_tracing(haystack_tracer)

禁用自动追踪

Haystack 在以下情况下会自动检测并启用追踪：

  • 如果已安装并配置了用于 OpenTelemetry 的 `opentelemetry-sdk`。
  • 如果已安装用于 Datadog 的 `ddtrace`。

要禁用此行为，有两种选择：

  • 在运行 Haystack 应用程序时，将环境变量HAYSTACK_AUTO_TRACE_ENABLED 设置为false。

— 或 —

  • 在 Python 中禁用追踪

    from haystack.tracing import disable_tracing

disable_tracing()

内容追踪

Haystack 还允许您追踪 pipeline 组件的输入和输出值。这对于逐步检查 pipeline 执行非常有用。

默认情况下，此行为被禁用，以防止敏感用户信息发送到您的追踪后端。

要启用内容追踪，有两种选择：

  • 在运行 Haystack 应用程序时，将环境变量在运行 Haystack 应用程序时，将环境变量 `HAYSTACK_CONTENT_TRACING_ENABLED` 设置为true。

— 或 —

  • 在 Python 中显式启用内容追踪

    from haystack import tracing

tracing.tracer.is_content_tracing_enabled = True

在开发过程中可视化追踪

使用 Jaeger 作为本地 pipeline 开发的轻量级追踪后端。这允许您在无需复杂追踪后端的情况下进行追踪实验。

An illustrative screenshot of Jaeger UI.

  1. 运行 Jaeger 容器。这将创建一个追踪后端以及一个用于可视化追踪的用户界面。

    docker 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

  2. 安装 OpenTelemetry SDK

    pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp

  3. 配置OpenTelemetry 使用 Jaeger 后端。

    from opentelemetry.sdk.resources import Resource
from opentelemetry.semconv.resource import ResourceAttributes

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Service name is required for most backends
resource = Resource(attributes={
    ResourceAttributes.SERVICE_NAME: "haystack"
})

tracer_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="https://:4318/v1/traces"))
tracer_provider.add_span_processor(processor)
trace.set_tracer_provider(tracer_provider)

  4. 告诉 Haystack 使用 OpenTelemetry 进行追踪。

    import haystack.tracing

haystack.tracing.auto_enable_tracing()

  5. 运行您的 pipeline。

    ...
pipeline.run(...)
...

  6. 在 Jaeger 提供的 UI 中查看追踪，地址为 https://:16686。

实时管道日志记录

使用 Haystack 的 LoggingTracer 日志记录，以实时检查通过管道的数据。

此功能在实验和原型制作期间特别有用，因为您无需预先设置任何追踪后端。

以下是启用此追踪器的方法。在此示例中，我们添加了颜色标签（可选），以突出显示组件的名称和输入

import logging
from haystack import tracing
from haystack.tracing.logging_tracer import LoggingTracer

logging.basicConfig(format="%(levelname)s - %(name)s -  %(message)s", level=logging.WARNING)
logging.getLogger("haystack").setLevel(logging.DEBUG)

tracing.tracer.is_content_tracing_enabled = True # to enable tracing/logging content (inputs/outputs)
tracing.enable_tracing(LoggingTracer(tags_color_strings={"haystack.component.input": "\x1b[1;31m", "haystack.component.name": "\x1b[1;34m"}))

以下是运行管道时生成的日志的样子

更新于 5 个月前