Python 和 OpenTelemetry

此页面适用于希望使用 OpenTelemetry 收集 Python 应用的 Cloud Trace 数据的开发者。OpenTelemetry 是一个供应商中立的插桩框架，可用于收集跟踪记录和指标数据。如需了解如何对代码进行插桩，请参阅插桩和可观测性。

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

如需了解版本信息，请参阅以下内容：

如需了解 OpenTelemetry 参考内容，请参阅以下内容：

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

准备工作

  • 您必须使用 Python 3.6 或更高版本。

  • 在 Google Cloud 控制台的导航面板中，选择 API 和服务，点击启用 API 和服务，然后启用 Cloud Trace API：

    转到 Cloud Trace API 设置

  • 如果系统显示 API 已启用，则表示此 API 已经启用。如未显示，请点击启用按钮。

安装 OpenTelemetry 软件包

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

  1. （可选）升级到 pip 的最新版本：

    pip install --upgrade pip

  2. 使用 pip 安装以下 OpenTelemetry 软件包：

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

导入 Trace 软件包

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

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


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 metrics, trace
from opentelemetry.exporter.cloud_monitoring import (
    CloudMonitoringMetricsExporter,
)
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.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
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 控制台为您的环境配置访问权限范围，请参阅配置 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) 查找应用的凭据。

您可以通过以下三种方式之一提供这些凭据：

  • 运行：gcloud auth application-default login

  • 将服务帐号放置在操作系统的默认路径中。 下面列出了 Windows 和 Linux 的默认路径：

    • Windows：%APPDATA%/gcloud/application_default_credentials.json

    • Linux：$HOME/.config/gcloud/application_default_credentials.json

  • 将 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"

查看跟踪记录

在 Google Cloud 控制台的导航面板中，选择 Trace，然后选择 Trace 探索器：

转到 Trace 探索器

问题排查

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

资源