Cómo habilitar indicadores de telemetría en las bibliotecas cliente de Rust

Google Cloud proporciona servicios potentes de supervisión, registro y diagnóstico para las aplicaciones de Rust.

Las bibliotecas cliente de Rust están instrumentadas para emitir datos de seguimiento, métricas y registro. La instrumentación es opcional, por lo que debes habilitarla de forma explícita. En este documento, se describen los indicadores disponibles y cómo habilitarlos.

Indicadores disponibles

Las bibliotecas cliente de Rust están instrumentadas para generar los siguientes indicadores:

1. Intervalos INFO para cada solicitud lógica del cliente. Por lo general, una sola llamada de método en la estructura del cliente obtiene ese intervalo (por ejemplo, llamar a access_secret_version en un cliente SecretManagerService).
2. Una métrica de histograma que mide el tiempo transcurrido para cada solicitud lógica del cliente. La métrica principal es gcp.client.request.duration.
3. Registros WARN para cada solicitud lógica del cliente que falla.
4. Intervalos INFO para cada intento de RPC de bajo nivel. Por lo general, un solo método en la estructura del cliente obtiene uno de esos intervalos, pero puede haber más si la biblioteca tiene que volver a intentar la RPC.
5. Registros DEBUG para cada intento de bajo nivel que falla.

Estos intervalos y registros siguen las convenciones semánticas de OpenTelemetry con atributosadicionales Google Cloud . Tanto los intervalos como los registros deben ser adecuados para la supervisión de producción.

Los indicadores incluyen atributos estándar de OpenTelemetry (por ejemplo, http.response.status_code y rpc.system.name) y Google Cloud-específicos atributos personalizados, que pueden incluir estos y atributos similares:

• gcp.client.service: Es el nombre del servicio (por ejemplo, pubsub o storage).
• gcp.client.repo: Es el repositorio de la biblioteca cliente (por ejemplo, googleapis/google-cloud-rust).
• gcp.client.version: Es la versión de la biblioteca cliente.
• gcp.client.artifact: Es la ruta de acceso del módulo específico (por ejemplo, google-cloud-secretmanager).
• gcp.resource.destination.id: Es el ID del recurso en el que se está actuando.
• gcp.errors.domain: Es el dominio de error para los registros de errores procesables.
• gcp.errors.metadata.<key>: Son las claves de metadatos de error adicionales para las solicitudes fallidas (aplanadas).

Para obtener una lista completa de los atributos estándares, consulta las convenciones semánticas de HTTP y gRPC de OpenTelemetry.

Las bibliotecas también tienen intervalos DEBUG para cada solicitud. Estos incluyen el cuerpo completo de la solicitud, el cuerpo completo de la respuesta para las solicitudes correctas y el mensaje de error completo, con detalles, para las solicitudes fallidas.

Ten en cuenta el contenido de estas solicitudes y respuestas antes de habilitarlas en entornos de producción, ya que la solicitud o las respuestas pueden incluir datos sensibles.

Estos intervalos DEBUG usan el crate de la biblioteca cliente seguido de ::tracing como su destino (por ejemplo, google_cloud_secretmanager_v1::tracing) y el nombre del método como el nombre del intervalo (por ejemplo, access_secret_version). Puedes usar el nombre, el destino o ambos para configurar tus filtros.

Habilita la telemetría

Los indicadores de observabilidad en cualquier nivel pueden contener datos sensibles, como nombres de recursos, URLs completas y mensajes de error.

Antes de configurar suscriptores o exportadores para seguimientos y registros, revisa el contenido de los intervalos y consulta la documentación del framework de seguimiento para configurar filtros y formateadores para evitar la filtración de información sensible, según el caso de uso previsto.

Para proteger los datos sensibles, los indicadores de telemetría están inhabilitados de forma predeterminada.

En Rust, debes configurar el cliente para que emita seguimientos, métricas y registros y configurar suscriptores y exportadores para enviar estos indicadores a un servicio externo.

Para configurar el cliente, puedes establecer la siguiente variable de entorno:

export GOOGLE_CLOUD_RUST_LOGGING=true

Como alternativa, puedes habilitar el seguimiento de forma explícita mediante programación cuando compilas tu cliente con el método .with_tracing() en el compilador de clientes:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Propagación del contexto de seguimiento

Las bibliotecas cliente de Rust propagan automáticamente los contextos de seguimiento activos a Google Cloud los servicios, incluso si la generación de seguimientos no está habilitada de forma explícita con .with_tracing().

Usa los crates tracing-opentelemetry o opentelemetry para proporcionar un contexto de seguimiento para las bibliotecas cliente.

Exporta la telemetría

Una vez que se habilita la telemetría en las bibliotecas cliente, se debe configurar tu aplicación para recopilar y exportar estos datos a tu servicio de observabilidad. Las bibliotecas cliente de Rust usan de forma nativa el ecosistema de seguimiento.

Seguimiento

Para exportar los tracing intervalos generados por las Google Cloud bibliotecas cliente a OpenTelemetry, debes configurar un Subscriber en tu aplicación que canalice datos a un exportador de OpenTelemetry (por ejemplo, OTLP).

Usa los crates tracing-opentelemetry y opentelemetry-otlp para configurar el 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, debes instalar un MeterProvider global de OpenTelemetry en tu aplicación antes de inicializar el cliente. Las bibliotecas cliente lo usarán automáticamente para registrar y exportar datos de métricas.

Para obtener más detalles sobre la recopilación y exportación de datos de OpenTelemetry a Cloud Monitoring o Cloud Trace, consulta Elige un enfoque de instrumentación

Logging

Las bibliotecas cliente de Rust usan el crate tracing para emitir registros de errores procesables en los niveles WARN y DEBUG. Los registros exportados incluirán IDs de seguimiento y de intervalo para garantizar una correlación perfecta con tus seguimientos, siempre que uses un formateador adecuado.

Para enrutar estos registros estructurados a Cloud Logging, configura un suscriptor de seguimiento para formatear eventos como JSON y generar resultados en la salida estándar (stdout). Si realizas la implementación en un entorno como Google Kubernetes Engine o Cloud Run, los agentes integrados rastrean automáticamente estos registros.

En el siguiente ejemplo, se configura un suscriptor para capturar y enrutar solo los registros de nivel 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 obtener instrucciones detalladas sobre la configuración de los datos de correlación de seguimiento de OpenTelemetry (como logging.googleapis.com/trace) en el formateador JSON, consulta Descripción general de los ejemplos de instrumentación basados en recopiladores.