日志自动仪表化示例

本页面演示了如何在 OpenTelemetry 中使用 Python 日志自动仪表化。

与追踪和指标不同,日志没有等效的 API,只有一个 SDK。对于 Python,您可以使用 Python 的 logger 库,然后 OTel SDK 会附加一个 OTLP 处理器到根记录器上,将 Python 记录器转换为 OTLP 记录器。这个过程的一种方法在 [OpenTelemetry Python 代码库][] 的日志示例中有详细记录。

另一种实现方法是通过 Python 对日志的自动仪表化支持。下面的示例基于 [OpenTelemetry Python 代码库][] 的日志示例。

虽然存在一个日志桥接 API,但它与追踪和指标的 API 不同,因为它不是应用开发者用来创建日志的。相反,开发者可以使用此桥接 API 在标准的针对特定语言的日志库中设置日志追加器。更多信息请参考此处

首先创建一个示例目录和示例的 Python 文件:

mkdir python-logs-example
cd python-logs-example
touch example.py

将以下内容粘贴到 example.py 中:

import logging

from opentelemetry import trace

tracer = trace.get_tracer_provider().get_tracer(__name__)

# Trace context correlation
with tracer.start_as_current_span("foo"):
    # Do something
    current_span = trace.get_current_span()
    current_span.add_event("This is a span event")
    logging.getLogger().error("This is a log message")

此处获取 OTel Collector 配置的副本,并将其保存为 python-logs-example/otel-collector-config.yaml

准备

执行以下示例时,建议使用虚拟环境。执行以下命令准备进行日志自动仪表化:

mkdir python_logs_example
virtualenv python_logs_example
source python_logs_example/bin/activate

安装

以下命令安装所需的软件包。opentelemetry-distro 包依赖于其他几个软件包,如用于自定义仪表化自己代码的 opentelemetry-sdk 和提供多个帮助自动仪表化程序的命令的 opentelemetry-instrumentation

pip install opentelemetry-distro
pip install opentelemetry-exporter-otlp

接下来的示例将结果发送到控制台。了解如何安装和配置OpenTelemetry Distro以将遥测数据发送到其他目标,比如 OpenTelemetry Collector。

注意:要通过 opentelemetry-instrument 使用自动仪表化,您必须通过环境变量或命令行对其进行配置。代理程序会创建一个不可通过其他方式修改的遥测管道。如果您需要对遥测管道进行更多自定义,请放弃使用代理程序,而是导入 OpenTelemetry SDK 和仪表化库到您的代码中,并在那里进行配置。您还可以通过导入 OpenTelemetry API 来扩展自动仪表化。有关详细信息,请参阅[API 参考][]。

执行

本节指导您执行自动仪表化的日志的过程。

在新的终端窗口中启动 OTel Collector:

docker run -it --rm -p 4317:4317 -p 4318:4318 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol-config.yml \
  --name otelcol \
  otel/opentelemetry-collector-contrib:0.76.1 \
  "--config=/etc/otelcol-config.yml"

打开另一个终端并运行 Python 程序:

source python_logs_example/bin/activate

export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
opentelemetry-instrument \
  --traces_exporter console,otlp \
  --metrics_exporter console,otlp \
  --logs_exporter console,otlp \
  --service_name python-logs-example \
  python $(pwd)/example.py

示例输出:

...
范围追踪 #0
范围追踪 SchemaURL:
范围仪表化 __main__
追踪 #0
    追踪 ID       : 389d4ac130a390d3d99036f9cd1db75e
    父 ID       :
    ID             : f318281c4654edc5
    名称           : foo
    类型           : 内部
    开始时间     : 2023-08-18 17:04:05.982564 +0000 UTC
    结束时间       : 2023-08-18 17:04:05.982667 +0000 UTC
    状态代码    : 未设置
    状态描述 :
事件:
事件 #0
     -> 名称: This is a span event
     -> 时间戳: 2023-08-18 17:04:05.982586 +0000 UTC

...

范围日志 #0
范围日志 SchemaURL:
范围仪表化 opentelemetry.sdk._logs._internal
日志记录 #0
观察时间戳: 1970-01-01 00:00:00 +0000 UTC
时间戳: 2023-08-18 17:04:05.982605056 +0000 UTC
严重性文本: ERROR
严重性数字: Error(17)
主体: Str(This is a log message)
属性:
     -> otelSpanID: Str(f318281c4654edc5)
     -> otelTraceID: Str(389d4ac130a390d3d99036f9cd1db75e)
     -> otelTraceSampled: Bool(true)
     -> otelServiceName: Str(python-logs-example)
追踪 ID: 389d4ac130a390d3d99036f9cd1db75e
追踪 ID: f318281c4654edc5
...

请注意,跨度事件和日志中的 SpanID(f318281c4654edc5)相同。日志 SDK 将当前 Span 的 SpanID 附加到任何记录的事件上,以提高相关遥测的能力。

最后修改 December 10, 2023: translate (a4350d6e)