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 aplicaciones de Rust.

Las bibliotecas cliente de Rust están instrumentadas para emitir datos de registro, métricas y seguimiento. 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. INFO abarca 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. Es 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 de WARN para cada solicitud lógica del cliente que falla.
  4. INFO abarca cada intento de RPC de bajo nivel. Por lo general, un solo método en la estructura del cliente obtiene un intervalo de este tipo, pero puede haber más si la biblioteca tiene que reintentar la RPC.
  5. Registros de DEBUG para cada intento de bajo nivel que falla.

Estos intervalos y registros siguen las Convenciones Semánticas de OpenTelemetry con atributosGoogle Cloud adicionales. 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 atributos personalizados específicos de Google Cloud, que pueden incluir estos y otros 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 específica del módulo (por ejemplo, google-cloud-secretmanager).
  • gcp.resource.destination.id: Es el ID del recurso sobre el que se realiza la acción.
  • gcp.errors.domain: Es el dominio de error para los registros de errores prácticos.
  • gcp.errors.metadata.<key>: Son claves de metadatos de error adicionales para solicitudes fallidas (aplanadas).

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

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 exitosas 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 pueden incluir datos sensibles.

Estos intervalos de 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.

Cómo habilitar la telemetría

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 registros, métricas y seguimientos y configurar suscriptores y exportadores para que envíen 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 registro de forma explícita y programática 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 los servicios deGoogle Cloud , incluso si la generación de registros 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.

Exportación de datos de telemetría

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

Seguimiento

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

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 prácticos 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 los eventos como JSON y generar un resultado estándar (stdout). Si realizas la implementación en un entorno como Google Kubernetes Engine o Cloud Run, los agentes integrados recuperan 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 cómo configurar los datos de correlación de seguimiento de OpenTelemetry (como logging.googleapis.com/trace) en el formateador JSON, consulta Descripción general de las muestras de instrumentación basadas en recopiladores.