Python 和 OpenTelemetry

此页面适用于希望使用 OpenTelemetry 收集 Python 应用的 Cloud Trace 数据的开发者。OpenTelemetry 是一组用于收集跟踪记录和指标数据的插桩库;这些库与多个后端协同工作。如需使用 OpenTelemetry 和 Python 收集跟踪记录,请执行以下操作(如本页所述):

  • 安装 OpenTelemetry 软件包。
  • 配置应用以将 span 导出到 Cloud Trace。
  • 配置您的平台。

如需了解版本信息,请参阅以下内容:

有关适用于 Python 的 OpenTelemetry 的最新详细信息以及其他文档和示例,请参阅 OpenTelemetry

准备工作

  • 您必须使用 Python 3.6 或更高版本。
  • 为您的 Google Cloud 项目启用 Cloud Trace API:

    1. 点击下面的按钮,或者在 Google Cloud Console 中,选择 API 和服务,然后选择 Cloud Trace API

      转到 Trace API

    2. Cloud Trace API 页面上,如果显示了启用按钮,请点击该按钮。如果未显示此按钮,则表示所选项目已启用 Cloud Trace API。

安装 OpenTelemetry 软件包

如需安装所需的 OpenTelemetry 软件包,请执行以下操作:

  1. (可选)升级到 pip 的最新版本:

    pip install --upgrade pip
    
  2. 使用 pip 安装以下 OpenTelemetry 软件包:

    pip install opentelemetry-api \
      opentelemetry-sdk \
      opentelemetry-exporter-gcp-trace
    

导入 Trace 软件包

更新您的应用以导入以下软件包和类:

  • trace
  • CloudTraceSpanExporter
  • TracerProvider
  • 导出 Span 处理器:

    • 如需通过后台进程发送 span,请使用 BatchSpanProcessor 处理器。除非您使用的是 Cloud Run,否则我们建议您使用此处理器。Cloud Run 不支持后台进程。

    • 如需通过前台进程发送 span,请使用 SimpleSpanProcessor 处理器。如果您使用的是 Cloud Run,则必须使用此处理器。此处理器可能会拖慢应用的速度。

  • (可选)如果您希望关联 span,请导入 Link 类。

以下示例展示了这些导入语句:


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

配置将 span 导出到 Cloud Trace

如需将 span 发送到 Cloud Trace,请修改您的应用以使用 CloudTraceSpanExporter 导出器。以下示例展示了必需步骤:


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

向 span 添加属性

如需向 span 添加属性,请调用 span 的 set_attribute 方法。例如,以下代码向名为 foo_with_attribute 的 span 添加多个属性:


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

向 span 添加事件

如需向 span 添加事件,请调用 span 的 add_event 方法。例如,以下代码会向名为 foo_with_event 的 span 添加事件:


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

如需关联两个 span,请导入 Link 类,然后使用 start_as_current_span 方法中的 links 字段。关联两个 span 时,您可以在 links 字段中添加属性。

以下代码展示了可用于将 span 关联到名为 link_target 的 span 的两种方法:


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

示例 Flask 应用

OpenTelemetry 的 Flask 插桩旨在简化捕获与 HTTP 请求相关的跟踪记录内容。这意味着您无需在路由中为这些请求添加特定的插桩:

  • Flask 使用配置的传播器从传入的 HTTP 请求中提取 span 上下文。
  • Flask 会自动创建 span,其中含有描述请求和响应的属性。

如需查看使用 Flask 和 OpenTelemetry 的端到端示例,请参阅 flask_e2e。Git README 包含有关如何安装、配置和运行示例的信息。

本部分重点介绍示例的 server.py 文件中包含的特定于 Flask 的配置步骤。客户端库文件 client.py 使用 Requests 插桩来启用跟踪 requests 库发出的 HTTP 请求。

导入和导出

如需使用 OpenTelemetry 的 Flask 插桩,您必须导入 FlaskInstrumentor

如果您要确保由不同 Google Cloud 产品创建的 span 与同一跟踪记录相关联,则必须使用 Cloud Trace 传播器来配置传播器。该传播器指定使用 X-Cloud-Trace-Context 标头。如果您未配置该传播器,则 OpenTelemetry 会使用默认的传播器。在这种情况下,由不同的 Google Cloud 产品(如 Cloud Run 和 App Engine)创建的 span 位于独立的跟踪记录中。

以下示例展示了所需的导入和配置语句以及 Cloud Trace 传播器的配置:


import time

from flask import Flask
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

set_global_textmap(CloudTraceFormatPropagator())

配置 CloudTraceSpanExporter 导出器时,您无需添加任何特定于 Flask 的语句;配置将 span 导出到 Cloud Trace 中的配置已经足够。

初始化 Flask

配置 FlaskInstrumentor 来对应用进行插桩处理。以下示例说明了如何执行此步骤:


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

配置平台

您可以在 Google Cloud 和其他平台上使用 Cloud Trace。

在 Google Cloud 上运行

当您的应用在 Google Cloud 上运行时,您无需向客户端库提供服务帐号形式的身份验证凭据。但是,您需要确保 Google Cloud Platform 已启用 Cloud Trace API 访问权限范围

如需查看受支持的 Google Cloud 环境的列表,请参阅环境支持

对于以下配置,默认的访问权限范围设置会启用 Cloud Trace API:

  • App Engine 柔性环境
  • App Engine 标准环境

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

如果您使用自定义访问权限范围,则必须确保已启用 Cloud Trace API 访问权限范围

  • 如需了解如何使用 Google Cloud Console 为您的环境配置访问权限范围,请参阅配置 Google Cloud 项目

  • 对于 gcloud 用户,请使用 --scopes 标志指定访问权限范围,并添加 trace.append Cloud Trace API 访问权限范围。例如,如需创建仅启用了 Cloud Trace API 的 GKE 集群,请执行以下操作:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

在本地和其他位置运行

如果您的应用在 Google Cloud 之外运行,则必须向客户端库提供服务帐号形式的身份验证凭据。该服务帐号必须包含 Cloud Trace Agent 角色。如需查看说明,请参阅创建服务帐号

Google Cloud 客户端库会使用应用默认凭据 (ADC) 查找应用的凭据。您可以通过设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量来提供这些凭据:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

查看跟踪记录

部署后,您可以在 Cloud Console 跟踪记录查看器中查看跟踪记录。

转到“跟踪记录查看器”页面

问题排查

如需了解如何排查 Cloud Trace 的问题,请转到“问题排查”页面

资源