logging or metrics or telemetry or tracing only.Expand description
Service telemetry.
Rustfoundry provides telemetry functionality for:
- logging
- distributed tracing (backed by Jaeger)
- metrics (backed by Prometheus)
- memory profiling (backed by jemalloc)
- monitoring tokio runtimes
The library strives to minimize the bootstrap code required to set up basic telemetry for a service and provide ergonomic API for telemetry-related operations.
§Initialization
In production code telemetry needs to be initialized on the service start up (usually at the
begining of the main function) with the init function for it to be collected by the
external sinks.
If syscall sandboxing is also being used (see crate::security for more details), telemetry
must be initialized prior to syscall sandboxing, since it uses syscalls during initialization
that it will not use later.
§Telemetry context
Rustfoundry’ telemetry is designed to not interfere with the production code, so you usually don’t need to carry log handles or tracing spans around. However, it is contextual, allowing different code branches to have different telemetry contexts. For example, in an HTTP service, you may want separate logs for each HTTP request. Contextual log fields are implicitly added to log records and apply only to log records produced for each particular request.
The TelemetryContext structure reflects this concept and contains information about the log
and tracing span used in the current code scope. The context doesn’t need to be explicitly
created, and if the service doesn’t need separate logs or traces for different code paths,
it is a process-wide singleton.
However, in some cases, it may be desirable to have branching of telemetry information. In such
cases, new telemetry contexts can be created using the TelemetryContext::with_forked_trace
and TelemetryContext::with_forked_log methods. These contexts need to be manually propagated
to the destination code branches using methods like TelemetryContext::scope and
TelemetryContext::apply.
§Testing
Telemetry is an important part of the functionality for any production-grade services and
Rustfoundry provides API for telemetry testing: special testing context can be created with
TelemetryContext::test method and the library provides a special with_test_telemetry macro
to enable telemetry testing in #[test] and #[tokio::test].
Modules§
- log
logging - Logging-related functionality.
- metrics
metrics - Metrics-related functionality.
- settings
- Telemetry settings.
- tokio_
runtime_ metrics tokio-runtime-metricsandtokio_unstableandrustfoundry_unstable - Toolkit for monitoring tokio runtimes using the
rustfoundry metrics api. - tracing
tracing - Distributed tracing-related functionality.
Structs§
- Memory
Profiler Linux and memory-profiling - A safe interface for jemalloc’s memory profiling functionality.
- Telemetry
Config - Telemetry configuration that is passed to
init. - Telemetry
Context - Implicit context for logging and tracing.
- Telemetry
Driver - A future that drives async telemetry functionality and that is returned
by
crate::telemetry::init. - Telemetry
Scope - A handle for the scope in which certain
TelemetryContextis active. - Telemetry
Server Route telemetry-server - A telemetry server route descriptor.
- Test
Telemetry Context testing - A test telemetry context.
- With
Telemetry Context - Wrapper for a future that provides it with
TelemetryContext. - With
Telemetry Context Local - The same as
WithTelemetryContext, but for futures that are!Send.
Functions§
- init
- Initializes service telemetry.
Type Aliases§
- Telemetry
Route Handler telemetry-server - Telemetry route handler.
- Telemetry
Route Handler Future telemetry-server - Future returned by
TelemetryServerRoute::handler.
Attribute Macros§
- with_
test_ telemetry testing - A macro that enables telemetry testing in
#[test]and#[tokio::test].