Rust Telemetry

This lib contains a set of helpers to work with OpenTelemetry logs, traces and metrics.

Setup

For setup all that's needed it to run the function rust_telemetry::init_otel. The function returns a guard that takes care of properly shutting down the providers.

If no configuration is present the exporting of logs traces and metrics is disabled and the stdout logging is enabled.

The functions on the crate exporting opentelemetry traces should be annotated with tracing::instrument to generate a new span for that function. Documentation on this macro can be found on the here

The opentelemetry information is exported using gRPC to and opentelemetry collector. By default the expected endpoint is http://localhots:4317

The default level of logging and traces is info for the crate and all it's dependencies. This level can be changed through the configuration and, the result filter expression is general_level,main_crate=level where general_level and level come from the configuration and main_crate is an argument for the init_otel function

#[tokio::main]
async fn main() {
  let _guard = init_otel!(&config).unwrap();

}

Configuration

An example config for OtelConfig can be found in config.sample.yaml. For the exact schema, see ./config-schema.yaml. Use schemars feature of this crate to be able to generate schemas for your service configs.

Propagate the context

A context can be propagated to allow linking the traces from two different services. This is done by injecting the context information into the request and retrieving it in another service.

reqwest

For injecting the current context using the reqwest client we can wrap a client in a reqwest-middleware and use the OtelMiddleware middleware present in this crate. This feature requires the feature flag reqwest-middleware

use rust_telemetry::reqwest_middleware::OtelMiddleware;

let reqwest_client = reqwest::Client::builder().build().unwrap();
let client = reqwest_middleware::ClientBuilder::new(reqwest_client)
  // Insert the tracing middleware
  .with(OtelMiddleware::default())
  .build();
client.get("http://localhost").send().await;

axum

For retrieving a context using axum we can use the OtelAxumLayer from axum_tracing_opentelemetry

[!WARNING] This only seems to be working using the feature flag tracing_level_info. See the issue

This layer should run as soon as possible

use axum_tracing_opentelemetry::middleware::OtelAxumLayer;

Router::new().layer(OtelAxumLayer::default())

Metrics

For adding metrics all that is needed is to make a trace with specific prefix. The documentation on how it works is here

Another option is to use directly the OpenTelemetry SDK for that. Examples to it can be found here

For convenience the function add_metrics_layer was added. This function adds an axum layer that makes metrics. To use this function the feature flag axum is needed. The layer is only added if the metrics exporting configuration is enabled.

Here is an example of usage. Note that in this example the layer won't be added because the default OtelConfig is not set to export metrics.

#[tokio::main]
async fn main() {
  let config = Some(rust_telemetry::config::OtelConfig::default());
  let app = Router::new().route("/", get("Test"));
  let app = rust_telemetry::axum::add_metrics_layer(app, config);

  let listener = tokio::net::TcpListener::bind("127.0.0.1:8000").await.unwrap();
  let server = axum::serve(listener, app);
  if let Err(err) = server.await {
      eprintln!("server error: {}", err);
  }
}

Lints

cargo clippy --workspace --all-targets

and this in your IDE:

cargo clippy --workspace --all-targets --message-format=json

Pre-commit usage

1. If not installed, install with your package manager, or pip install --user pre-commit
2. Run pre-commit autoupdate to update the pre-commit config to use the newest template
3. Run pre-commit install to install the pre-commit hooks to your local environment

Famedly

This project is part of the source code of Famedly.

We think that software for healthcare should be open source, so we publish most parts of our source code at github.com/famedly.

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

For licensing information of this project, have a look at the LICENSE file within the repository.

If you compile the open source software that we make available to develop your own mobile, desktop or embeddable application, and cause that application to connect to our servers for any purposes, you have to agree to our Terms of Service. In short, if you choose to connect to our servers, certain restrictions apply as follows:

• You agree not to change the way the open source software connects and interacts with our servers
• You agree not to weaken any of the security features of the open source software
• You agree not to use the open source software to gather data
• You agree not to use our servers to store data for purposes other than the intended and original functionality of the Software
• You acknowledge that you are solely responsible for any and all updates to your software

No license is granted to the Famedly trademark and its associated logos, all of which will continue to be owned exclusively by Famedly GmbH. Any use of the Famedly trademark and/or its associated logos is expressly prohibited without the express prior written consent of Famedly GmbH.

For more information take a look at Famedly.com or contact us by info@famedly.com