You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 096e416
Browse filesBrowse the repository at this point in the historyBrowse files
docs(native): regroup and add missing options (#20415)
## DESCRIBE YOUR PR
The Native SDK's options page was missing options, and "Core Options"
had grown into a catch-all. Shorter groups with descriptive titles are
lighter to glance through, and hopefully make it easier to find whatever
one is looking for.
#### Core Options
- Add `dist`, `logger_level`, `logger`, `logger_enabled_when_crashed`,
`attach_stacktrace` and `shutdown_timeout`.
- Move `logs_with_attributes` here from Logs Options.
#### Hooks
- Add `before_breadcrumb`, `before_screenshot`, `on_crashed_last_run`
and `initial_scope`.
- Move `before_send_log` and `before_send_metric` here from Logs Options
and Metrics Options.
#### Crash Handling Options (new)
- Add `symbolize_stacktraces`, `system_crash_reporter_enabled`,
`max_stack_capture_size`, `handler_strategy`, and
`crash_memory_reserve`.
#### Native Backend Options (new)
- Move `crash_reporting_mode` and `minidump_mode` here from Core
Options.
- Add `thread_stackwalk_mode`, `crash_upload_mode` and `minidump_flags`.
#### Crashpad Backend Options (new)
- Move `crashpad_wait_for_upload` here from Core Options.
- Add `crashpad_limit_stack_capture_to_sp`.
#### Tracing Options
- Move `propagate_traceparent` here from Core Options.
- Add `max_spans`, `strict_trace_continuation` and `org_id`.
#### Logs Options and Metrics Options
- Remove the emptied sections.
#### Transport Options
- Add `transfer_timeout`, `ca_certs` and `enable_large_attachments`.
<!-- Keep the urgency section so automation can prioritize this PR. You
may delete other sections you don't need. -->
## IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs
to go live.
Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the
due date. You can update this information later by editing the PR
description.
- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] No deadline: Not urgent, can wait up to 1 week+
## SLA
- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
supplied a deadline.
Thanks in advance for your help!
## PRE-MERGE CHECKLIST
_Make sure you've checked the following before merging your changes:_
- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)
## LEGAL BOILERPLATE
<!-- Sentry employees and contractors can delete or ignore this section.
-->
Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.
## EXTRA RESOURCES
- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)
Sets the minimum level of the debug messages the SDK logs. Has no effect unless `debug` is enabled.
38
+
39
+
</SdkOption>
40
+
41
+
<SdkOptionname="logger"type="function">
42
+
43
+
This function is called with the level, the format string, and the arguments of each debug message, and replaces the default logger, which prints to `stderr` or, on Android, to logcat. It's only called when `debug` is enabled. Multiple threads may call it concurrently.
44
+
45
+
</SdkOption>
46
+
47
+
<SdkOptionname="logger_enabled_when_crashed"type="bool"defaultValue="true"defaultNote="false for breakpad on macOS"availableSince="0.11.0">
48
+
49
+
Whether the SDK keeps calling the logger after it detects a crash. Disabling it avoids potential issues that logging might cause during crash handling.
Sets the release. Release names are strings, but some formats are detected by Sentry and might be rendered differently. Learn more about how to send release data so Sentry can tell you about regressions between releases and identify the potential source in [the releases documentation](/product/releases/) or the <SandboxLinkscenario="releases">sandbox</SandboxLink>.
@@ -48,53 +66,51 @@ By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` env
Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly.
71
+
Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application.
This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped.
77
+
Configures the sample rate for error events, in the range of `0.0`to `1.0`. The default is `1.0`, which means that 100% of error events will be sent. If set to `0.1`, only 10% of error events will be sent. Events are picked randomly.
Whether Crashpad should delay application shutdown until the upload of the crash report in the `crashpad_handler` is complete. This is useful for deployment in `Docker` (Linux and Windows containers) or `systemd`, where the life cycle of all processes is bound by the root process (typically the application being monitored).
83
+
This variable controls the total amount of breadcrumbs that should be captured. This defaults to `100`, but you can set this to any number. However, you should be aware that Sentry has a [maximum payload size](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) and any events exceeding that payload size will be dropped.
Controls which crash report format the `native` backend sends when the application crashes. This setting only affects the `native` backend. See [Crash Reporting Modes](/platforms/native/configuration/backends/native/#crash-reporting-modes).
89
+
Set this boolean to `false` to disable client reports. Client reports are a protocol feature that allows clients to send status information about themselves to Sentry. They’re currently used mainly to report outcomes for events that were never sent.
Controls how much memory the `native` backend captures in minidumps. This setting only affects the `native` backend and crash reporting modes that send a minidump. See [Minidump Capture Modes](/platforms/native/configuration/backends/native/#minidump-capture-modes).
95
+
Disables uploads until the user has given consent to the SDK. Give consent with `sentry_user_consent_give` and revoke it with `sentry_user_consent_revoke`. The SDK discards envelopes captured before consent is given, unless [offline caching](/platforms/native/configuration/transports/#offline-caching) or [HTTP retry](/platforms/native/configuration/transports/#retrying-failed-uploads) is enabled.
Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` header for [distributed tracing](https://docs.sentry.io/platforms/native/tracing/trace-propagation/custom-instrumentation/).
Attaches the stack trace of the capturing thread to events that carry none, such as messages. Events that already carry a stack trace, including crashes, are left untouched. With a stack trace, messages group by call site rather than by message text.
Set this boolean to `false` to disable client reports. Client reports are a protocol feature that allows clients to send status information about themselves to Sentry. They’re currently used mainly to report outcomes for events that were never sent.
107
+
Sets the maximum time, in milliseconds, that `sentry_close()` waits for asynchronous tasks, such as pending uploads, to finish before it attempts a forced termination.
Disables uploads until the user has given consent to the SDK. Give consent with `sentry_user_consent_give` and revoke it with `sentry_user_consent_revoke`. The SDK discards envelopes captured before consent is given, unless [offline caching](/platforms/native/configuration/transports/#offline-caching) or [HTTP retry](/platforms/native/configuration/transports/#retrying-failed-uploads) is enabled.
113
+
Whether calls to `sentry_log_X()` expect an attributes object as the second argument, allowing users to pass in custom log attributes. An example can be found on the [Logs page](/platforms/native/logs/#additional-attributes).
98
114
99
115
</SdkOption>
100
116
@@ -130,6 +146,124 @@ User feedback does not go through <PlatformIdentifier name="before_send" />, so
130
146
131
147
</SdkOption>
132
148
149
+
<SdkOptionname="before_send_log"type="function">
150
+
151
+
This function is called with an SDK-specific log object, and can return a modified log object, or `sentry_value_new_null()` to drop the log. In that case, you **must** call `sentry_value_decref(log)` before returning.
This function is called with an SDK-specific metric object, and can return a modified metric object, or `sentry_value_new_null()` to drop the metric. In that case, you **must** call `sentry_value_decref(metric)` before returning. An example can be found on the [Metrics page](/platforms/native/metrics/#before_send_metric).
This function is called with each breadcrumb passed to `sentry_add_breadcrumb()`, and can return a modified breadcrumb, or `sentry_value_new_null()` to drop it. To drop it, you **must** call `sentry_value_decref(breadcrumb)` before returning.
This function is called with the event before a screenshot is captured for it, and should return non-zero to capture the screenshot or zero to skip it. It doesn't take ownership of the event. It's only called on Windows when <PlatformLinkto="/enriching-events/screenshots/">screenshots</PlatformLink> are enabled, and isn't supported by the `crashpad` backend.
This function is called during `sentry_init()` for every envelope of a crash from a previous run. It doesn't take ownership of the envelope, which is only valid during the call. Because `sentry_init()` hasn't completed yet, the function must not call SDK functions that require an initialized SDK. With the `native` backend, the option must also be set in the run that crashed, so that the crash daemon keeps the envelope for the next launch.
This function is called once during `sentry_init()` with the global scope, before the crash backend starts, so the data it sets is available to crash reports, including those of out-of-process crash handlers. Configure the scope with the `sentry_scope_*` functions rather than global functions such as `sentry_set_tag`.
182
+
183
+
</SdkOption>
184
+
185
+
## Crash Handling Options
186
+
187
+
<SdkOptionname="symbolize_stacktraces"type="bool"defaultValue="false"defaultNote="true with the native backend, and on Android, AIX, and PlayStation">
188
+
189
+
Enables client-side symbolication of stack traces. This is useful for resolving system library frames when debug information files can't be provided for server-side symbolication. It can have a performance impact, because symbolication runs in the application process when the `inproc` backend handles a crash, or when you capture an event with any backend.
Forwards crashes to the macOS system crash reporter. Depending on the crash, this may increase the time it takes to handle it. This setting only affects the `crashpad` and `native` backends on macOS.
196
+
197
+
</SdkOption>
198
+
199
+
<SdkOptionname="max_stack_capture_size"type="uint32_t"defaultValue="0"defaultNote="bytes, no limit"availableSince="0.17.2">
200
+
201
+
Limits the size of the stack captured for each non-crashing thread. The crashed thread is not limited. Set to `0` for no limit. This setting only affects the `crashpad` and `native` backends on Linux.
Controls when the SDK invokes a previously installed signal handler. By default, it's invoked after the SDK has handled the signal. `SENTRY_HANDLER_STRATEGY_CHAIN_AT_START` invokes it first instead, which is needed for runtimes like CLR or Mono that convert some signals into managed exceptions. Otherwise, the SDK would report a native crash in addition to the managed exception. This setting only affects the `inproc` backend on Linux and Android, and the `native` backend on Linux.
Sets the amount of memory, in bytes, that the SDK reserves during `sentry_init()` and releases when it handles a crash, so the crash handler can still allocate after the application has run out of memory. Set to `0` to disable it. The default comes from the `SENTRY_CRASH_MEMORY_RESERVE` CMake option, which is set in KiB.
214
+
215
+
</SdkOption>
216
+
217
+
## Native Backend Options
218
+
219
+
These options only affect the [`native` backend](/platforms/native/configuration/backends/native/).
Controls which crash report format the `native` backend sends when the application crashes. This setting only affects the `native` backend. See [Crash Reporting Modes](/platforms/native/configuration/backends/native/#crash-reporting-modes).
Controls how much memory the `native` backend captures in minidumps. This setting only affects the `native` backend and crash reporting modes that send a minidump. See [Minidump Capture Modes](/platforms/native/configuration/backends/native/#minidump-capture-modes).
Controls which threads the `native` backend walks when it unwinds stacks on the client. With `SENTRY_THREAD_STACKWALK_MODE_CRASHED_ONLY`, only the crashed thread gets a stack trace, and the remaining threads are listed with their ID and name. This shortens crash processing for applications with many threads. This setting only affects the `native` backend and crash reporting modes with client-side stack walking.
Controls whether the crashed application waits for the `native` backend's crash daemon to finish uploading. With `SENTRY_CRASH_UPLOAD_MODE_ASYNC`, the application can exit as soon as the crash data has been captured, while the daemon continues the upload in the background. This setting only affects the `native` backend.
Sets the raw Windows [`MINIDUMP_TYPE`](https://learn.microsoft.com/en-us/windows/win32/api/minidumpapiset/ne-minidumpapiset-minidump_type) flags for minidumps. When set, these flags take precedence over `minidump_mode`. Unsupported bits are discarded, and `0` selects `MiniDumpNormal`. This setting only affects the `native` backend on Windows.
248
+
249
+
</SdkOption>
250
+
251
+
## Crashpad Backend Options
252
+
253
+
These options only affect the [`crashpad` backend](/platforms/native/configuration/backends/crashpad/).
Whether Crashpad should delay application shutdown until the upload of the crash report in the `crashpad_handler` is complete. This is useful for deployment in `Docker` (Linux and Windows containers) or `systemd`, where the life cycle of all processes is bound by the root process (typically the application being monitored).
Uses the current stack pointer to bound the stack capture of the `crashpad` backend, instead of the full stack region derived from the thread environment block (TEB). This is useful when running under Wine or Proton, where incorrect TEB values can lead to excessively large stack captures. This setting only affects the `crashpad` backend on Windows.
This function is called with an SDK-specific log object, and can return a modified log object, or `sentry_value_new_null()` to drop the log. In that case, you **must** call `sentry_value_decref(log)` before returning.
283
+
Sets the maximum number of spans that can be attached to a transaction.
Whether calls to `sentry_log_X()` expect an attributes object as the second argument, allowing users to pass in custom log attributes. An example can be found on the [Logs page](/platforms/native/logs/#additional-attributes).
289
+
Controls whether the SDK should propagate the W3C `traceparent` HTTP header alongside the `sentry-trace` header for [distributed tracing](https://docs.sentry.io/platforms/native/tracing/trace-propagation/custom-instrumentation/).
Controls whether to continue an incoming trace when only one of the trace and the SDK has an organization ID. When enabled, the SDK starts a new trace in that case. When disabled, it continues the incoming trace. If both organization IDs are present and differ, the SDK never continues the trace. See [strict trace continuation](https://develop.sentry.dev/sdk/foundations/trace-propagation/#strict-trace-continuation).
164
298
165
-
This function is called with an SDK-specific metric object, and can return a modified metric object, or `sentry_value_new_null()` to drop the metric. In that case, you **must** call `sentry_value_decref(metric)` before returning. An example can be found on the [Metrics page](/platforms/native/metrics/#before_send_metric).
Overrides the organization ID that the SDK derives from the DSN host, such as `123456` from `o123456.ingest.sentry.io`. This is typically only needed for self-hosted setups where the DSN host doesn't contain the organization ID.
166
304
167
305
</SdkOption>
168
306
@@ -217,3 +355,21 @@ Sets the maximum size in bytes for the cache directory. On startup, the SDK remo
217
355
Sets the maximum age in seconds for entries in the cache directory. On startup, the SDK removes cached entries exceeding the limit. Set to `0` for no limit. See [Offline Caching](/platforms/native/configuration/transports/#offline-caching).
218
356
219
357
</SdkOption>
358
+
359
+
<SdkOptionname="transfer_timeout"type="uint64_t"defaultValue="0"defaultNote="milliseconds, no limit"availableSince="0.15.0">
360
+
361
+
Sets the timeout in milliseconds for HTTP transfers. With curl, it limits the total time a request may take. With WinHTTP, it applies to individual send and receive operations. Set to `0` for no limit. Crashpad's crash report upload doesn't support it.
362
+
363
+
</SdkOption>
364
+
365
+
<SdkOptionname="ca_certs"type="string">
366
+
367
+
Sets the path to a file containing the SSL certificates used for verification. Only the `curl` transport uses this option.
Uploads attachments above an internal size threshold in a separate request before the envelope is sent, instead of embedding them in the envelope. Without it, Sentry rejects oversized uploads. This requires the `projects:relay-upload-endpoint` server-side feature.
0 commit comments