|
2 | 2 | //! |
3 | 3 | //! This integration allows you to capture spans from your existing OpenTelemetry setup and send |
4 | 4 | //! them to Sentry, with support for distributed tracing. |
| 5 | +//! |
5 | 6 | //! It's assumed that only the [OpenTelemetry tracing |
6 | 7 | //! API](https://opentelemetry.io/docs/specs/otel/trace/api/) is used to start/end/modify Spans. |
7 | 8 | //! Mixing it with the Sentry tracing API (e.g. `sentry_core::start_transaction(ctx)`) will not |
8 | 9 | //! work, as the spans created with the two methods will not be nested properly. |
9 | | -//! Capturing events (either manually with e.g. `sentry::capture_event`, or automatically with e.g. the |
10 | | -//! `sentry-panic` integration) will send them to Sentry with the correct trace and span |
11 | | -//! association. |
| 10 | +//! |
| 11 | +//! Capturing events with `sentry::capture_event` will send them to Sentry with the correct |
| 12 | +//! trace and span association. |
12 | 13 | //! |
13 | 14 | //! # Configuration |
14 | 15 | //! |
15 | | -//! Initialize Sentry, then register the [`SentryPropagator`] and the [`SentrySpanProcessor`]: |
| 16 | +//! Add the necessary dependencies to your Cargo.toml: |
| 17 | +//! |
| 18 | +//! ```toml |
| 19 | +//! [dependencies] |
| 20 | +//! opentelemetry = { version = "0.29.1", features = ["trace"] } |
| 21 | +//! opentelemetry_sdk = { version = "0.29.0", features = ["trace"] } |
| 22 | +//! sentry = { version = "0.38.0", features = ["opentelemetry"] } |
| 23 | +//! ``` |
| 24 | +//! |
| 25 | +//! Initialize Sentry with a `traces_sample_rate`, then register the [`SentryPropagator`] and the |
| 26 | +//! [`SentrySpanProcessor`]: |
16 | 27 | //! |
17 | 28 | //! ``` |
18 | | -//! use opentelemetry::{global}; |
19 | | -//! use opentelemetry_sdk::{ |
20 | | -//! propagation::TraceContextPropagator, trace::SdkTracerProvider, |
| 29 | +//! use opentelemetry::{ |
| 30 | +//! global, |
| 31 | +//! trace::{TraceContextExt, Tracer}, |
| 32 | +//! KeyValue, |
21 | 33 | //! }; |
| 34 | +//! use opentelemetry_sdk::trace::SdkTracerProvider; |
| 35 | +//! use sentry::integrations::opentelemetry as sentry_opentelemetry; |
22 | 36 | //! |
23 | 37 | //! // Initialize the Sentry SDK |
24 | | -//! let _guard = sentry::init(sentry::ClientOptions { |
25 | | -//! // Enable capturing of traces; set this a to lower value in production. |
26 | | -//! // For more sophisticated behavior use a custom |
27 | | -//! // [`sentry::ClientOptions::traces_sampler`] instead. |
28 | | -//! // That's the equivalent of a tail sampling processor in OpenTelemetry. |
29 | | -//! // These options will only affect sampling of the spans that are sent to Sentry, |
30 | | -//! // not of the underlying OpenTelemetry spans. |
31 | | -//! traces_sample_rate: 1.0, |
32 | | -//! ..sentry::ClientOptions::default() |
33 | | -//! }); |
| 38 | +//! let _guard = sentry::init(( |
| 39 | +//! "https://[email protected]/0", |
| 40 | +//! sentry::ClientOptions { |
| 41 | +//! // Enable capturing of traces; set this a to lower value in production. |
| 42 | +//! // For more sophisticated behavior use a custom |
| 43 | +//! // [`sentry::ClientOptions::traces_sampler`] instead. |
| 44 | +//! // That's the equivalent of a tail sampling processor in OpenTelemetry. |
| 45 | +//! // These options will only affect sampling of the spans that are sent to Sentry, |
| 46 | +//! // not of the underlying OpenTelemetry spans. |
| 47 | +//! traces_sample_rate: 1.0, |
| 48 | +//! debug: true, |
| 49 | +//! ..sentry::ClientOptions::default() |
| 50 | +//! }, |
| 51 | +//! )); |
34 | 52 | //! |
35 | 53 | //! // Register the Sentry propagator to enable distributed tracing |
36 | 54 | //! global::set_text_map_propagator(sentry_opentelemetry::SentryPropagator::new()); |
|
42 | 60 | //! |
43 | 61 | //! global::set_tracer_provider(tracer_provider); |
44 | 62 | //! ``` |
| 63 | +//! |
| 64 | +//! # Usage |
| 65 | +//! |
| 66 | +//! Use the OpenTelemetry API to create spans. They will be captured by Sentry: |
| 67 | +//! |
| 68 | +//! ```no_run |
| 69 | +//! let tracer = global::tracer("tracer"); |
| 70 | +//! // Creates a Sentry span (transaction) with the name set to "example" |
| 71 | +//! tracer.in_span("example", |_| { |
| 72 | +//! // Creates a Sentry child span with the name set to "child" |
| 73 | +//! tracer.in_span("child", |cx| { |
| 74 | +//! // OTEL span attributes are captured as data attributes on the Sentry span |
| 75 | +//! cx.span().set_attribute(KeyValue::new("my", "attribute")); |
| 76 | +//! |
| 77 | +//! // Captures a Sentry error message and associates it with the ongoing child span |
| 78 | +//! sentry::capture_message("Everything is on fire!", sentry::Level::Error); |
| 79 | +//! }); |
| 80 | +//! }); |
| 81 | +//! ``` |
45 | 82 |
|
46 | 83 | mod converters; |
47 | 84 | mod processor; |
|
0 commit comments