Rust - Monocle Docs

The Rust SDK sends tracing spans, logs, OpenTelemetry metrics, and captured exceptions to Monocle. It uses stable Rust, without nightly features.

Installation

Create a DSN
Open Services, add or select your service, and choose Rust under SDK connection. Copy its DSN.
Install the SDK
Terminal
```
cargo add monocle-sh-sdk@0.1
cargo add tracing tracing-subscriber
```
The package is named monocle-sh-sdk on crates.io and exposes monocle in Rust code.
Set the environment
Set these variables through your process manager. The SDK does not load .env files itself.
Runtime environment
```
MONOCLE_DSN=https://mk_live_xxxxxxxx@ingest.monocle.sh/00000000-0000-4000-8000-000000000001
MONOCLE_ENVIRONMENT=development
MONOCLE_VERSION=<deployed commit SHA>
```
Use the same DSN across environments. Set MONOCLE_ENVIRONMENT to staging or production where you deploy, and MONOCLE_VERSION to the deployed commit.

Initialize the SDK

src/main.rs

use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

fn main() -> Result<(), Box<dyn std::error::Error>> {
	let monocle = monocle::init(monocle::Options {
		dsn: std::env::var("MONOCLE_DSN")?,
		service_name: "api".into(),
		service_version: std::env::var("MONOCLE_VERSION").ok(),
		environment: std::env::var("MONOCLE_ENVIRONMENT")?,
	})?;
	tracing_subscriber::registry().with(monocle.layer()).init();
	monocle::install_panic_hook();

	{
		let span = tracing::info_span!("monocle setup verification");
		let _entered = span.enter();
		tracing::info!("Rust service connected");
	}

	monocle.shutdown();
	Ok(())
}

If you already have a tracing subscriber, add monocle.layer() to it instead of creating another one. Keep the client alive until your server and workers stop, then call shutdown() to flush pending traces, logs, and metrics.

Run the application. In Monocle, open Traces in the development environment and look for monocle setup verification and its Rust service connected log.

Trace Axum requests

Enable the optional Axum integration:

Terminal

cargo add monocle-sh-sdk@0.1 --features axum

Add the layer after SDK initialization:

Router setup

let app = axum::Router::new()
	.route("/orders", axum::routing::get(orders))
	.layer(monocle::axum::layer());

The layer traces incoming requests, continues traceparent headers, and marks 5xx responses as failed. Health checks and OPTIONS requests are excluded. Database and outbound HTTP calls need their own instrumentation.

Report exceptions

Capture handled errors where you process them:

Error handler

if let Err(error) = save_order() {
	monocle::capture_error(&error);
}

Monocle records the current stack and the error's Error::source() causes. It does not recover the stack where the error originated or reconstruct suspended async callers. Ordinary tracing::error! events remain logs, not issues.

The panic hook reports panics and calls the previous hook without changing unwind or abort behavior. Delivery is best effort. Segmentation faults and forced process termination are not captured.

Show files, lines, and source code

For Linux x86_64 ELF/DWARF builds, upload native symbols and sources from CI. The debug artifact resolves captured addresses, including inline calls. A separate source bundle provides code excerpts. Without matching artifacts, Monocle keeps the raw frames and causes.

Installation

Trace Axum requests

Report exceptions

Show files, lines, and source code

Search documentation