Skip to content

docs: update docs including OTEL and other integrations #790

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
May 8, 2025
Merged

docs: update docs including OTEL and other integrations #790

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7edc727
docs: update docs including OTEL and other integrations
lcian May 7, 2025
73bd7ed
fix
lcian May 7, 2025
c68cfdd
fix
lcian May 7, 2025
55fb7cb
fix
lcian May 7, 2025
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
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,12 @@ This workspace contains various crates that provide support for logging events a

An integration for the `log` and `env_logger` crate.

- [sentry-opentelemetry](./sentry-opentelemetry)
[![crates.io](https://img.shields.io/crates/v/sentry-opentelemetry.svg)](https://crates.io/crates/sentry-opentelemetry)
[![docs.rs](https://docs.rs/sentry-opentelemetry/badge.svg)](https://docs.rs/sentry-opentelemetry)

An integration for the `opentelemetry` crate.

- [sentry-panic](./sentry-panic)
[![crates.io](https://img.shields.io/crates/v/sentry-panic.svg)](https://crates.io/crates/sentry-panic)
[![docs.rs](https://docs.rs/sentry-panic/badge.svg)](https://docs.rs/sentry-panic)
Expand Down
94 changes: 94 additions & 0 deletions sentry-opentelemetry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<p align="center">
<a href="https://sentry.io/?utm_source=github&utm_medium=logo" target="_blank">
<img src="https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png" alt="Sentry" width="280" height="84">
</a>
</p>

# Sentry Rust SDK: sentry-opentelemetry

Support for capturing Sentry spans from OpenTelemetry spans.

Sentry spans are automatically captured from OpenTelemetry spans via `SentrySpanProcessor`.
Distributed tracing is supported via `SentryPropagator`.
Note that it's assumed that only the OTEL API is used to create and manage spans.
Mixing the OTEL and Sentry tracing API will not work, and will result in separate traces being captured.
Using the Sentry API for other purposes is supported.
For example, capturing an error inside a span will correctly send it to Sentry with the span association.

If you're using `tracing-opentelemetry`, use `sentry-tracing` instead.

# Configuration

Add the necessary dependencies to your Cargo.toml:

```toml
[dependencies]
opentelemetry = { version = "0.29.1", features = ["trace"] }
opentelemetry_sdk = { version = "0.29.0", features = ["trace"] }
sentry = { version = "0.38.0", features = ["opentelemetry"] }
```

Initialize Sentry with a `traces_sample_rate`, then register the [`SentryPropagator`] and the
[`SentrySpanProcessor`]:

```rust
use opentelemetry::{
global,
trace::{TraceContextExt, Tracer},
KeyValue,
};
use opentelemetry_sdk::trace::SdkTracerProvider;
use sentry::integrations::opentelemetry as sentry_opentelemetry;

// Initialize the Sentry SDK
let _guard = sentry::init((
"https://your-dsn@sentry.io/0",
sentry::ClientOptions {
// Enable capturing of traces; set this a to lower value in production.
// For more sophisticated behavior use a custom
// [`sentry::ClientOptions::traces_sampler`] instead.
// That's the equivalent of a tail sampling processor in OpenTelemetry.
// These options will only affect sampling of the spans that are sent to Sentry,
// not of the underlying OpenTelemetry spans.
traces_sample_rate: 1.0,
debug: true,
..sentry::ClientOptions::default()
},
));

// Register the Sentry propagator to enable distributed tracing
global::set_text_map_propagator(sentry_opentelemetry::SentryPropagator::new());

let tracer_provider = SdkTracerProvider::builder()
// Register the Sentry span processor to send OpenTelemetry spans to Sentry
.with_span_processor(sentry_opentelemetry::SentrySpanProcessor::new())
.build();

global::set_tracer_provider(tracer_provider);
```

# Usage

Use the OpenTelemetry API to create spans. They will be captured by Sentry:

```rust
let tracer = global::tracer("tracer");
// Creates a Sentry span (transaction) with the name set to "example"
tracer.in_span("example", |_| {
// Creates a Sentry child span with the name set to "child"
tracer.in_span("child", |cx| {
// OTEL span attributes are captured as data attributes on the Sentry span
cx.span().set_attribute(KeyValue::new("my", "attribute"));

// Captures a Sentry error message and associates it with the ongoing child span
sentry::capture_message("Everything is on fire!", sentry::Level::Error);
});
});
```

## Resources

License: MIT

- [Discord](https://discord.gg/ez5KZN7) server for project discussions.
- Follow [@getsentry](https://twitter.com/getsentry) on Twitter for updates
71 changes: 54 additions & 17 deletions sentry-opentelemetry/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,53 @@
//!
//! This integration allows you to capture spans from your existing OpenTelemetry setup and send
//! them to Sentry, with support for distributed tracing.
//!
//! It's assumed that only the [OpenTelemetry tracing
//! API](https://opentelemetry.io/docs/specs/otel/trace/api/) is used to start/end/modify Spans.
//! Mixing it with the Sentry tracing API (e.g. `sentry_core::start_transaction(ctx)`) will not
//! work, as the spans created with the two methods will not be nested properly.
//! Capturing events (either manually with e.g. `sentry::capture_event`, or automatically with e.g. the
//! `sentry-panic` integration) will send them to Sentry with the correct trace and span
//! association.
//!
//! Capturing events with `sentry::capture_event` will send them to Sentry with the correct
//! trace and span association.
//!
//! # Configuration
//!
//! Initialize Sentry, then register the [`SentryPropagator`] and the [`SentrySpanProcessor`]:
//! Add the necessary dependencies to your Cargo.toml:
//!
//! ```toml
//! [dependencies]
//! opentelemetry = { version = "0.29.1", features = ["trace"] }
//! opentelemetry_sdk = { version = "0.29.0", features = ["trace"] }
//! sentry = { version = "0.38.0", features = ["opentelemetry"] }
//! ```
//!
//! Initialize Sentry with a `traces_sample_rate`, then register the [`SentryPropagator`] and the
//! [`SentrySpanProcessor`]:
//!
//! ```
//! use opentelemetry::{global};
//! use opentelemetry_sdk::{
//! propagation::TraceContextPropagator, trace::SdkTracerProvider,
//! use opentelemetry::{
//! global,
//! trace::{TraceContextExt, Tracer},
//! KeyValue,
//! };
//! use opentelemetry_sdk::trace::SdkTracerProvider;
//! use sentry::integrations::opentelemetry as sentry_opentelemetry;
//!
//! // Initialize the Sentry SDK
//! let _guard = sentry::init(sentry::ClientOptions {
//! // Enable capturing of traces; set this a to lower value in production.
//! // For more sophisticated behavior use a custom
//! // [`sentry::ClientOptions::traces_sampler`] instead.
//! // That's the equivalent of a tail sampling processor in OpenTelemetry.
//! // These options will only affect sampling of the spans that are sent to Sentry,
//! // not of the underlying OpenTelemetry spans.
//! traces_sample_rate: 1.0,
//! ..sentry::ClientOptions::default()
//! });
//! let _guard = sentry::init((
//! "https://your-dsn@sentry.io/0",
//! sentry::ClientOptions {
//! // Enable capturing of traces; set this a to lower value in production.
//! // For more sophisticated behavior use a custom
//! // [`sentry::ClientOptions::traces_sampler`] instead.
//! // That's the equivalent of a tail sampling processor in OpenTelemetry.
//! // These options will only affect sampling of the spans that are sent to Sentry,
//! // not of the underlying OpenTelemetry spans.
//! traces_sample_rate: 1.0,
//! debug: true,
//! ..sentry::ClientOptions::default()
//! },
//! ));
//!
//! // Register the Sentry propagator to enable distributed tracing
//! global::set_text_map_propagator(sentry_opentelemetry::SentryPropagator::new());
Expand All @@ -42,6 +60,25 @@
//!
//! global::set_tracer_provider(tracer_provider);
//! ```
//!
//! # Usage
//!
//! Use the OpenTelemetry API to create spans. They will be captured by Sentry:
//!
//! ```no_run
//! let tracer = global::tracer("tracer");
//! // Creates a Sentry span (transaction) with the name set to "example"
//! tracer.in_span("example", |_| {
//! // Creates a Sentry child span with the name set to "child"
//! tracer.in_span("child", |cx| {
//! // OTEL span attributes are captured as data attributes on the Sentry span
//! cx.span().set_attribute(KeyValue::new("my", "attribute"));
//!
//! // Captures a Sentry error message and associates it with the ongoing child span
//! sentry::capture_message("Everything is on fire!", sentry::Level::Error);
//! });
//! });
//! ```

mod converters;
mod processor;
Expand Down
13 changes: 11 additions & 2 deletions sentry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,14 +80,20 @@ extra setup to function properly.
| `reqwest` | ✅ | | | |
| `native-tls` | ✅ | | | `reqwest` must be enabled. |
| `rustls` | | | | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
| `curl` | | | | |
| `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
| `ureq` | | | | `ureq` transport support using `rustls` by default |
| `ureq-native-tls` | | | | |
| `curl` | | | | |
| `actix` | | 🔌 | | Requires extra setup; See [`sentry-actix`]'s documentation. |
| `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
| `tracing` | | 🔌 | | Requires extra setup; See [`sentry-tracing`]'s documentation. |
| `opentelemetry` | | 🔌 | | Requires extra setup; See [`sentry-opentelemetry`]'s documentation. |

[`sentry-log`]: https://crates.io/crates/sentry-log
[`sentry-slog`]: https://crates.io/crates/sentry-slog
[`sentry-actix`]: https://crates.io/crates/sentry-actix
[`sentry-tower`]: https://crates.io/crates/sentry-tower
[`sentry-tracing`]: https://crates.io/crates/sentry-tracing
[`sentry-opentelemetry`]: https://crates.io/crates/sentry-opentelemetry

### Default features
- `backtrace`: Enables backtrace support.
Expand Down Expand Up @@ -116,7 +122,10 @@ extra setup to function properly.
- `ureq-native-tls`: Enables the `ureq` transport using `native-tls`.

### Integrations
- `actix`: Enables support for the `actix-web` crate.
- `tower`: Enables support for the `tower` crate and those using it.
- `tracing`: Enables support for the `tracing` crate and those using it.
- `opentelemetry`: Enables support for the `opentelemetry` and `opentelemetry-sdk` crates.

## Resources

Expand Down
14 changes: 12 additions & 2 deletions sentry/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@
//! [`Transport`]: trait.Transport.html
//! [`sentry-core`]: https://crates.io/crates/sentry-core
//!
//!
//! # Features
//!
//! Additional functionality and integrations are enabled via feature flags. Some features require
Expand All @@ -72,14 +73,20 @@
//! | `reqwest` | ✅ | | | |
//! | `native-tls` | ✅ | | | `reqwest` must be enabled. |
//! | `rustls` | | | | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
//! | `curl` | | | | |
//! | `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
//! | `ureq` | | | | `ureq` transport support using `rustls` by default |
//! | `ureq-native-tls` | | | | |
//! | `curl` | | | | |
//! | `actix` | | 🔌 | | Requires extra setup; See [`sentry-actix`]'s documentation. |
//! | `tower` | | 🔌 | | Requires extra setup; See [`sentry-tower`]'s documentation. |
//! | `tracing` | | 🔌 | | Requires extra setup; See [`sentry-tracing`]'s documentation. |
//! | `opentelemetry` | | 🔌 | | Requires extra setup; See [`sentry-opentelemetry`]'s documentation. |
//!
//! [`sentry-log`]: https://crates.io/crates/sentry-log
//! [`sentry-slog`]: https://crates.io/crates/sentry-slog
//! [`sentry-actix`]: https://crates.io/crates/sentry-actix
//! [`sentry-tower`]: https://crates.io/crates/sentry-tower
//! [`sentry-tracing`]: https://crates.io/crates/sentry-tracing
//! [`sentry-opentelemetry`]: https://crates.io/crates/sentry-opentelemetry
//!
//! ## Default features
//! - `backtrace`: Enables backtrace support.
Expand Down Expand Up @@ -108,7 +115,10 @@
//! - `ureq-native-tls`: Enables the `ureq` transport using `native-tls`.
//!
//! ## Integrations
//! - `actix`: Enables support for the `actix-web` crate.
//! - `tower`: Enables support for the `tower` crate and those using it.
//! - `tracing`: Enables support for the `tracing` crate and those using it.
//! - `opentelemetry`: Enables support for the `opentelemetry` and `opentelemetry-sdk` crates.

#![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
#![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
Expand Down