在 Rust 客户端库中启用遥测信号

Google Cloud 可为 Rust 应用提供强大的监控、日志记录和诊断功能。

Rust 客户端库经过插桩处理，可发出跟踪记录、指标和日志记录数据。插桩是选择性加入的，您需要明确启用它。本文档介绍了可用的信号以及如何启用这些信号。

可用信号

Rust 客户端库经过插桩处理，可生成以下信号：

  1. 针对每个逻辑客户端请求的 INFO span。通常，客户端结构体中的单个方法调用会获得此类 span（例如，对 SecretManagerService 客户端调用 access_secret_version）。
  2. 用于衡量每个逻辑客户端请求所用时间的直方图指标。主要指标是 gcp.client.request.duration。
  3. 针对每个失败的逻辑客户端请求的 WARN 日志。
  4. 针对每个低级别 RPC 尝试的 INFO span。通常，客户端结构体中的单个方法会获得一个此类 span，但如果库必须重试 RPC，则可能会有更多此类 span。
  5. 针对每个失败的低级别尝试的 DEBUG 日志。

这些 span 和日志遵循 OpenTelemetry Semantic Conventions，并包含其他 Google Cloud 属性。span 和日志都应适用于生产环境监控。

这些信号包括标准 OpenTelemetry 属性（例如 http.response.status_code 和 rpc.system.name）以及 Google Cloud特定于 Google Cloud 的自定义属性，这些属性可能包括以下属性和类似属性：

  • gcp.client.service：服务名称（例如 pubsub 或 storage）。
  • gcp.client.repo：客户端库代码库（例如 googleapis/google-cloud-rust）。
  • gcp.client.version：客户端库版本。
  • gcp.client.artifact：特定模块路径（例如 google-cloud-secretmanager）。
  • gcp.resource.destination.id：所操作资源的 ID。
  • gcp.errors.domain：可操作错误日志的错误网域。
  • gcp.errors.metadata.<key>：失败请求的其他错误元数据键（扁平化）。

如需查看完整的标准属性列表，请参阅 OpenTelemetry HTTP 和 gRPC 语义惯例。

这些库还针对每个请求提供 DEBUG span。这些 span 包括完整的请求正文、成功请求的完整响应正文，以及失败请求的完整错误消息（包含详细信息）。

在生产环境中启用这些请求和响应之前，请考虑这些请求和响应的内容，因为请求或响应可能包含敏感数据。

这些 DEBUG span 使用客户端库 crate，后跟 ::tracing 作为 其目标（例如 google_cloud_secretmanager_v1::tracing），并使用 方法名称作为 span 名称（例如 access_secret_version）。您可以使用 名称、目标或两者来设置过滤条件。

启用遥测

为保护敏感数据，遥测信号默认处于停用状态。

在 Rust 中，您必须配置客户端以发出跟踪记录、指标和日志，并且 必须配置订阅者和导出器以将这些信号发送到外部服务。

如需配置客户端，您可以设置以下环境变量：

export GOOGLE_CLOUD_RUST_LOGGING=true

或者，您也可以在构建客户端时使用客户端构建器上的 .with_tracing() 方法以编程方式明确启用跟踪：

use google_cloud_secretmanager_v1::client::SecretManagerService;

let client = SecretManagerService::builder()
    .with_tracing()
    .build()
    .await?;

跟踪上下文传播

Rust 客户端库会自动将活跃跟踪上下文传播到 Google Cloud 服务，即使未使用 .with_tracing()明确启用跟踪生成也是如此。

使用 tracing-opentelemetry 或 opentelemetry crate 为客户端库提供跟踪 上下文。

导出遥测数据

在客户端库中启用遥测后，您必须将应用配置为收集此数据并将其导出到可观测性服务。 Rust 客户端库原生使用 跟踪生态系统。

跟踪

如需将 tracing span 导出到 OpenTelemetry，您必须在应用中配置一个 Subscriber，该订阅者会将 数据通过管道传输到 OpenTelemetry 导出器（例如 OTLP）。 Google Cloud

使用 tracing-opentelemetry 和 opentelemetry-otlp crate 配置导出器：

use google_cloud_secretmanager_v1::client::SecretManagerService;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample() -> anyhow::Result<()> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("example");

    // Create a tracing layer that sends data to an OpenTelemetry Collector running on localhost.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

    // Register the subscriber globally
    let subscriber = Registry::default().with(telemetry);
    tracing::subscriber::set_global_default(subscriber)?;

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

指标

如需导出指标，您必须先在应用中安装全局 OpenTelemetry MeterProvider，然后再初始化客户端。客户端库会自动使用它来记录和导出指标数据。

如需详细了解如何收集 OpenTelemetry 数据并将其导出到 Cloud Monitoring 或 Cloud Trace，请参阅选择插桩 方法。

日志记录

Rust 客户端库使用 tracing crate 在 WARN 和 DEBUG 级别发出可操作的错误日志。导出的日志将包含跟踪记录 ID 和 span ID，以确保与跟踪记录无缝关联，前提是您使用适当的格式化程序。

如需将这些结构化日志路由到 Cloud Logging，请配置跟踪订阅者以将事件格式化为 JSON 并输出到标准输出 (stdout)。如果您要部署到 Google Kubernetes Engine 或 Cloud Run 等环境，内置代理会自动抓取这些日志。

以下示例配置了一个订阅者，用于仅捕获和路由 WARN 级别的日志。

use google_cloud_secretmanager_v1::client::SecretManagerService;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

pub async fn sample() -> anyhow::Result<()> {
    // Enable all `WARN` logs to include failed client requests in all client libraries.
    let filter = tracing_subscriber::EnvFilter::new("warn");

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

如需详细了解如何在 JSON 格式化程序中配置 OpenTelemetry 跟踪记录关联 数据（例如 logging.googleapis.com/trace），请参阅基于收集器的插桩 示例概览。