Mengaktifkan sinyal telemetri di library klien Rust

Google Cloud menyediakan pemantauan, logging, dan diagnostik yang andal untuk aplikasi Rust.

Library klien Rust diinstrumentasikan untuk memancarkan data tracing, metrik, dan logging. Pengukuran ini bersifat keikutsertaan; Anda harus mengaktifkannya secara eksplisit. Dokumen ini menjelaskan sinyal yang tersedia dan cara mengaktifkannya.

Sinyal yang tersedia

Library klien Rust diinstrumentasikan untuk menghasilkan sinyal berikut:

1. INFO rentang untuk setiap permintaan klien logis. Biasanya, satu panggilan metode dalam struct klien mendapatkan rentang tersebut (misalnya, memanggil access_secret_version pada klien SecretManagerService).
2. Metrik histogram yang mengukur waktu yang berlalu untuk setiap permintaan klien logis. Metrik utama adalah gcp.client.request.duration.
3. Log WARN untuk setiap permintaan klien logis yang gagal.
4. INFO untuk setiap upaya RPC tingkat rendah. Biasanya, satu metode dalam struct klien mendapatkan satu rentang tersebut, tetapi mungkin ada lebih banyak jika library harus mencoba ulang RPC.
5. DEBUG untuk setiap upaya tingkat rendah yang gagal.

Rentang dan log ini mengikuti Konvensi Semantik OpenTelemetry dengan atributGoogle Cloud tambahan. Rentang dan log harus sesuai untuk pemantauan produksi.

Sinyal mencakup atribut OpenTelemetry standar (misalnya, http.response.status_code dan rpc.system.name) serta atribut kustom khusus Google Cloud, yang dapat mencakup atribut ini dan atribut serupa:

• gcp.client.service: Nama layanan (misalnya, pubsub atau storage).
• gcp.client.repo: Repositori library klien (misalnya, googleapis/google-cloud-rust).
• gcp.client.version: Versi library klien.
• gcp.client.artifact: Jalur modul tertentu (misalnya, google-cloud-secretmanager).
• gcp.resource.destination.id: ID resource yang sedang ditindaklanjuti.
• gcp.errors.domain: Domain error untuk log error yang dapat ditindaklanjuti.
• gcp.errors.metadata.<key>: Kunci metadata error tambahan untuk permintaan yang gagal (diratakan).

Untuk daftar lengkap atribut standar, lihat konvensi semantik HTTP dan gRPC OpenTelemetry.

Library juga memiliki rentang DEBUG untuk setiap permintaan. Hal ini mencakup isi permintaan lengkap, isi respons lengkap untuk permintaan yang berhasil, dan pesan error lengkap, dengan detail, untuk permintaan yang gagal.

Pertimbangkan isi permintaan dan respons ini sebelum mengaktifkannya di lingkungan produksi, karena permintaan atau respons dapat mencakup data sensitif.

Rentang DEBUG ini menggunakan crate library klien yang diikuti dengan ::tracing sebagai targetnya (misalnya, google_cloud_secretmanager_v1::tracing) dan nama metode sebagai nama rentang (misalnya, access_secret_version). Anda dapat menggunakan nama, target, atau keduanya untuk menyiapkan filter.

Mengaktifkan telemetri

Sinyal kemampuan pengamatan di tingkat mana pun dapat berisi data sensitif seperti nama resource, URL lengkap, dan pesan error.

Sebelum mengonfigurasi subscriber atau eksportir untuk rekaman aktivitas dan log, tinjau konten rentang dan lihat dokumentasi framework pelacakan untuk menyiapkan filter dan pemformat guna mencegah kebocoran informasi sensitif, bergantung pada kasus penggunaan yang Anda inginkan.

Untuk melindungi data sensitif, sinyal telemetri dinonaktifkan secara default.

Di Rust, Anda harus mengonfigurasi klien untuk memancarkan rekaman aktivitas, metrik, dan log serta harus mengonfigurasi subscriber dan eksportir untuk mengirim sinyal ini ke layanan eksternal.

Untuk mengonfigurasi klien, Anda dapat menetapkan variabel lingkungan berikut:

export GOOGLE_CLOUD_RUST_LOGGING=true

Atau, Anda dapat mengaktifkan pelacakan secara eksplisit secara terprogram saat membangun klien dengan menggunakan metode .with_tracing() pada builder klien:

use google_cloud_secretmanager_v1::client::SecretManagerService;

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

Penerapan konteks rekaman aktivitas

Library klien Rust secara otomatis menyebarkan konteks rekaman aktivitas aktif ke Google Cloud layanan, meskipun pembuatan rekaman aktivitas tidak diaktifkan secara eksplisit menggunakan .with_tracing().

Gunakan crate tracing-opentelemetry atau opentelemetry untuk menyediakan konteks pelacakan bagi library klien.

Mengekspor telemetri

Setelah telemetri diaktifkan di library klien, aplikasi Anda harus dikonfigurasi untuk mengumpulkan dan mengekspor data ini ke layanan pengamatan Anda. Library klien Rust secara native menggunakan ekosistem tracing.

Pelacakan

Untuk mengekspor rentang tracing yang dihasilkan oleh library klien Google Cloud ke OpenTelemetry, Anda harus mengonfigurasi Subscriber di aplikasi yang menyalurkan data ke pengekspor OpenTelemetry (misalnya, OTLP).

Gunakan crate tracing-opentelemetry dan opentelemetry-otlp untuk mengonfigurasi pengekspor:

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

Metrik

Untuk mengekspor metrik, Anda harus menginstal MeterProvider OpenTelemetry global di aplikasi sebelum menginisialisasi klien. Library klien akan menggunakannya secara otomatis untuk merekam dan mengekspor data metrik.

Untuk mengetahui detail selengkapnya tentang cara mengumpulkan dan mengekspor data OpenTelemetry ke Cloud Monitoring atau Cloud Trace, lihat Memilih pendekatan instrumentasi.

Logging

Library klien Rust menggunakan crate tracing untuk memancarkan log error yang dapat ditindaklanjuti di level WARN dan DEBUG. Log yang diekspor akan menyertakan ID rekaman aktivitas dan ID rentang untuk memastikan korelasi yang lancar dengan rekaman aktivitas Anda, asalkan Anda menggunakan pemformat yang sesuai.

Untuk merutekan log terstruktur ini ke Cloud Logging, konfigurasi pelanggan pelacakan untuk memformat peristiwa sebagai JSON dan menghasilkan output ke output standar (stdout). Jika Anda men-deploy ke lingkungan seperti Google Kubernetes Engine atau Cloud Run, agen bawaan akan otomatis meng-scrape log ini.

Contoh berikut mengonfigurasi pelanggan untuk merekam dan merutekan hanya log tingkat 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(())
}

Untuk mengetahui petunjuk mendetail tentang cara mengonfigurasi data korelasi rekaman aktivitas OpenTelemetry (seperti logging.googleapis.com/trace) di pemformat JSON, lihat Ringkasan contoh instrumentasi berbasis pengumpul.