Crate opinionated_telemetry
source ·Expand description
Common telemetry tools.
We focus on supporting the following Rust APIs:
tracing
for tracing, with support for fowarding fromlog
.metrics
for monitoring.
We specifically try to integrate with OpenTelemetry and to support standard
"traceparent"
and "tracestate"
headers.
Environment Variables
The following variables can be used to configure
RUST_LOG
can be used to control our logging levels in the normal fashion.OPINIONATED_TELEMETRY_TRACER
can be set tocloud_trace
ordebug
to enable OpenTelelmetry tracing. If not set, we will log to stderr usingtracing
, honoring the filter specified byRUST_LOG
.OPINIONATED_TELEMETRY_METRICS
can be set toprometheus
to enable Prometheus metrics, ordebug
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 usingprom-aggregation-gateway
instead of Prometheus’s defaultpushgateway
.OTEL_SERVICE_NAME
andOTEL_SERVICE_VERSION
can be used to identify your service. If not set, we will use theservice_name
andservice_version
parameters to [start_telemetry
] orrun_with_telemetry
. OtherOTEL_
variables supported by theopentelemetry
crate may also be respected.
For CLI tools, these variables will normally be set by the calling app:
TRACEPARENT
andTRACESTATE
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
Macros
- Implement
Structs
- Interface used to configure and install telemetry.
- 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
- A monitoring-related error.
Traits
- Trait that allows adding an external [
opentelemetry::Context
] to an existingtracing::Span
.
Functions
- Export the current
tracing::Span
in a format suitable for passing totokio::process::Command::envs
. - Export the current
tracing::Span
as HTTP-style headers stored in aHashMap
. - Export the current
tracing::Span
using [Injector
]. - Start all telemetry subsystems, run the given future, and then stop all telemetry subsystems.
- 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 the parent of the current span using the environment. This will use the
TRACEPARENT
andTRACESTATE
if present.
Type Aliases
- The result type of this library.