Tracing#

为了帮助调试和监控 Ray 应用程序，Ray 与 OpenTelemetry 集成，以便将追踪导出到 Jaeger 等外部追踪栈。

注意

Tracing (追踪) 是一个 Alpha 功能，不再积极开发/维护中。API 可能发生更改。

安装#

首先，安装 OpenTelemetry

pip install opentelemetry-api==1.34.1
pip install opentelemetry-sdk==1.34.1
pip install opentelemetry-exporter-otlp==1.34.1

Tracing startup hook (追踪启动钩子)#

要启用追踪，您必须提供一个追踪启动钩子，其中包含一个用于设置 Tracer Provider (追踪器提供程序)、Remote Span Processors (远程 Span 处理器) 和 Additional Instruments (附加仪器) 的函数。追踪启动钩子应该是一个不带任何参数或关键字参数的函数。此钩子需要在所有工作进程的 Python 环境中可用。

下面是一个示例追踪启动钩子，它设置了默认的追踪提供程序，将 spans 导出到 /tmp/spans 文件夹中的文件，并且没有附加任何仪器。

import ray
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)


def setup_tracing() -> None:
    # Creates /tmp/spans folder
    os.makedirs("/tmp/spans", exist_ok=True)
    # Sets the tracer_provider. This is only allowed once per execution
    # context and will log a warning if attempted multiple times.
    trace.set_tracer_provider(TracerProvider())
    trace.get_tracer_provider().add_span_processor(
        SimpleSpanProcessor(
            ConsoleSpanExporter(
                out=open(f"/tmp/spans/{os.getpid()}.json", "a")
                )
        )
    )

对于希望尝试追踪的开源用户，Ray 有一个默认的追踪启动钩子，可以将 spans 导出到 /tmp/spans 文件夹。要使用此默认钩子运行，请执行以下代码示例来设置追踪并追踪一个简单的 Ray Task。

$ ray start --head --tracing-startup-hook=ray.util.tracing.setup_local_tmp_tracing:setup_tracing
$ python
    ray.init()
    @ray.remote
    def my_function():
        return 1

    obj_ref = my_function.remote()

ray.init(_tracing_startup_hook="ray.util.tracing.setup_local_tmp_tracing:setup_tracing")

@ray.remote
def my_function():
    return 1

obj_ref = my_function.remote()

如果您想提供自己的自定义追踪启动钩子，请以 module:attribute 的格式提供，其中 attribute 是要运行的 setup_tracing 函数。

Tracer provider (追踪器提供程序)#

这配置了如何收集追踪。在此处查看 TracerProvider API：这里。

Remote span processors (远程 Span 处理器)#

这配置了追踪的导出目标。在此处查看 SpanProcessor API：这里。

希望尝试追踪的用户可以将他们的远程 Span 处理器配置为将 spans 导出到本地 JSON 文件。认真进行本地开发的Serious users可以通过 Jaeger exporter (Jaeger 导出器) 将追踪推送到 Jaeger 容器。

Additional instruments (附加仪器)#

如果您使用的是具有内置追踪支持的库，您提供的 setup_tracing 函数也应该能够 patch 这些库。您可以在此处找到有关这些库仪器化的更多文档：这里。

Custom traces (自定义追踪)#

在您的程序中添加自定义追踪。在您的程序中，使用 trace.get_tracer(__name__) 获取 tracer 对象，并使用 tracer.start_as_current_span(...) 启动一个新的 span。

以下是一个添加自定义追踪的简单示例。

from opentelemetry import trace

@ray.remote
def my_func():
    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("foo"):
        print("Hello world from OpenTelemetry Python!")