`tracing-stackdriver`

A `tracing` Subscriber for communicating Stackdriver-formatted logs

tracing is a scoped, structured logging and diagnostic system based on emitting Events in the context of potentially-nested Spans across asynchronous await points. These properties make tracing ideal for use with Google Cloud Operations Suite structured logging (formerly Stackdriver).

This crate provides a Layer for use with a tracing Registry that formats tracing Spans and Events into properly-structured JSON for consumption by Google Operations Logging through the jsonPayload field. This includes the following behaviors and enhancements:

rfc3339-formatted timestamps for all Events
severity (in LogSeverity format) derived from tracing Level
target derived from the Event target Metadata
Span name and custom fields included under a span key
automatic nesting of http_request.-prefixed event fields
automatic camelCase-ing of all field keys (e.g. http_request -> httpRequest)
valuable support, including an HttpRequest helper struct

Examples

Basic setup:

```rust use tracingsubscriber::{layer::SubscriberExt, Registry}; use tracingstackdriver::Stackdriver;

fn main() { let stackdriver = Stackdriver::layer(); // writes to std::io::Stdout let subscriber = Registry::default().with(stackdriver);

tracing::subscriber::set_global_default(subscriber).expect("Could not set up global logger");

} ```

Custom write location:

```rust use tracingsubscriber::{layer::SubscriberExt, Registry}; use tracingstackdriver::Stackdriver;

fn main() { let makewriter = || std::io::Stderr; let stackdriver = Stackdriver::layer().withwriter(make_writer); // writes to std::io::Stderr let subscriber = Registry::default().with(stackdriver);

tracing::subscriber::set_global_default(subscriber).expect("Could not set up global logger");

} ```

With `httpRequest` fields:

See all available fields here.

```rust // requires working global setup (see above examples)

use hyper::Request;

fn handle_request(request: Request) { let method = &request.method(); let uri = &request.uri();

tracing::info!( httprequest.requestmethod = %method, httprequest.requesturl = %uri, "Request received" );

// jsonPayload formatted as: // { // "time": "some-timestamp" // "severity": "INFO", // "httpRequest": { // "requestMethod": "GET", // "requestUrl": "/some/url/from/request" // }, // "message": "Request received" // } } ```

With more specific `LogSeverity` levels:

Google supports a slightly different set of severity levels than tracing. tracing levels are automatically mapped to LogSeverity levels, but you can customize the level beyond the intersection of tracing levels and LogSeverity levels by using the provided LogSeverity level with a severity key.

```rust use tracing_stackdriver::LogSeverity;

fn main() { // requires working global setup (see above examples)

tracing::info!(severity = %LogSeverity::Notice, "Application starting");

// jsonPayload formatted as: // { // "time": "some-timestamp" // "severity": "NOTICE", // "message": "Request received" // } } ```

With `valuable` support:

tracing_stackdriver supports deeply-nested structured logging through tracing's unstable valuable support. In addition, httpRequest fields can be generated with the HttpRequest helper struct exported from this library for better compile-time checking of fields.

To enable valuable support, use the valuable feature flag and compile your project with RUSTFLAGS="--cfg tracing_unstable".

```rust

// requires working global setup (see above examples)

use hyper::Request; use tracing_stackdriver::HttpRequest; use valuable::Valuable;

[derive(Valuable)]

struct StructuredLog { service: &'static str, handler: &'static str }

fn handlerequest(request: Request) { let httprequest = HttpRequest { requestmethod: request.method().into(), requesturl: request.uri().into(), ..Default::default() };

let structuredlog = StructuredLog { service: "requesthandlers", handler: "handle_request", };

tracing::info!( httprequest = httprequest.asvalue(), structuredlog = structuredlog.asvalue(), "Request received" );

Roadmap:

distributing tracing data in Cloud Trace format
support the logging API in addition to the logging agent/std{out,err}

tracing-stackdriver

A tracing Subscriber for communicating Stackdriver-formatted logs