Crate gcp_rust_tools 

GCP Observability for Rust

A lightweight, high-performance Google Cloud Platform observability library for Rust applications. This crate provides easy-to-use APIs for Cloud Logging, Cloud Monitoring, and Cloud Trace using the gcloud CLI for authentication and the Google Cloud REST APIs for data submission.

Features

• Cloud Logging: Send structured logs to Google Cloud Logging
• Cloud Monitoring: Create custom metrics in Google Cloud Monitoring
• Cloud Trace: Create distributed traces in Google Cloud Trace
• Background Processing: Fire-and-forget API with background thread processing
• Automatic Token Refresh: Handles gcloud token expiration and re-authentication
• Error Resilience: Automatic retry logic for authentication failures
• Builder Pattern: Fluent API for constructing observability data

Architecture

The library uses a channel-based architecture with a single background worker thread:

• Main Thread: Your application code sends observability data to a channel
• Worker Thread: A dedicated std::thread processes queued items using async operations
• No Rate Limiting: The single-threaded model naturally prevents overwhelming the APIs
• Silent Failures: Background operations fail silently to avoid disrupting your application

Quick Start

use gcp_rust_tools::{ObservabilityClient, LogEntry, MetricData, TraceSpan};
use std::collections::HashMap;
use std::time::{SystemTime, Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the client (performs authentication)
    // Credentials are resolved internally from GOOGLE_APPLICATION_CREDENTIALS.
    // Project id is resolved from (in order): provided value, GOOGLE_CLOUD_PROJECT,
    // or `gcloud config get-value project`.
    let client = ObservabilityClient::new(
        Some("your-project-id".to_string()),
        None,
    ).await?;

    // Fire-and-forget logging (returns immediately, processes in background)
    client.send_log(LogEntry::new("INFO", "Application started"))?;
     
    // With service name
    client.send_log(
        LogEntry::new("ERROR", "Database connection failed")
            .with_service_name("api-server")
    )?;

    // Send metrics with labels
    let mut labels = HashMap::new();
    labels.insert("environment".to_string(), "production".to_string());
     
    client.send_metric(
        MetricData::new(
            "custom.googleapis.com/requests_total",
            42.0,
            "INT64",
            "GAUGE"
        ).with_labels(labels)
    )?;

    // Create distributed traces
    let trace_id = ObservabilityClient::generate_trace_id();
    let span_id = ObservabilityClient::generate_span_id();
     
    client.send_trace(
        TraceSpan::new(
            trace_id,
            span_id,
            "HTTP Request",
            SystemTime::now(),
            Duration::from_millis(150)
        )
    )?;

    Ok(())
}

Error Handling

The library provides robust error handling:

• Authentication Errors: Automatically detected and recovered via token refresh
• API Errors: Detailed error messages with HTTP status codes
• Background Failures: Silently handled to avoid disrupting your application
• Setup Errors: Returned immediately during client initialization

Token Management

The library automatically handles gcloud token expiration:

1. Detects expired tokens (401/403 responses)
2. Re-authenticates using your service account
3. Retries the failed operation with a fresh token
4. All happens transparently without manual intervention

Performance Considerations

• Non-blocking: Fire-and-forget methods return immediately
• Single Worker: One background thread prevents API rate limit issues
• Bounded Channel: 1027-item buffer prevents memory overflow
• Minimal Overhead: No rate limiting logic or complex synchronization

Modules

helpers

pubsub

Structs

LogEntry

Log entry data for Cloud Logging

MetricData

Metric data for Cloud Monitoring

ObservabilityClient

Main client

SIGTERM

SIGTERM command—used to stop the worker loop

TraceSpan

Trace span data for Cloud Trace

TraceStatus

Enums

ObservabilityError

Errors for observability operations

Traits

Handle

Each message type implements Handle to execute itself using the client.