Ativar sinais de telemetria em bibliotecas de cliente Rust

Google Cloud oferece funcionalidades avançadas de monitoramento, geração de registros e diagnóstico para aplicativos Rust.

As bibliotecas de cliente do Rust são instrumentadas para emitir dados de rastreamento, métricas e geração de registros. A instrumentação é opcional. É necessário ativá-la explicitamente. Este documento descreve os indicadores disponíveis e como ativá-los.

Indicadores disponíveis

As bibliotecas de cliente do Rust são instrumentadas para gerar os seguintes indicadores:

1. Abrangências INFO para cada solicitação lógica do cliente. Normalmente, uma única chamada de método na struct do cliente recebe um período desse tipo (por exemplo, chamar access_secret_version em um cliente SecretManagerService).
2. Uma métrica de histograma que mede o tempo decorrido para cada solicitação lógica do cliente. A métrica principal é gcp.client.request.duration.
3. Registros WARN para cada solicitação lógica do cliente que falha.
4. Abrangências INFO para cada tentativa de RPC de baixo nível. Normalmente, um único método na struct do cliente recebe um período desse tipo, mas pode haver mais se a biblioteca precisar repetir a RPC.
5. Registros DEBUG para cada tentativa de baixo nível que falha.

Essas abrangências e registros seguem as convenções semânticas do OpenTelemetry com atributos Google Cloud adicionais. As abrangências e os registros são adequados para monitoramento de produção.

Os indicadores incluem atributos padrão do OpenTelemetry (por exemplo, http.response.status_code e rpc.system.name) e Google Cloud-específicos atributos personalizados, que podem incluir estes e atributos semelhantes:

• gcp.client.service: o nome do serviço (por exemplo, pubsub ou storage).
• gcp.client.repo: o repositório da biblioteca de cliente (por exemplo, googleapis/google-cloud-rust).
• gcp.client.version: a versão da biblioteca de cliente.
• gcp.client.artifact: o caminho do módulo específico (por exemplo, google-cloud-secretmanager).
• gcp.resource.destination.id: o ID do recurso em que a ação está sendo realizada.
• gcp.errors.domain: o domínio de erro para registros de erros acionáveis.
• gcp.errors.metadata.<key>: chaves de metadados de erro adicionais para solicitações com falha (aplanadas).

Para uma lista completa de atributos padrão, consulte as convenções semânticas HTTP e gRPC do OpenTelemetry.

As bibliotecas também têm abrangências DEBUG para cada solicitação. Elas incluem o corpo completo da solicitação, o corpo completo da resposta para solicitações bem-sucedidas e a mensagem de erro completa, com detalhes, para solicitações com falha.

Considere o conteúdo dessas solicitações e respostas antes de ativá-las em ambientes de produção, já que elas podem incluir dados sensíveis.

Esses períodos DEBUG usam o crate da biblioteca de cliente seguido por ::tracing como destino (por exemplo, google_cloud_secretmanager_v1::tracing) e o nome do método como o nome do período (por exemplo, access_secret_version). É possível usar o nome, o destino ou ambos para configurar os filtros.

Como ativar a telemetria

Os indicadores de observabilidade em qualquer nível podem conter dados sensíveis, como nomes de recursos, URLs completos e mensagens de erro.

Antes de configurar assinantes ou exportadores para traces e registros, revise o conteúdo das abrangências e consulte a documentação do framework de rastreamento para configurar filtros e formatadores para evitar o vazamento de informações sensíveis, dependendo do caso de uso pretendido.

Para proteger dados sensíveis, os indicadores de telemetria são desativados por padrão.

No Rust, é necessário configurar o cliente para emitir traces, métricas e registros e configurar assinantes e exportadores para enviar esses indicadores a um serviço externo.

Para configurar o cliente, defina a seguinte variável de ambiente:

export GOOGLE_CLOUD_RUST_LOGGING=true

Como alternativa, é possível ativar explicitamente o rastreamento de maneira programática ao criar o cliente usando o método .with_tracing() no criador do cliente:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Propagação do contexto de trace

As bibliotecas de cliente do Rust propagam automaticamente contextos de trace ativos para Google Cloud serviços, mesmo que a geração de trace não esteja ativada explicitamente usando .with_tracing().

Use os crates tracing-opentelemetry ou opentelemetry para fornecer um contexto de rastreamento para as bibliotecas de cliente.

Como exportar a telemetria

Depois que a telemetria é ativada nas bibliotecas de cliente, o aplicativo precisa ser configurado para coletar e exportar esses dados para o serviço de observabilidade. As bibliotecas de cliente do Rust usam o rastreamento ecossistema de maneira nativa.

Rastreamento

Para exportar as tracing abrangências geradas pelas Google Cloud bibliotecas de cliente para o OpenTelemetry, é necessário configurar um Subscriber no aplicativo que canaliza dados para um exportador do OpenTelemetry (por exemplo, OTLP).

Use os crates tracing-opentelemetry e opentelemetry-otlp para configurar o exportador:

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(())
}

Métricas

Para exportar métricas, é necessário instalar um MeterProvider global do OpenTelemetry no aplicativo antes de inicializar o cliente. As bibliotecas de cliente o usarão automaticamente para registrar e exportar dados de métricas.

Para mais detalhes sobre como coletar e exportar dados do OpenTelemetry para o Cloud Monitoring ou o Cloud Trace, consulte Escolher uma abordagem de instrumentação.

Logging

As bibliotecas de cliente do Rust usam o crate tracing para emitir registros de erros acionáveis nos níveis WARN e DEBUG. Os registros exportados vão incluir IDs de trace e IDs de abrangência para garantir a correlação perfeita com os traces, desde que você use um formatador adequado.

Para encaminhar esses registros estruturados para o Cloud Logging, configure um assinante de rastreamento para formatar eventos como JSON e gerar saída padrão (stdout). Se você estiver fazendo a implantação em um ambiente como o Google Kubernetes Engine ou o Cloud Run, os agentes integrados vão extrair esses registros automaticamente.

O exemplo a seguir configura um assinante para capturar e encaminhar apenas registros de nível 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(())
}

Para instruções detalhadas sobre como configurar os dados de correlação de trace do OpenTelemetry (como logging.googleapis.com/trace) no formatador JSON, consulte Visão geral dos exemplos de instrumentação baseados em coletores.