sentry_core/clientoptions.rs
1use std::borrow::Cow;
2use std::fmt;
3use std::sync::Arc;
4use std::time::Duration;
5
6use crate::constants::USER_AGENT;
7use crate::performance::TracesSampler;
8use crate::protocol::{Breadcrumb, Event};
9use crate::types::Dsn;
10use crate::{Integration, IntoDsn, TransportFactory};
11
12/// Type alias for before event/breadcrumb handlers.
13pub type BeforeCallback<T> = Arc<dyn Fn(T) -> Option<T> + Send + Sync>;
14
15/// The Session Mode of the SDK.
16///
17/// Depending on the use-case, the SDK can be set to two different session modes:
18///
19/// * **Application Mode Sessions**:
20/// This mode should be used for user-attended programs, which typically have
21/// a single long running session that span the applications' lifetime.
22///
23/// * **Request Mode Sessions**:
24/// This mode is intended for servers that use one session per incoming
25/// request, and thus have a lot of very short lived sessions.
26///
27/// Setting the SDK to *request-mode* sessions means that session durations will
28/// not be tracked, and sessions will be pre-aggregated before being sent upstream.
29/// This applies both to automatic and manually triggered sessions.
30///
31/// **NOTE**: Support for *request-mode* sessions was added in Sentry `21.2`.
32///
33/// See the [Documentation on Session Modes](https://develop.sentry.dev/sdk/sessions/#sdk-considerations)
34/// for more information.
35///
36/// **NOTE**: The `release-health` feature (enabled by default) needs to be enabled for this option to have
37/// any effect.
38#[derive(Copy, Clone, Debug, PartialEq, Eq)]
39pub enum SessionMode {
40 /// Long running application session.
41 Application,
42 /// Lots of short per-request sessions.
43 Request,
44}
45
46/// The maximum size of an HTTP request body that the SDK captures.
47///
48/// Only request bodies that parse as JSON or form data are currently captured.
49/// See the [Documentation on attaching request body](https://develop.sentry.dev/sdk/expected-features/#attaching-request-body-in-server-sdks)
50/// and the [Documentation on handling sensitive data](https://develop.sentry.dev/sdk/expected-features/data-handling/#sensitive-data)
51/// for more information.
52#[derive(Clone, Copy, PartialEq)]
53pub enum MaxRequestBodySize {
54 /// Don't capture request body
55 None,
56 /// Capture up to 1000 bytes
57 Small,
58 /// Capture up to 10000 bytes
59 Medium,
60 /// Capture entire body
61 Always,
62 /// Capture up to a specific size
63 Explicit(usize),
64}
65
66impl MaxRequestBodySize {
67 /// Check if the content length is within the size limit.
68 pub fn is_within_size_limit(&self, content_length: usize) -> bool {
69 match self {
70 MaxRequestBodySize::None => false,
71 MaxRequestBodySize::Small => content_length <= 1_000,
72 MaxRequestBodySize::Medium => content_length <= 10_000,
73 MaxRequestBodySize::Always => true,
74 MaxRequestBodySize::Explicit(size) => content_length <= *size,
75 }
76 }
77}
78
79/// Configuration settings for the client.
80///
81/// These options are explained in more detail in the general
82/// [sentry documentation](https://docs.sentry.io/error-reporting/configuration/?platform=rust).
83///
84/// # Examples
85///
86/// ```
87/// let _options = sentry::ClientOptions {
88/// debug: true,
89/// ..Default::default()
90/// };
91/// ```
92#[derive(Clone)]
93pub struct ClientOptions {
94 // Common options
95 /// The DSN to use. If not set the client is effectively disabled.
96 pub dsn: Option<Dsn>,
97 /// Enables debug mode.
98 ///
99 /// In debug mode debug information is printed to stderr to help you understand what
100 /// sentry is doing. When the `log` feature is enabled, Sentry will instead
101 /// log to the `sentry` logger independently of this flag with the `Debug` level.
102 pub debug: bool,
103 /// The release to be sent with events.
104 pub release: Option<Cow<'static, str>>,
105 /// The environment to be sent with events.
106 ///
107 /// Defaults to either `"development"` or `"production"` depending on the
108 /// `debug_assertions` cfg-attribute.
109 pub environment: Option<Cow<'static, str>>,
110 /// The sample rate for event submission. (0.0 - 1.0, defaults to 1.0)
111 pub sample_rate: f32,
112 /// The sample rate for tracing transactions. (0.0 - 1.0, defaults to 0.0)
113 pub traces_sample_rate: f32,
114 /// If given, called with a SamplingContext for each transaction to determine the sampling rate.
115 ///
116 /// Return a sample rate between 0.0 and 1.0 for the transaction in question.
117 /// Takes priority over the `sample_rate`.
118 pub traces_sampler: Option<Arc<TracesSampler>>,
119 /// Maximum number of breadcrumbs. (defaults to 100)
120 pub max_breadcrumbs: usize,
121 /// Attaches stacktraces to messages.
122 pub attach_stacktrace: bool,
123 /// If turned on some default PII informat is attached.
124 pub send_default_pii: bool,
125 /// The server name to be reported.
126 pub server_name: Option<Cow<'static, str>>,
127 /// Module prefixes that are always considered "in_app".
128 pub in_app_include: Vec<&'static str>,
129 /// Module prefixes that are never "in_app".
130 pub in_app_exclude: Vec<&'static str>,
131 // Integration options
132 /// A list of integrations to enable.
133 ///
134 /// See [`sentry::integrations`](integrations/index.html#installing-integrations) for
135 /// how to use this to enable extra integrations.
136 pub integrations: Vec<Arc<dyn Integration>>,
137 /// Whether to add default integrations.
138 ///
139 /// See [`sentry::integrations`](integrations/index.html#default-integrations) for
140 /// details how this works and interacts with manually installed integrations.
141 pub default_integrations: bool,
142 // Hooks
143 /// Callback that is executed before event sending.
144 pub before_send: Option<BeforeCallback<Event<'static>>>,
145 /// Callback that is executed for each Breadcrumb being added.
146 pub before_breadcrumb: Option<BeforeCallback<Breadcrumb>>,
147 // Transport options
148 /// The transport to use.
149 ///
150 /// This is typically either a boxed function taking the client options by
151 /// reference and returning a `Transport`, a boxed `Arc<Transport>` or
152 /// alternatively the `DefaultTransportFactory`.
153 pub transport: Option<Arc<dyn TransportFactory>>,
154 /// An optional HTTP proxy to use.
155 ///
156 /// This will default to the `http_proxy` environment variable.
157 pub http_proxy: Option<Cow<'static, str>>,
158 /// An optional HTTPS proxy to use.
159 ///
160 /// This will default to the `HTTPS_PROXY` environment variable
161 /// or `http_proxy` if that one exists.
162 pub https_proxy: Option<Cow<'static, str>>,
163 /// The timeout on client drop for draining events on shutdown.
164 pub shutdown_timeout: Duration,
165 // Other options not documented in Unified API
166 /// Disable SSL verification.
167 ///
168 /// # Warning
169 ///
170 /// This introduces significant vulnerabilities, and should only be used as a last resort.
171 pub accept_invalid_certs: bool,
172 /// Enable Release Health Session tracking.
173 ///
174 /// When automatic session tracking is enabled, a new "user-mode" session
175 /// is started at the time of `sentry::init`, and will persist for the
176 /// application lifetime.
177 ///
178 /// **NOTE**: The `release-health` feature (enabled by default) needs to be enabled for this option to have
179 /// any effect.
180 pub auto_session_tracking: bool,
181 /// Determine how Sessions are being tracked.
182 ///
183 /// **NOTE**: The `release-health` feature (enabled by default) needs to be enabled for this option to have
184 /// any effect.
185 pub session_mode: SessionMode,
186 /// Border frames which indicate a border from a backtrace to
187 /// useless internals. Some are automatically included.
188 pub extra_border_frames: Vec<&'static str>,
189 /// Automatically trim backtraces of junk before sending. (defaults to true)
190 pub trim_backtraces: bool,
191 /// The user agent that should be reported.
192 pub user_agent: Cow<'static, str>,
193 /// Controls how much of request bodies are captured
194 pub max_request_body_size: MaxRequestBodySize,
195}
196
197impl ClientOptions {
198 /// Creates new Options.
199 pub fn new() -> Self {
200 Self::default()
201 }
202
203 /// Adds a configured integration to the options.
204 ///
205 /// # Examples
206 ///
207 /// ```
208 /// struct MyIntegration;
209 ///
210 /// impl sentry::Integration for MyIntegration {}
211 ///
212 /// let options = sentry::ClientOptions::new().add_integration(MyIntegration);
213 /// assert_eq!(options.integrations.len(), 1);
214 /// ```
215 #[must_use]
216 pub fn add_integration<I: Integration>(mut self, integration: I) -> Self {
217 self.integrations.push(Arc::new(integration));
218 self
219 }
220}
221
222impl fmt::Debug for ClientOptions {
223 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
224 #[derive(Debug)]
225 struct BeforeSend;
226 let before_send = self.before_send.as_ref().map(|_| BeforeSend);
227 #[derive(Debug)]
228 struct BeforeBreadcrumb;
229 let before_breadcrumb = self.before_breadcrumb.as_ref().map(|_| BeforeBreadcrumb);
230 #[derive(Debug)]
231 struct TransportFactory;
232
233 let integrations: Vec<_> = self.integrations.iter().map(|i| i.name()).collect();
234
235 f.debug_struct("ClientOptions")
236 .field("dsn", &self.dsn)
237 .field("debug", &self.debug)
238 .field("release", &self.release)
239 .field("environment", &self.environment)
240 .field("sample_rate", &self.sample_rate)
241 .field("traces_sample_rate", &self.traces_sample_rate)
242 .field(
243 "traces_sampler",
244 &self
245 .traces_sampler
246 .as_ref()
247 .map(|arc| std::ptr::addr_of!(**arc)),
248 )
249 .field("max_breadcrumbs", &self.max_breadcrumbs)
250 .field("attach_stacktrace", &self.attach_stacktrace)
251 .field("send_default_pii", &self.send_default_pii)
252 .field("server_name", &self.server_name)
253 .field("in_app_include", &self.in_app_include)
254 .field("in_app_exclude", &self.in_app_exclude)
255 .field("integrations", &integrations)
256 .field("default_integrations", &self.default_integrations)
257 .field("before_send", &before_send)
258 .field("before_breadcrumb", &before_breadcrumb)
259 .field("transport", &TransportFactory)
260 .field("http_proxy", &self.http_proxy)
261 .field("https_proxy", &self.https_proxy)
262 .field("shutdown_timeout", &self.shutdown_timeout)
263 .field("accept_invalid_certs", &self.accept_invalid_certs)
264 .field("auto_session_tracking", &self.auto_session_tracking)
265 .field("session_mode", &self.session_mode)
266 .field("extra_border_frames", &self.extra_border_frames)
267 .field("trim_backtraces", &self.trim_backtraces)
268 .field("user_agent", &self.user_agent)
269 .finish()
270 }
271}
272
273impl Default for ClientOptions {
274 fn default() -> ClientOptions {
275 ClientOptions {
276 dsn: None,
277 debug: false,
278 release: None,
279 environment: None,
280 sample_rate: 1.0,
281 traces_sample_rate: 0.0,
282 traces_sampler: None,
283 max_breadcrumbs: 100,
284 attach_stacktrace: false,
285 send_default_pii: false,
286 server_name: None,
287 in_app_include: vec![],
288 in_app_exclude: vec![],
289 integrations: vec![],
290 default_integrations: true,
291 before_send: None,
292 before_breadcrumb: None,
293 transport: None,
294 http_proxy: None,
295 https_proxy: None,
296 shutdown_timeout: Duration::from_secs(2),
297 accept_invalid_certs: false,
298 auto_session_tracking: false,
299 session_mode: SessionMode::Application,
300 extra_border_frames: vec![],
301 trim_backtraces: true,
302 user_agent: Cow::Borrowed(USER_AGENT),
303 max_request_body_size: MaxRequestBodySize::Medium,
304 }
305 }
306}
307
308impl<T: IntoDsn> From<(T, ClientOptions)> for ClientOptions {
309 fn from((into_dsn, mut opts): (T, ClientOptions)) -> ClientOptions {
310 opts.dsn = into_dsn.into_dsn().expect("invalid value for DSN");
311 opts
312 }
313}
314
315impl<T: IntoDsn> From<T> for ClientOptions {
316 fn from(into_dsn: T) -> ClientOptions {
317 ClientOptions {
318 dsn: into_dsn.into_dsn().expect("invalid value for DSN"),
319 ..ClientOptions::default()
320 }
321 }
322}