Crate opinionated_telemetry

Common telemetry tools.

We focus on supporting the following Rust APIs:

• tracing for tracing, with support for fowarding from log.
• metrics for monitoring.

We specifically try to integrate with OpenTelemetry and to support standard "traceparent" and "tracestate" headers.

Usage

For a simple async CLI tool, you could use this library like this:

use anyhow::Result;
use opinionated_telemetry::{
  run_with_telemetry, set_parent_span_from_env, AppType,
};
use tracing::instrument;

#[tokio::main]
async fn main() -> Result<()> {
  run_with_telemetry(
    AppType::Cli,
    env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"),
    main_helper(),
  ).await
}

// Note that `instrument` will only work correctly on functions called from
// inside `run_with_telemetry`.
#[instrument(
  name = "my-app",
  fields(version = env!("CARGO_PKG_VERSION"))
)]
async fn main_helper() -> Result<()> {
 // Use TRACEPARENT and TRACESTATE from the environment to link into any
 // existing trace. Or start a new trace if none are present.
 set_parent_span_from_env();
 Ok(())
}

For more complex applications, you can use TelemetryConfig. For synchronous applications, see [run_with_telemetry_sync] and [TelemetryConfig::install_sync], which are available if the sync feature is enabled.

Features

• sync: Enable synchronous telemetry support. Use this for otherwise synchronous applications. This is not enabled by default.

Environment Variables

The following variables can be used to configure telemetry:

• RUST_LOG can be used to control our logging levels in the normal fashion.
• OPINIONATED_TELEMETRY_TRACER can be set to cloud_trace or debug to enable OpenTelelmetry tracing. If not set, we will log to stderr using tracing, honoring the filter specified by RUST_LOG.
• OPINIONATED_TELEMETRY_METRICS can be set to prometheus to enable Prometheus metrics, or debug to log metrics. Otherwise metrics will not be reported.
• OPINIONATED_TELEMETRY_PROMETHEUS_LISTEN_ADDR defaults to `“0.0.0.0:9090”.
• OPINIONATED_TELEMETRY_PROMETHEUS_PUSHGATEWAY_URL must be specified for CLI tools using Prometheus. We strongly recommend using prom-aggregation-gateway instead of Prometheus’s default pushgateway.
• OTEL_SERVICE_NAME and OTEL_SERVICE_VERSION can be used to identify your service. If not set, we will use the service_name and service_version parameters to TelemetryConfig, run_with_telemetry or [run_with_telemetry_sync]. Other OTEL_ variables supported by the opentelemetry crate may also be respected.

For CLI tools, these variables will normally be set by the calling app:

• TRACEPARENT and TRACESTATE can be passed to CLI tools to link them into an existing trace. These follow the conventions of the W3C Trace Context.

Metric naming conventions

For best results across different metrics reporting systems, we recommend following the Prometheus metric naming conventions.

Example metric names:

• myapp_requests_total: Counter with no units.
• myapp_processed_bytes_total: Counter with units.
• myapp_memory_usage_bytes: Gauge with units.

Label naming

Labels should be “low-arity”. Specifically, that means that labels should have only a small number of possible values, because each possible label value will require most backends to store a new time series.

Re-exports

• pub use metrics;
• pub use tracing;

Structs

• TelemetryConfig
  Interface used to configure and install telemetry.
• TelemetryHandle
  A handle that can be used to shut down telemetry and flush any remaining data. If you do not call TelemetryHandle::flush_and_shutdown, telemetry data may be lost.

Enums

• AppType
  What type of application should we configure telemetry for? This will affect how various kinds of telemetry are configured. For example, AppType::Server would create a Prometheus scape endpoint, but AppType::Cli would push metrics to a Prometheus push gateway once on shutdown.
• Error
  A monitoring-related error.

Traits

• SetParentFromExtractor
  Trait that allows adding an external [opentelemetry::Context] to an existing tracing::Span.

Functions

• current_span_as_env
  Export the current tracing::Span in a format suitable for passing to tokio::process::Command::envs.
• current_span_as_headers
  Export the current tracing::Span as HTTP-style headers stored in a HashMap.
• inject_current_span_into
  Export the current tracing::Span using [Injector].
• run_with_telemetry
  Start all telemetry subsystems, run the given future, and then stop all telemetry subsystems.
• set_parent_span_from
  Set the parent of the current span using the given extractor. If no trace span can be found using the extractor, start a new trace instead
• set_parent_span_from_env
  Set the parent of the current span using the environment. This will use the TRACEPARENT and TRACESTATE if present.

Type Aliases

• Result
  The result type of this library.