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, Log, Metric};
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.
101 pub debug: bool,
102 /// The release to be sent with events.
103 pub release: Option<Cow<'static, str>>,
104 /// The environment to be sent with events.
105 ///
106 /// Defaults to either `"development"` or `"production"` depending on the
107 /// `debug_assertions` cfg-attribute.
108 pub environment: Option<Cow<'static, str>>,
109 /// The sample rate for event submission. (0.0 - 1.0, defaults to 1.0)
110 pub sample_rate: f32,
111 /// The sample rate for tracing transactions. (0.0 - 1.0, defaults to 0.0)
112 pub traces_sample_rate: f32,
113 /// If given, called with a SamplingContext for each transaction to determine the sampling rate.
114 ///
115 /// Return a sample rate between 0.0 and 1.0 for the transaction in question.
116 /// Takes priority over the `sample_rate`.
117 pub traces_sampler: Option<Arc<TracesSampler>>,
118 /// Maximum number of breadcrumbs. (defaults to 100)
119 pub max_breadcrumbs: usize,
120 /// Attaches stacktraces to messages.
121 pub attach_stacktrace: bool,
122 /// If turned on, some information that can be considered PII is captured, such as potentially sensitive HTTP headers and user IP address in HTTP server integrations.
123 pub send_default_pii: bool,
124 /// The server name to be reported.
125 pub server_name: Option<Cow<'static, str>>,
126 /// Module prefixes that are always considered "in_app".
127 pub in_app_include: Vec<&'static str>,
128 /// Module prefixes that are never "in_app".
129 pub in_app_exclude: Vec<&'static str>,
130 // Integration options
131 /// A list of integrations to enable.
132 ///
133 /// See [`sentry::integrations`](integrations/index.html#installing-integrations) for
134 /// how to use this to enable extra integrations.
135 pub integrations: Vec<Arc<dyn Integration>>,
136 /// Whether to add default integrations.
137 ///
138 /// See [`sentry::integrations`](integrations/index.html#default-integrations) for
139 /// details how this works and interacts with manually installed integrations.
140 pub default_integrations: bool,
141 // Hooks
142 /// Callback that is executed before event sending.
143 pub before_send: Option<BeforeCallback<Event<'static>>>,
144 /// Callback that is executed for each Breadcrumb being added.
145 pub before_breadcrumb: Option<BeforeCallback<Breadcrumb>>,
146 /// Callback that is executed for each Log being added.
147 ///
148 /// This callback has no effect unless the `logs` feature is enabled at compile-time, as the
149 /// feature is a pre-requisite to capturing logs.
150 pub before_send_log: Option<BeforeCallback<Log>>,
151 // Transport options
152 /// The transport to use.
153 ///
154 /// This is typically either a boxed function taking the client options by
155 /// reference and returning a `Transport`, a boxed `Arc<Transport>` or
156 /// alternatively the `DefaultTransportFactory`.
157 pub transport: Option<Arc<dyn TransportFactory>>,
158 /// An optional HTTP proxy to use.
159 ///
160 /// This will default to the `http_proxy` environment variable.
161 pub http_proxy: Option<Cow<'static, str>>,
162 /// An optional HTTPS proxy to use.
163 ///
164 /// This will default to the `HTTPS_PROXY` environment variable
165 /// or `http_proxy` if that one exists.
166 pub https_proxy: Option<Cow<'static, str>>,
167 /// The timeout on client drop for draining events on shutdown.
168 pub shutdown_timeout: Duration,
169 /// Controls the maximum size of an HTTP request body that can be captured when using HTTP
170 /// server integrations. Needs `send_default_pii` to be enabled to have any effect.
171 pub max_request_body_size: MaxRequestBodySize,
172 /// Determines whether captured structured logs should be sent to Sentry (defaults to false).
173 ///
174 /// This setting has no effect unless the `logs` feature is enabled at compile-time, as the
175 /// feature is a pre-requisite to sending logs.
176 pub enable_logs: bool,
177 /// Determines whether captured metrics should be sent to Sentry (defaults to false).
178 ///
179 /// This setting has no effect unless the `metrics` feature is enabled at compile-time,
180 /// as the feature is a prerequisite for sending metrics.
181 pub enable_metrics: bool,
182 /// Callback that is executed for each Metric before sending.
183 ///
184 /// This setting has no effect unless the `metrics` feature is enabled at compile-time,
185 /// as the feature is a prerequisite for sending metrics.
186 pub before_send_metric: Option<BeforeCallback<Metric>>,
187 // Other options not documented in Unified API
188 /// Disable SSL verification.
189 ///
190 /// # Warning
191 ///
192 /// This introduces significant vulnerabilities, and should only be used as a last resort.
193 pub accept_invalid_certs: bool,
194 /// Enable Release Health Session tracking.
195 ///
196 /// When automatic session tracking is enabled, a new "user-mode" session
197 /// is started at the time of `sentry::init`, and will persist for the
198 /// application lifetime.
199 ///
200 /// This setting has no effect unless the `release-health` feature is enabled at compile-time,
201 /// as the feature is a pre-requisite to tracking sessions.
202 pub auto_session_tracking: bool,
203 /// Determine how Sessions are being tracked.
204 ///
205 /// This setting has no effect unless the `release-health` feature is enabled at compile-time,
206 /// as the feature is a pre-requisite to tracking sessions.
207 pub session_mode: SessionMode,
208 /// The user agent that should be reported.
209 pub user_agent: Cow<'static, str>,
210}
211
212impl ClientOptions {
213 /// Creates new Options.
214 pub fn new() -> Self {
215 Self::default()
216 }
217
218 /// Adds a configured integration to the options.
219 ///
220 /// # Examples
221 ///
222 /// ```
223 /// struct MyIntegration;
224 ///
225 /// impl sentry::Integration for MyIntegration {}
226 ///
227 /// let options = sentry::ClientOptions::new().add_integration(MyIntegration);
228 /// assert_eq!(options.integrations.len(), 1);
229 /// ```
230 #[must_use]
231 pub fn add_integration<I: Integration>(mut self, integration: I) -> Self {
232 self.integrations.push(Arc::new(integration));
233 self
234 }
235}
236
237impl fmt::Debug for ClientOptions {
238 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
239 #[derive(Debug)]
240 struct BeforeSend;
241 let before_send = self.before_send.as_ref().map(|_| BeforeSend);
242 #[derive(Debug)]
243 struct BeforeBreadcrumb;
244 let before_breadcrumb = self.before_breadcrumb.as_ref().map(|_| BeforeBreadcrumb);
245 let before_send_log = {
246 #[derive(Debug)]
247 struct BeforeSendLog;
248 self.before_send_log.as_ref().map(|_| BeforeSendLog)
249 };
250 let before_send_metric = {
251 #[derive(Debug)]
252 struct BeforeSendMetric;
253 self.before_send_metric.as_ref().map(|_| BeforeSendMetric)
254 };
255 #[derive(Debug)]
256 struct TransportFactory;
257
258 let integrations: Vec<_> = self.integrations.iter().map(|i| i.name()).collect();
259
260 let mut debug_struct = f.debug_struct("ClientOptions");
261 debug_struct
262 .field("dsn", &self.dsn)
263 .field("debug", &self.debug)
264 .field("release", &self.release)
265 .field("environment", &self.environment)
266 .field("sample_rate", &self.sample_rate)
267 .field("traces_sample_rate", &self.traces_sample_rate)
268 .field(
269 "traces_sampler",
270 &self
271 .traces_sampler
272 .as_ref()
273 .map(|arc| std::ptr::addr_of!(**arc)),
274 )
275 .field("max_breadcrumbs", &self.max_breadcrumbs)
276 .field("attach_stacktrace", &self.attach_stacktrace)
277 .field("send_default_pii", &self.send_default_pii)
278 .field("server_name", &self.server_name)
279 .field("in_app_include", &self.in_app_include)
280 .field("in_app_exclude", &self.in_app_exclude)
281 .field("integrations", &integrations)
282 .field("default_integrations", &self.default_integrations)
283 .field("before_send", &before_send)
284 .field("before_breadcrumb", &before_breadcrumb)
285 .field("transport", &TransportFactory)
286 .field("http_proxy", &self.http_proxy)
287 .field("https_proxy", &self.https_proxy)
288 .field("shutdown_timeout", &self.shutdown_timeout)
289 .field("accept_invalid_certs", &self.accept_invalid_certs)
290 .field("auto_session_tracking", &self.auto_session_tracking)
291 .field("session_mode", &self.session_mode)
292 .field("enable_logs", &self.enable_logs)
293 .field("before_send_log", &before_send_log)
294 .field("enable_metrics", &self.enable_metrics)
295 .field("before_send_metric", &before_send_metric)
296 .field("user_agent", &self.user_agent)
297 .finish()
298 }
299}
300
301impl Default for ClientOptions {
302 fn default() -> ClientOptions {
303 ClientOptions {
304 dsn: None,
305 debug: false,
306 release: None,
307 environment: None,
308 sample_rate: 1.0,
309 traces_sample_rate: 0.0,
310 traces_sampler: None,
311 max_breadcrumbs: 100,
312 attach_stacktrace: false,
313 send_default_pii: false,
314 server_name: None,
315 in_app_include: vec![],
316 in_app_exclude: vec![],
317 integrations: vec![],
318 default_integrations: true,
319 before_send: None,
320 before_breadcrumb: None,
321 transport: None,
322 http_proxy: None,
323 https_proxy: None,
324 shutdown_timeout: Duration::from_secs(2),
325 accept_invalid_certs: false,
326 auto_session_tracking: false,
327 session_mode: SessionMode::Application,
328 user_agent: Cow::Borrowed(USER_AGENT),
329 max_request_body_size: MaxRequestBodySize::Medium,
330 enable_logs: true,
331 before_send_log: None,
332 enable_metrics: false,
333 before_send_metric: None,
334 }
335 }
336}
337
338impl<T: IntoDsn> From<(T, ClientOptions)> for ClientOptions {
339 fn from((into_dsn, mut opts): (T, ClientOptions)) -> ClientOptions {
340 opts.dsn = into_dsn.into_dsn().expect("invalid value for DSN");
341 opts
342 }
343}
344
345impl<T: IntoDsn> From<T> for ClientOptions {
346 fn from(into_dsn: T) -> ClientOptions {
347 ClientOptions {
348 dsn: into_dsn.into_dsn().expect("invalid value for DSN"),
349 ..ClientOptions::default()
350 }
351 }
352}