Expand description

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.


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;

async fn main() -> Result<()> {
    env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"),

// Note that `instrument` will only work correctly on functions called from
// inside `run_with_telemetry`.
  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.

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.


  • 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_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.




  • 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.
  • A monitoring-related error.



Type Aliases

  • The result type of this library.