Skip to content

feat(rust): add getting started docs for tracing #14578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/platforms/rust/guides/tracing/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
title: tracing
120 changes: 120 additions & 0 deletions docs/platforms/rust/guides/tracing/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
title: tracing
description: "Learn about monitoring your Rust application with Sentry's tracing integration."
---

The Sentry SDK offers an integration for tokio's [tracing](https://github.com/tokio-rs/tracing) ecosystem that supports:

- Reporting `tracing` events to Sentry as events, breadcrumbs, or logs.
- Reporting `tracing` spans to Sentry.
- Reporting errors and panics with the correct trace correlation.

## Install

<OnboardingOptionButtons
options={["error-monitoring", "performance", "logs"]}
/>

To add Sentry with the `tracing` integration to your Rust project, add the necessary dependencies to your `Cargo.toml`:

```toml {filename:Cargo.toml}
[dependencies]
tracing = "0.1.41"
tracing-subscriber = "0.3.19"
sentry = { version = "{{@inject packages.version('sentry.rust') }}", features = [
"tracing",
# ___PRODUCT_OPTION_START___ logs
"logs",
# ___PRODUCT_OPTION_END___ logs
] }
tokio = { version = "1.45.0", features = ["full"] }
```

## Configure

Initialize the Sentry SDK and register the Sentry layer to start sending `tracing` events and spans to Sentry:

<Alert level="warning">

Macros like `#[tokio::main]` and `#[actix_web::main]` are not supported. The Sentry client must be initialized before the async runtime is started, as shown below.

</Alert>

```rust
use tracing_subscriber::prelude::*;

fn main() {
// Initialize Sentry
let _guard = sentry::init((
"___PUBLIC_DSN___",
sentry::ClientOptions {
release: sentry::release_name!(),
# ___PRODUCT_OPTION_START___ performance
// Capture all traces and spans. Set to a lower value in production
traces_sample_rate: 1.0,
# ___PRODUCT_OPTION_END___ performance
# ___PRODUCT_OPTION_START___ logs
enable_logs:true
# ___PRODUCT_OPTION_END___ logs
..sentry::ClientOptions::default()
},
});

// Register the Sentry tracing layer
tracing_subscriber::registry()
.with(tracing_subscriber::fmt::layer())
.with(sentry::integrations::tracing::layer())
.init();

tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()?
.block_on(async {
// Futures should to be bound to a Hub
// Learn more at https://docs.rs/sentry-core/latest/sentry_core/#parallelism-concurrency-and-async
fail().bind_hub(sentry::Hub::current()).await;
});
}

# ___PRODUCT_OPTION_START___ performance
#[tracing::instrument] // Captures a root span (transaction) around this function execution
# ___PRODUCT_OPTION_END___ performance
async fn fail() {
tracing::debug!("Doing work"); // Adds a breadrcumb
# ___PRODUCT_OPTION_START___ performance
let _span = tracing::info_span("Child span").entered(); // Captures a child span
# ___PRODUCT_OPTION_END___ performance
tracing::error!("Everything is on fire!");
}
```

By default, error level events are captured as Sentry events, while anything at or above info is added as a breadcrumb.

{/* ___PRODUCT_OPTION_START___ logs */}

To capture structured logs for `tracing` events instead, you need to set up the Sentry layer with a custom event filter that maps to logs, like so:

```rust
use sentry::integrations::tracing::EventFilter;

sentry::integrations::tracing::layer().event_filter(|md| match *md.level() {
// Capture error level events as Sentry events
tracing::Level::ERROR => EventFilter::Event,
// Ignore trace level events, as they're too verbose
tracing::Level::TRACE => EventFilter::Ignore,
// Capture everything else as a structured log
_ => EventFilter::Log,
});
```

{/* ___PRODUCT_OPTION_END___ logs */}

## Verify

<Alert>

Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.

</Alert>

To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Select Issues, and then Errors & Outages in the sidebar, where you will find the newly created issue. Clicking on the issue's title will open a page where you can see detailed information and mark it as resolved.
7 changes: 7 additions & 0 deletions src/components/platformIcon.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ import SymfonySVG from 'platformicons/svg/symfony.svg';
import TanstackSVG from 'platformicons/svg/tanstack.svg';
import TokioSVG from 'platformicons/svg/tokio.svg';
import TornadoSVG from 'platformicons/svg/tornado.svg';
import TracingSVG from 'platformicons/svg/tracing.svg';
import TrytonSVG from 'platformicons/svg/tryton.svg';
import UnitySVG from 'platformicons/svg/unity.svg';
import UnoSVG from 'platformicons/svg/uno.svg';
Expand Down Expand Up @@ -275,6 +276,7 @@ import SymfonySVGLarge from 'platformicons/svg_80x80/symfony.svg';
import TanstackSVGLarge from 'platformicons/svg_80x80/tanstack.svg';
import TokioSVGLarge from 'platformicons/svg_80x80/tokio.svg';
import TornadoSVGLarge from 'platformicons/svg_80x80/tornado.svg';
import TracingSVGLarge from 'platformicons/svg_80x80/tracing.svg';
import TrytonSVGLarge from 'platformicons/svg_80x80/tryton.svg';
import UnitySVGLarge from 'platformicons/svg_80x80/unity.svg';
import UnoSVGLarge from 'platformicons/svg_80x80/uno.svg';
Expand Down Expand Up @@ -825,6 +827,10 @@ const formatToSVG = {
sm: TornadoSVG,
lg: TornadoSVGLarge,
},
tracing: {
sm: TracingSVG,
lg: TracingSVGLarge,
},
tryton: {
sm: TrytonSVG,
lg: TrytonSVGLarge,
Expand Down Expand Up @@ -1039,6 +1045,7 @@ export const PLATFORM_TO_ICON = {
'ruby-sinatra': 'sinatra',
rust: 'rust',
'rust-actix-web': 'actix',
'rust-tracing': 'tracing',
'rust-axum': 'axum',
scala: 'scala',
stride3d: 'stride3d',
Expand Down
Loading