diff --git a/src/platform-includes/configuration/tags/defining-is-easy/native.mdx b/src/platform-includes/configuration/tags/defining-is-easy/native.mdx new file mode 100644 index 0000000000000..d633be8007660 --- /dev/null +++ b/src/platform-includes/configuration/tags/defining-is-easy/native.mdx @@ -0,0 +1 @@ +Defining tags is easy, and will bind them to the [current scope](../scopes/) ensuring all future events within scope contain the same tags. diff --git a/src/platform-includes/configuration/tags/defining-is-easy/native.minidumps.mdx b/src/platform-includes/configuration/tags/defining-is-easy/native.minidumps.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/configuration/tags/defining-is-easy/native.wasm.mdx b/src/platform-includes/configuration/tags/defining-is-easy/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-file-formats-mach-o-dsym/native.mdx b/src/platform-includes/debug-file-formats-mach-o-dsym/native.mdx new file mode 100644 index 0000000000000..281264e3b3d21 --- /dev/null +++ b/src/platform-includes/debug-file-formats-mach-o-dsym/native.mdx @@ -0,0 +1,123 @@ +## Mach-O and dSYM + +Executables, dynamic libraries and debug companions on all Apple platforms use +the _Mach Object_, or short _Mach-O_, container format. This applies to iOS, +iPadOS, tvOS, watchOS, macOS, and visionOS. + +- **Executables** do not carry a file extension. For desktop applications, they + are often placed in app bundle structures with the `.app` suffix. Unless + stripped manually, executables contain unwind information and a symbol table. + Debug information is never stored in executables. + +- **Dynamic Libraries** use the `.dylib` extension, and otherwise behave exactly + the same as executables. + +- **Debug Companions** are placed in a folder structure with the `.dSYM` + extension, and are located at `.dSYM/Contents/Resources/DWARF/`. + They usually contain a symbol table and debug information, but rarely unwind + information. + +When building an application with Xcode or with the `clang` compiler, debug +information is automatically placed in a dSYM file. When linking manually, +however, the dSYM file must be created using the following command: + +```bash +dsymutil /path/to/output[.dylib] +``` + +## Executable and Linkable Format (ELF) + +On Linux distributions, executables and debug information are stored in _ELF_ +containers. Unlike other platforms, there is no dedicated container or specifier +for debug companion files. + +Debug information is part of the binary (executable or library) and stripped +when generating release builds due to their size. However, there is a way to +retain them in a separate file (either in a different location or with `.debug` +extension): + +```bash +# There is an executable called "binary" in the CWD +objcopy --only-keep-debug binary binary.debug +objcopy --strip-debug --strip-unneeded binary +objcopy --add-gnu-debuglink=binary.debug binary +``` + +This results in the following structure: + +- **Executables** do not carry a file extension. If stripped like above, + executables contain a symbol table, but no debug information. If the build + run omits frame pointers, unwind information will also be retained. Both can + be further stripped using flags like `--strip-all`. + +- **Shared Libraries** use the `.so` extension, and otherwise behave exactly + the same as executables. + +- **Debug Companions** do not carry a standard file extension, but are often + named `.debug`. If stripped like above, these files contain unwind + information, debug information and a symbol table. + +Shared libraries installed via package managers usually provide their debugging +information in separate `*-dev` packages and put it in locations like +`/usr/local/debug/...`. To receive symbolicated stack traces from those +libraries, make sure to also upload their symbols in addition to your app’s +symbols. + +ELF supports the compression of debug information which can significantly reduce +the time required to upload debug information files to Sentry and thus improve +build times. `gcc` (version 5 or newer) and `clang` (version 5 or newer) support +this by passing the `-gz` flag to both the compiler and linker. The common way +to compress debug information, however, is when stripping the executable: + +```bash +# Note the --compress-debug-sections option +objcopy --only-keep-debug --compress-debug-sections=zlib binary binary.debug +``` + +This can be verified by checking for the `C` flag in `readelf`, corresponding to +`SHF_COMPRESSED`: + +```bash +readelf -S path/to/file + ... + [21] .debug_info PROGBITS 0000000000000000 00000370 + 000000000000e133 0000000000000000 C 0 0 1 +``` + +## PE and PDB + +Executables and dynamic libraries on Microsoft Windows, and those created by the +.NET platform on all operating systems, use the _Portable Executable_ (_PE_) +container format. Associated debug information is stored in _Program Database_ +(_PDB_) files. + +- **Executables** use an `.exe` file extension. Only when compiled for 64-bit + architectures, they contain unwind information. Otherwise, they do not contain + any usable information and will be omitted for the upload to Sentry. + +- **Dynamic Libraries** use the `.dll` file extension, and otherwise behave + exactly the same as executables. + +- **Debug Companions** are stored in `.pdb` files. They usually contain debug + information and in most cases symbol tables. For 32-bit programs, they also + contain unwind information. In rare cases, they might have different file + names than their corresponding executable. + +- The .NET platform uses a variation of this format, called [Portable PDBs](https://github.com/dotnet/core/blob/main/Documentation/diagnostics/portable_pdb.md). + Portable PDBs are supported as of Sentry 22.11.0 (or Sentry CLI 2.8.0, or Symbolic 10.0.0). + +## Breakpad Symbols + +The Google Breakpad library has established a platform-independent ASCII format +to store debug information. Such files are usually generated for applications +using Breakpad, Crashpad, or the Electron Framework. + +The Breakpad repository includes `dump_syms` tools for each platform that can +convert from native debug files to Breakpad symbols. These converters bundle all +available information into one file, such that only one file needs to be +uploaded. + +In contrast to native debug files, Breakpad symbols discard a lot of information +that is not required to process minidumps. Most notably, inline functions are +not declared, such that Sentry is not able to display inline frames in stack +traces. diff --git a/src/platform-includes/debug-file-formats-mach-o-dsym/native.wasm.mdx b/src/platform-includes/debug-file-formats-mach-o-dsym/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-file-formats-proguard-mappings/native.mdx b/src/platform-includes/debug-file-formats-proguard-mappings/native.mdx new file mode 100644 index 0000000000000..6ea7e6c2dea75 --- /dev/null +++ b/src/platform-includes/debug-file-formats-proguard-mappings/native.mdx @@ -0,0 +1,5 @@ +## ProGuard Mappings + +ProGuard mapping files allow Sentry to resolve obfuscated Java classpaths and +method names into their original form. In that sense, they act as debug +information files for Java and Android applications. diff --git a/src/platform-includes/debug-file-formats-proguard-mappings/native.wasm.mdx b/src/platform-includes/debug-file-formats-proguard-mappings/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-files-identifiers-gnu-build-identifiers/native.mdx b/src/platform-includes/debug-files-identifiers-gnu-build-identifiers/native.mdx new file mode 100644 index 0000000000000..401930719b538 --- /dev/null +++ b/src/platform-includes/debug-files-identifiers-gnu-build-identifiers/native.mdx @@ -0,0 +1,15 @@ +## GNU Build Identifiers + +For ELF files on Linux, Sentry uses the GNU build identifier to compute the +debug identifier. All recent compilers and linkers support the emission of build +IDs, but sometimes they might require additional configuration. `gcc` does this +by default, for `clang` use one of the following flags: + +- `--build-id=uuid` for a fast but non-reproducible random identifier. +- `--build-id=sha1` for a slower but reproducible identifier generated by + hashing the first page of the code section. + +_The identifier needs to be present and identical in the binary as well +as stripped debug information files._ If the ID is missing for some reason, +upload the files before stripping so that `sentry-cli` can compute a stable +identifier from the unstripped file. diff --git a/src/platform-includes/debug-files-identifiers-gnu-build-identifiers/native.wasm.mdx b/src/platform-includes/debug-files-identifiers-gnu-build-identifiers/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-files-identifiers-pdb-age-mismatches/native.mdx b/src/platform-includes/debug-files-identifiers-pdb-age-mismatches/native.mdx new file mode 100644 index 0000000000000..a88bc2291b9c2 --- /dev/null +++ b/src/platform-includes/debug-files-identifiers-pdb-age-mismatches/native.mdx @@ -0,0 +1,22 @@ +## PDB Age Mismatches + +Microsoft PDBs compose their identifiers from two parts: A unique signature and +an age field. The signature is generated when the PDB is written initially and +usually changes with every build. The age is a counter that is incremented every +time the PDB is modified. + +PE files, such as executables and dynamic libraries, specify the full identifier +of the corresponding PDB in their header. This includes the age. If the PDB is +modified after the PE has been generated, however, its age might diverge. This +can lead to different identifiers: + +``` +PE: 3003763b-afcb-4a97-aae3-28de8f188d7c-2 +PDB: 3003763b-afcb-4a97-aae3-28de8f188d7c-4 +``` + +`sentry-cli` can detect these differences during the upload process and +associates the same identifier to both files. However, this requires that both +files are uploaded in the same invocation of the upload command. Otherwise, the +identifiers diverge and Sentry might not be able to resolve the correct file +for symbolication. diff --git a/src/platform-includes/debug-files-identifiers-pdb-age-mismatches/native.wasm.mdx b/src/platform-includes/debug-files-identifiers-pdb-age-mismatches/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-files-identifiers-proguard/native.mdx b/src/platform-includes/debug-files-identifiers-proguard/native.mdx new file mode 100644 index 0000000000000..63b89f834add5 --- /dev/null +++ b/src/platform-includes/debug-files-identifiers-proguard/native.mdx @@ -0,0 +1,19 @@ +## ProGuard UUIDs + +Unlike other debug information files, ProGuard files do not have an intrinsic +unique identifier. Sentry CLI assigns them a SHA1 UUID based on the checksum of +the file. You can use `sentry-cli debug-files check` on a ProGuard file to see the +generated UUID. + +If you need to generate the UUID yourself, you can do so with the following +algorithm (Python code for reference): + +```python +import uuid + +NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, "guardsquare.com") + +def get_proguard_uuid(filename): +with open(filename, 'rb') as f: +return uuid.uuid5(NAMESPACE, f.read()) +``` diff --git a/src/platform-includes/debug-files-identifiers-proguard/native.wasm.mdx b/src/platform-includes/debug-files-identifiers-proguard/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-information-files/_default.mdx b/src/platform-includes/debug-information-files/_default.mdx new file mode 100644 index 0000000000000..eabf84d362a19 --- /dev/null +++ b/src/platform-includes/debug-information-files/_default.mdx @@ -0,0 +1,13 @@ +Each major platform uses different debug information files. We currently support +the following formats: + +- [_dSYM files_](./file-formats/#mach-o-and-dsym) for iOS, iPadOS, + tvOS, watchOS, macOS, and visionOS +- [_ELF symbols_](./file-formats/#executable-and-linkable-format-elf) for Linux and + Android (NDK) +- [_PDB files_](./file-formats/#pe-and-pdb) for Windows and .NET +- [_Breakpad symbols_](./file-formats/#breakpad-symbols) for all + platforms +- [_WASM files_](./file-formats/#wasm) for WebAssembly +- [_ProGuard mappings_](./file-formats/#proguard-mappings) for + Java and Android diff --git a/src/platform-includes/debug-information-files/native.wasm.mdx b/src/platform-includes/debug-information-files/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/debug-information/_default.mdx b/src/platform-includes/debug-information/_default.mdx new file mode 100644 index 0000000000000..17aca2e5e9d22 --- /dev/null +++ b/src/platform-includes/debug-information/_default.mdx @@ -0,0 +1,5 @@ +In addition to Debug Information Files, Sentry needs _Call Frame Information_ +(CFI) to extract accurate stack traces from minidumps of optimized release +builds. CFI is usually part of the executables and not copied to debug symbols. +Unless you are uploading Breakpad symbols, be sure to also include the binaries +when uploading files to Sentry. diff --git a/src/platform-includes/debug-information/native.wasm.mdx b/src/platform-includes/debug-information/native.wasm.mdx new file mode 100644 index 0000000000000..1129c7c917c78 --- /dev/null +++ b/src/platform-includes/debug-information/native.wasm.mdx @@ -0,0 +1,12 @@ +For WASM, you need to provide both the debug information and the original code +in the same debug information file. To do this, we provide a custom +tool called [wasm-split](https://github.com/getsentry/symbolicator/tree/master/crates/wasm-split) +that can do the splitting for you: + +```shell +wasm-split /path/to/file.wasm -d /path/to/file.debug.wasm --strip +``` + +This command modifies the `file.wasm` in place to add the `build_id`, then removes all +debug information. The debug information is put in a `file.debug.wasm` which +then needs to be uploaded to Sentry. diff --git a/src/platform-includes/sensitive-data/pii/native.breakpad.mdx b/src/platform-includes/sensitive-data/pii/native.breakpad.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/pii/native.crashpad.mdx b/src/platform-includes/sensitive-data/pii/native.crashpad.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/pii/native.mdx b/src/platform-includes/sensitive-data/pii/native.mdx new file mode 100644 index 0000000000000..0067748aa9a18 --- /dev/null +++ b/src/platform-includes/sensitive-data/pii/native.mdx @@ -0,0 +1 @@ +If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/). diff --git a/src/platform-includes/sensitive-data/pii/native.minidumps.mdx b/src/platform-includes/sensitive-data/pii/native.minidumps.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/pii/native.wasm.mdx b/src/platform-includes/sensitive-data/pii/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/scrubbing-data/native.breakpad.mdx b/src/platform-includes/sensitive-data/scrubbing-data/native.breakpad.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/scrubbing-data/native.crashpad.mdx b/src/platform-includes/sensitive-data/scrubbing-data/native.crashpad.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/scrubbing-data/native.mdx b/src/platform-includes/sensitive-data/scrubbing-data/native.mdx new file mode 100644 index 0000000000000..968e4a34e3415 --- /dev/null +++ b/src/platform-includes/sensitive-data/scrubbing-data/native.mdx @@ -0,0 +1,43 @@ +## Scrubbing Data + +### & + +SDKs provide a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. Some SDKs also provide a hook which does the same thing for transactions. We recommend using and in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. + + + +Sensitive data may appear in the following areas: + +- Stack-locals → Some SDKs (Python, PHP and Node) will pick up variable values within the stack trace. These can be scrubbed, or this behavior can be disabled altogether if necessary. +- Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. +- User context → Automated behavior is controlled via . +- HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. +- Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. + +For more details and data filtering instructions, see Filtering Events. + +### Examples + +**Contextual information** + +Instead of sending confidential information in plaintext, consider hashing it: + + + +This will allow you to correlate it within internal systems if needed, but keep it confidential from Sentry. + +**User details** + +Your organization may determine that emails are not considered confidential, but if they are, consider instead sending your internal identifier: + + + +Doing this will ensure you still benefit from user-impact related features. + +**Logging integrations** + +As a best practice you should always avoid logging confidential information. If you have legacy systems you need to work around, consider the following: + +- Anonymize the confidential information within the log statements (for example, swap out email addresses -> for internal identifiers) +- Use to filter it out from breadcrumbs before it is attached +- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/breadcrumbs/)) diff --git a/src/platform-includes/sensitive-data/scrubbing-data/native.minidumps.mdx b/src/platform-includes/sensitive-data/scrubbing-data/native.minidumps.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/sensitive-data/scrubbing-data/native.wasm.mdx b/src/platform-includes/sensitive-data/scrubbing-data/native.wasm.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platforms/native/common/configuration/filtering.mdx b/src/platforms/native/common/configuration/filtering.mdx index e379fd342e74c..bd213d5087b89 100644 --- a/src/platforms/native/common/configuration/filtering.mdx +++ b/src/platforms/native/common/configuration/filtering.mdx @@ -1,7 +1,7 @@ --- title: Filtering -sidebar_order: 60 description: "Learn more about how to configure your SDK to filter events reported to Sentry." +sidebar_order: 60 --- When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume. @@ -18,12 +18,10 @@ Configure your SDK to filter error events by using the callback method. Because it's called immediately before the event is sent to the server, this is your last chance to decide not to send data or to edit it. receives the event object as a parameter, which you can use to either modify the event’s data or drop it completely by returning `null`, based on custom logic and the data available on the event. - + Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/error-monitoring/breadcrumbs/). - - #### Event Hints The callback is passed both the `event` and a second argument, `hint`, that holds one or more hints. @@ -33,116 +31,3 @@ Typically a `hint` holds the original exception so that additional data can be e When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from a log record or exception instance. For better customization, SDKs send these objects to certain callbacks (, or the event processor system in the SDK). - - - - - -### Using Hints - -Hints are available in two places: - -1. / -2. `eventProcessors` - -Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected. - -For events, hints contain properties such as `event_id`, `originalException`, `syntheticException` (used internally to generate cleaner stack trace), and any other arbitrary `data` that you attach. - -For breadcrumbs, the use of `hints` is implementation dependent. For XHR requests, the hint contains the xhr object itself; for user interactions the hint contains the DOM element and event name and so forth. - - - -In this example, the fingerprint is forced to a common value if an exception of a certain type has been caught: - - - -#### Hints for Events - -`originalException` - -: The original exception that caused the Sentry SDK to create the event. This is useful for changing how the Sentry SDK groups events or to extract additional information. - -`syntheticException` - -: When a string or a non-error object is raised, Sentry creates a synthetic exception so you can get a basic stack trace. This exception is stored here for further data extraction. - -#### Hints for Breadcrumbs - - - - - - - -### Using - -You can use the option to filter out errors that match a certain pattern. This option receives a list of strings and regular expressions to match against the error message. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. - - - - - - -### Using - -You can use the option to filter out errors that match a type or subtype. - - - - - - -### Decluttering Sentry - - - - - - - -## Filtering Transaction Events - -To prevent certain transactions from being reported to Sentry, use the or configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. - -### Using - -**Note:** The and config options are mutually exclusive. If you define a to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled. - -In its simplest form, used just for filtering the transaction, it looks like this: - - - -It also allows you to sample different transactions at different rates. - -If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more. - -Learn more about configuring the sample rate. - - - -### Using - - - - - - - -### Using - -You can use the option to filter out transactions that match a certain pattern. This option receives a list of strings and regular expressions to match against the transaction name. When using strings, partial matches will be filtered out, so if you need to filter by exact match, use regex patterns instead. - - - - - - -### Using - -You can use the option to filter out transactions that match a certain string. - - - - - diff --git a/src/platforms/native/common/configuration/options.mdx b/src/platforms/native/common/configuration/options.mdx index 219923163b0d5..ca0a6af8c1277 100644 --- a/src/platforms/native/common/configuration/options.mdx +++ b/src/platforms/native/common/configuration/options.mdx @@ -1,7 +1,7 @@ --- title: Basic Options -sidebar_order: 1 description: "Learn more about how to configure the SDK. These options are set when the SDK is first initialized, passed to the init function as an object." +sidebar_order: 1 --- SDKs are configurable using a variety of options. The options are largely standardized among SDKs, but there are some differences to better accommodate platform peculiarities. Options are set when the SDK is first @@ -23,176 +23,32 @@ Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-uti - - -- Original - Default .NET stack trace format. -- Enhanced - Include `async`, return type, arguments, and more. - -Before version 3.0.0 of the Sentry SDK for .NET, there was no special treatment for the stack trace. Sentry reported what .NET made available at runtime. -This behavior now called `StackTraceMode.Original`. With the introduction of 3.0, a new default mode is `Enhanced`. - - - -Changing this value will affect issue grouping. Since the frame significantly changes shape. - - - - - - - -Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. - -Example scenarios where it should be explicitly set to true: - -- Universal Windows platform (UWP) applications -- WinForms applications -- Windows Presentation Foundation (WPF) applications -- Single user console applications - -Defaults to `false`, unless in Blazor WASM, MAUI, Unity, or Xamarin where the default is `true`. - - - - + Allows you to specify a path to the local event- and crash-database of the Native SDK. This path will default to `.sentry-native` relative to the current working directory (`CWD`). While this is a convenient setting for development, we strongly urge you to provide an explicit database path for our production deployments. In many deployment scenarios, the path relative to the `CWD` will not be writable. For this reason, you should store the database in your application's user-specific data/cache directory (e.g., under `%AppData%\Local` on Windows, `~/Library/Application Support` on macOS, or `XDG_CACHE_HOME` on Linux). - + Turns debug mode on or off. If debug is enabled SDK will attempt to print out useful debugging information if something goes wrong with sending the event. The default is always `false`. It's generally not recommended to turn it on in production, though turning `debug` mode on will not cause any safety concerns. - - -If enabled, the SDK prints out debug information about if something went wrong while sending events. -It isn't recommended to use this in production. - - - - - - - -Enabling `debug` mode makes the SDK generate as much diagnostic data as possible. However, if you'd prefer to lower the verbosity of the Sentry SDK diagnostics logs, configure this option to set the appropriate level: - -- `debug`: **default** The most verbose mode -- `info`: Informational messages -- `warning`: Warning that something might not be right -- `error`: Only SDK internal errors are printed -- `fatal`: Only critical errors are printed - - - - - -For app models that don't have a console to print to, you can customize the SDK's diagnostic logger to write to a file or to Visual Studio's debug window. - - - - - -Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. - - - - - -Sets the distribution of the application. Distributions are used to disambiguate build or deployment variants of the same release of an application. For example, the dist can be the build number of an Xcode build or the version code of an Android build. The dist has a max length of 64 characters. - - - - + Sets the release. Some SDKs will try to automatically configure a release out of the box but it's a better idea to manually set it to guarantee that the release is in sync with your deploy integrations or source map uploads. 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 sandbox. - - By default the SDK will try to read this value from the `SENTRY_RELEASE` environment variable (in the browser SDK, this will be read off of the `window.SENTRY_RELEASE.id` if available). - - - - -By default the SDK will read properties from the Electron `app` module to create the release in the format `appName@version`. - - - - - -By default the SDK will read from `Application.productName` and `Application.version` to create the release in the format `$"{Application.productName}@{Application.version}".` - - - - - -Sets the environment. This string is freeform and not set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). - -By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` environment variable (except for the browser SDK where this is not applicable). - - - - - Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` environment variable. Otherwise, the default environment is `production`. - - - - -Sets the environment. Defaults to `development` or `production` depending on whether the application is packaged. - - - - - -Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). - -By default, the SDK reports `editor` when running inside the Unity Editor. Otherwise, the default environment is `production`. - - - - - -Sets the environment. This string is freeform and set by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). - -By default, the SDK reports `debug` when the debugger is attached. Otherwise, the default environment is `production`. - -Additionally, if you are running with the ASP.NET Core integration, you will also see the environment named as `staging`, if running in staging, or `development`, if running in development mode. - - - - - -Sets the environment. This string is freeform and set to `production` by default. A release can be associated with more than one environment to separate them in the UI (think `staging` vs `production` or similar). - -By default the SDK will try to read this value from the `SENTRY_ENVIRONMENT` environment variable. - - - - - - - -Sets the URL that will be used to transport captured events. This can be used to work around ad-blockers or to have more granular control over events sent to Sentry. Adding your DSN is still required when using this option so necessary attributes can be set on the generated Sentry data. This option **requires the implementation** of a custom server endpoint. Learn more and find examples in [Dealing with Ad-Blockers](/platforms/javascript/troubleshooting/#dealing-with-ad-blockers). - - - - - -Sets which errors are reported. It takes the same values as PHP's [`error_reporting`](https://www.php.net/manual/errorfunc.configuration.php#ini.error-reporting) configuration parameter. - -By default all types of errors are be reported (equivalent to `E_ALL`). - @@ -201,995 +57,44 @@ Configures the sample rate for error events, in the range of `0.0` to `1.0`. The - - -Dynamically configures the sample rate for error events on a per-event basis. This configuration option accepts a function, which takes two parameters (the `event` and the `hint`), and which returns a boolean (indicating whether the event should be sent to Sentry) or a floating-point number between 0.0 and 1.0, inclusive (where the number indicates the probability the event is sent to Sentry; the SDK will randomly decide whether to send the event with the given probability). - -If this configuration option is specified, the option is ignored. - - - 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/envelopes/#size-limits) and any events exceeding that payload size will be dropped. - - -The maximum number of [envelopes](https://develop.sentry.dev/sdk/envelopes/) to keep in cache. The SDKs use envelopes to send data, such as events, attachments, user feedback, and sessions to sentry.io. An envelope can contain multiple items, such as an event with a session and two attachments. Depending on the usage of the SDK, the size of an envelope can differ. If the number of envelopes in the local cache exceeds `max-cache-items`, the SDK deletes the oldest envelope and migrates the sessions to the next envelope to maintain the integrity of your release health stats. The default is `30`. - - - - + When enabled, stack traces are automatically attached to all messages logged. Stack traces are always attached to exceptions; however, when this option is set, stack traces are also sent with messages. This option, for instance, means that stack traces appear next to all log messages. - - -This option is turned on by default. - - - - This option is turned off by default. - - Grouping in Sentry is different for events with stack traces and without. As a result, you will get new groups as you enable or disable this flag for certain events. - - -If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent. - - - -If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](/product/security/mobile-privacy/) to assist with Apple App Store and Google Play app privacy details. - - - -This option is turned off by default. - -If you enable this option, be sure to manually remove what you don't want to send using our features for managing [_Sensitive Data_](../../data-management/sensitive-data/). - - - - - -If is turned off, scrubs the event payload for sensitive information from a `denylist`. See how to [configure the scrubber here](../../data-management/sensitive-data/#event-scrubber). - - - - - -When enabled, source context will be included in events sent to Sentry. This source context includes the five lines of code above and below the line of code where an error happened. - -The option is enabled by default. - - - - - -When enabled, the SDK will capture a snapshot of local variables to send with the event to help with debugging. - -This option is on by default. - - - - - -This option can be used to supply a "server name." When provided, the name of the server is sent along and persisted in the event. For many integrations, the server name actually corresponds to the device hostname, even in situations where the machine is not actually a server. - - - -Most SDKs will attempt to auto-discover this value. - - - - - -For ASP.NET and ASP.NET Core applications, the value will default to the server's name. For other application types, the value will default to the computer's name only when the `SendDefaultPii` is set to `true`, because the computer's name can be considered personally identifiable information (PII) in the case of a desktop or mobile application. - - - - - - - - - - - - - -A list of class names that matches exceptions that shouldn't be sent to Sentry. -Checks whether the provided class name is of a given type or subtype. - - - - - - - - - - - -A list of strings that match transaction names that shouldn't be sent to Sentry. - - - - - - - - - - - - - - - - - -When set to `true`, the SDK will send session events to Sentry. This is supported in all browser SDKs, emitting one session per pageload and page navigation to Sentry. In mobile SDKs, when the app goes to the background for longer than 30 seconds, sessions are ended. - - - - - -When not set to `false`, the SDK tracks sessions linked to the lifetime of the Electron main process. - - - - - -Configures whether stack trace frames are considered as in app frames by default. -You can use this to essentially make `inAppIncludes` or `inAppExcludes` an allow or deny list. -This value is used only if Sentry can not find the origin of the frame. - -- If `considerInAppFramesByDefault` is set to `true`, you only need to maintain `inAppExcludes`. -- Conversely, if `considerInAppFramesByDefault` is set to `false`, you only need to maintain `inAppIncludes`. - - - - - -A list of string prefixes of module names that belong to the app. This option takes precedence over `in-app-exclude`. - -Sentry differentiates stack frames that are directly related to your application ("in application") from stack frames that come from other packages such as the standard library, frameworks, or other dependencies. The application package is automatically marked as `inApp`. The difference is visible in [sentry.io](https://sentry.io), where only the "in application" frames are displayed by default. - - - - - -A list of string prefixes of module names that do not belong to the app, but rather to third-party packages. Modules considered not part of the app will be hidden from stack traces by default. - -This option can be overridden using . - - - - - -A list of exception types that will be filtered out before sending to Sentry. - - - - - -This parameter controls whether integrations should capture HTTP request bodies. It can be set to one of the following values: - -- `never`: Request bodies are never sent. -- `small`: Only small request bodies will be captured. The cutoff for small depends on the SDK (typically 4KB). -- `medium`: Medium and small requests will be captured (typically 10KB). -- `always`: The SDK will always capture the request body as long as Sentry can make sense of it. - - - - - -The number of characters after which the values containing text in the event payload will be truncated (defaults to `1024`). - - - If the value you set for this is exceptionally large, the event may exceed 1 - MiB and will be dropped by Sentry. - - - - - - -A path to an alternative CA bundle file in PEM-format. - - - - - -The number of context lines for each frame in the stack trace when loading a file. - - - - - -The number of context lines for each frame when loading a file. - -#### Deprecated - -`frameContextLines` has moved to the `ContextLines` integration. - - - - - -#### Deprecated - -Has been renamed to [max_request_body_size](/platforms/python/configuration/options/#max-request-body-size). - - - - - -#### Deprecated - -Has been renamed to [include_local_variables](/platforms/python/configuration/options/#include-local-variables). - - - - - -Data to be set to the initial scope. Initial scope can be defined either as an object or a callback function, as shown below. - -Object: - - - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - debug: true, - initialScope: { - tags: { "my-tag": "my value" }, - user: { id: 42, email: "john.doe@example.com" }, - }, -}); -``` - -Callback function: - -```javascript -Sentry.init({ - dsn: "___PUBLIC_DSN___", - debug: true, - initialScope: (scope) => { - scope.setTags({ a: "b" }); - return scope; - }, -}); -``` - - - - - -A block that configures the initial scope when starting the SDK. - - - -```swift -import Sentry - -SentrySDK.start { options in - options.dsn = "___PUBLIC_DSN___" - options.initialScope = { scope in - scope.setTag(value: "my value", key: "my-tag") - return scope - } -} -``` - -```objc {tabTitle:Objective-C} -@import Sentry; - -[SentrySDK startWithConfigureOptions:^(SentryOptions *options) { - options.dsn = @"___PUBLIC_DSN___"; - options.initialScope = ^(SentryScope *scope) { - scope setTagValue:@"my value" forKey:@"my-tag"]; - return scope; - }; -}]; -``` - -_(New in [sentry-cocoa version 8.7.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#870))_ - - - - - -Maximum number of characters a single value can have before it will be truncated (defaults to `250`). - - - - +## Hooks -Sentry SDKs normalize any contextual data to a given depth. Any data beyond this depth will be trimmed and marked using its type instead (`[Object]` or `[Array]`), without walking the tree any further. By default, walking is performed three levels deep. +These options can be used to hook the SDK in various ways to customize the reporting of events. - + - +This function is called with an SDK-specific message or error event object, and can return a modified event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending. -This is the maximum number of properties or entries that will be included in any given object or array when the SDK is normalizing contextual data. Any data beyond this depth will be dropped. (defaults to 1000) +By the time is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect. - - -Takes a screenshot of the application when an error happens and includes it as an attachment. -Learn more about enriching events with screenshots in our Screenshots documentation. - - - -_(New in version 4.11.0)_ + - - - - -_(New in version 6.0.0)_ - - +This function is called with a backend-specific event object, and can return a modified event object or nothing to skip reporting the event. In contrast to `before_send`, it is only called when a crash occurred. You can find detailed information concerning its usage in [Filtering](/platforms/native/configuration/filtering/#using-on_crash). - - -The quality of the attached screenshot. It can be set to `full`, `high`, `medium` or `low`. - - +## Tracing Options - + -Renders a JSON representation of the entire view hierarchy of the application when an error happens and includes it as an attachment. -Learn more about enriching events with the view hierarchy in our View Hierarchy documentation. +A number between `0.0` and `1.0`, controlling the percentage chance a given transaction will be sent to Sentry. (`0.0` represents 0% while `1.0` represents 100%.) Applies equally to all transactions created in the app. Either this or must be defined to enable tracing. - - - -The idle time, measured in ms, to wait until a transaction will be automatically finished. The transaction will use the end timestamp of the last finished span as the endtime for the transaction. - -The default is `3000`. - - - -_(New in version 6.0.0)_ - - - -This only affects [user interaction transactions](/platforms/android/performance/instrumentation/automatic-instrumentation/#user-interaction-instrumentation). - - - - - - - - - - - -Inter-process communication mode to receive event and scope updates from renderer processes. - -Available options are: - -- `IPCMode.Classic` - Configures Electron IPC modules -- `IPCMode.Protocol` - Configures a custom protocol and `fetch` -- `IPCMode.Both` (default) - Configures both modes for maximum compatibility - - - -A function that returns an array of Electron `session` objects. These sessions are used to configure communication between the Electron main and renderer processes. - -Defaults to `() => [session.defaultSession]` - - - -Callback function that allows custom naming of renderer processes. - -`(contents: WebContents) => string | undefined` - -If the callback is not set, or it returns `undefined`, the default naming scheme is used. - - - - - -Specifies whether this SDK should send events to Sentry. Defaults to `true`. Setting this to `enabled: false` doesn't prevent all overhead from Sentry instrumentation. To disable Sentry completely, depending on environment, call `Sentry.init` conditionally. - - - - - -Set this boolean to `false` to disable sending of client reports. Client reports are a protocol feature that let clients send status reports about themselves to Sentry. They are currently mainly used to emit outcomes for events that were never sent. - - - -_(New in version 6.0.0)_ - - - - - -_(New in version 7.13.0)_ - - - - - -_(New in version 6.6.0)_ - - - - - - - -Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. - - - -_(New in version 7.0.0)_ - - - - - - - -Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. - - - -_(New in version 5.3.0)_ - - - - - -_(New in version 7.30.0)_ - - - - - - - -Set this boolean to `true` to add stack local variables to stack traces. - - - -Due to an [open Node.js issue](https://github.com/nodejs/node/issues/38439), we -are currently unable to capture local variables for unhandled errors when using -JavaScript modules (ESM). - -See the integration -options for a workaround. - - - - - - - -## Integration Configuration - -For many platform SDKs integrations can be configured alongside it. On some platforms that happen as part of the `init()` call, in some others, different patterns apply. - - - -In some SDKs, the integrations are configured through this parameter on library initialization. For more information, please see our documentation for a specific integration. - - - -This can be used to disable integrations that are added by default. When set to `false`, no default integrations are added. - - - -This can be used to disable integrations that are enabled by default if the SDK detects that the corresponding framework or library is installed. When set to `false`, none of these integrations will be enabled by default, even if the corresponding framework/library is detected. - - - -## Hooks - -These options can be used to hook the SDK in various ways to customize the reporting of events. - - - -The callbacks you set as hooks will be called on the thread where the event happened. So you can only use -thread-safe APIs and only use Unity-specific APIs after you've checked that you're on the UI thread. - - - - - -This function is called with an SDK-specific message or error event object, and can return a modified event object, or `null` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending. - -By the time is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect. - - - - - -This function is called with an SDK-specific transaction event object, and can return a modified transaction event object, or `null` to skip reporting the event. One way this might be used is for manual PII stripping before sending. - - - - - - - - - -This function is called with a backend-specific event object, and can return a modified event object or nothing to skip reporting the event. In contrast to `before_send`, it is only called when a crash occurred. You can find detailed information concerning its usage in [Filtering](/platforms/native/configuration/filtering/#using-on_crash). - - - - - -This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object. -The callback typically gets a second argument (called a "hint") which contains the original object from which the breadcrumb was created to further customize what the breadcrumb should look like. - - - - - - - -This function is called with an event and the result of sending that event. This is useful to log send results, instrument Sentry calls, and so on. - - - - - - - -## Transport Options - -Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments. - - - -Switches out the transport used to send events. How this works depends on the SDK. It can, for instance, be used to capture events for unit-testing or to send it through some more complex setup that requires proxy authentication. - - - - - -Options used to configure the transport. This is an object with the following possible optional keys: - - - -- `headers`: An object containing headers to be sent with every request. -- `proxy`: A proxy used for outbound requests. Can be http or https. -- `caCerts`: A path or list of paths to a CA certificate, or a buffer of CA certificates. -- `httpModule`: A custom HTTP module to use for requests. Defaults to the the native `http` and `https` modules. -- `keepAlive`: Determines whether to keep the socket alive between requests. Defaults to `false`. - - - - - -- `headers`: An object containing headers to be sent with every request. Used by the SDK's fetch and XHR transports. -- `fetchOptions`: An object containing options to be passed to the `fetch` call. Used by the SDK's fetch transport. - - - - - - - Configures an HTTP proxy for outgoing requests to the backend, (HTTPS requests - tunneled through that proxy). The Native SDK doesn't pick up the `http_proxy` - environment variable. You can find more details on the [transport - page](/platforms/native/configuration/transports/#using-an-http-proxy). - - - - -When set, a proxy can be configured that should be used for outbound requests. This is also used for HTTPS requests unless a separate `https-proxy` is configured. However, not all SDKs support a separate HTTPS proxy. SDKs will attempt to default to the system-wide configured proxy, if possible. For instance, on Unix systems, the `http_proxy` environment variable will be picked up. - - - - - -Configures a separate proxy for outgoing HTTPS requests. This value might not be supported by all SDKs. When not supported the `http-proxy` value is also used for HTTPS requests at all times. - - - - - -A dict containing additional proxy headers (usually for authentication) to be forwarded to `urllib3`'s [`ProxyManager`](https://urllib3.readthedocs.io/en/1.24.3/reference/index.html#urllib3.poolmanager.ProxyManager). - - - - - -Specifies a local directory used for caching payloads. When this option is enabled (that is, when the directory is set), the Sentry SDK will persist envelopes locally before sending to Sentry. This configuration option is particularly useful if you expect your application to run in environments where internet connectivity is limited. - - - - - -Default: set to `android.content.Context.getCacheDir()/sentry`. - - - - - -Default: not set (caching is disabled). - - - - - -The default value is `Application.persistentDataPath`. You can disable offline caching by setting it to `null`. - - - - - -The default value is `Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)`. - - - - - -The default value is `Path.Combine(FileSystem.CacheDirectory, "sentry")`. See the [Microsoft docs](https://docs.microsoft.com/dotnet/maui/platform-integration/storage/file-system-helpers#platform-differences) for how `FileSystem.CacheDirectory` differs on each supported platform. - - - - - -When caching is enabled (that is, is set), this option controls the timeout that limits how long the SDK will attempt to flush existing cache during initialization. Note that flushing the cache involves sending the payload to Sentry in a blocking operation. Setting this option to zero means that Sentry will **not** attempt to flush the cache during initialization, but instead will do so when the next payload is queued up. - -The default is `1` (one) second. - - - - - -Controls how many seconds to wait before shutting down. Sentry SDKs send events from a background queue. This queue is given a certain amount to drain pending events. The default is SDK specific but typically around two seconds. Setting this value too low may cause problems for sending events from command line applications. Setting the value too high will cause the application to block for a long time for users experiencing network connectivity problems. - - - - - -_Deprecated._ Controls how many times the SDK will attempt to resend an event to Sentry. The default is `0`. - - - - - -The maximum number of seconds to wait while trying to connect to a server. The default is `2`. - - - - - -The maximum execution time, in seconds, for the request+response as a whole. The value should also include the time for the connect phase, so it should be greater than the value set for the `http_connect_timeout` option. The default is `5`. - - - - - - - - - -Controls whether to report events to Sentry _synchronously_ (if set to `:sync`) or _asynchronously_ (if set to `:none`). Defaults to `:none`. - - - - - -The maximum number of attempts to send an event to Sentry. Defaults to `4`. - - - - - -The HTTP client to use for sending events to Sentry. This must be a module that implements the [`Sentry.HTTPClient`](https://hexdocs.pm/sentry/Sentry.HTTPClient.html) behaviour. Defaults to `Sentry.HackneyClient`, which is based on the [Hackney](https://hexdocs.pm/hackney) HTTP client. - - - - - -Options to be passed to Hackney. Only applied if `client` is set to `Sentry.HackneyClient`. Defaults to `[pool: :sentry_pool]`. - - - - - -The maximum number of connections to keep in the pool. Only applied if `client` is set to `Sentry.HackneyClient`. Defaults to `50`. - - - - - -The maximum time to wait (in milliseconds) for a connection to become available. Only applied if `client` is set to `Sentry.HackneyClient`. Defaults to `5000`. - - - - - - - -## Tracing Options - - - -A boolean value, if true, transactions and trace data will be generated and captured. This will set the `traces-sample-rate` to the recommended default of 1.0 if `traces-sample-rate` is not defined. Note that `traces-sample-rate` and `traces-sampler` take precedence over this option. - - - - - -A number between 0 and 1, controlling the percentage chance a given transaction will be sent to Sentry. (0 represents 0% while 1 represents 100%.) Applies equally to all transactions created in the app. Either this or must be defined to enable tracing. - - -If is 0, this means that no new traces will be created. However, if you have another service (for example a JS frontend) that makes requests to your service that include trace information, those traces will be continued and thus transactions will be sent to Sentry. - -If you want to disable all tracing you need to set `=None` or set `=False`. In this case, no new traces will be started and no incoming traces will be continued. - - - - - - - -A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or must be defined to enable tracing. - - - - - -An optional property that configures which downstream services receive the `sentry-trace` header attached to HTTP requests. It contains a list of URLs or regex against which URLs are matched. If not set, the `sentry-trace` header is attached to every request executed from an instrumented client. - - - - - -An optional property that controls which downstream services receive tracing data, in the form of a `sentry-trace` and a `baggage` header attached to any outgoing HTTP requests. - -The option may contain a list of strings or regex against which the URLs of outgoing requests are matched. -If one of the entries in the list matches the URL of an outgoing request, trace data will be attached to that request. -String entries do not have to be full matches, meaning the URL of a request is matched when it _contains_ a string provided through the option. - -If is not provided, trace data is attached to every outgoing request from the instrumented client. - - - - - -An optional list of functions that should be set up for performance monitoring. For each function in the list, a span will be created when the function is executed. -Functions in the list are represented as strings containing the fully qualified name of the function. - -This is a convenient option, making it possible to have one central place for configuring what functions to trace, instead of having custom instrumentation scattered all over your code base. - -To learn more, see the [Custom Instrumentation](/platforms/python/performance/instrumentation/custom-instrumentation/#define-span-creation-in-a-central-place) documentation. - - - - - -When enabled, a new monitor thread will be spawned to perform health checks on the SDK. If the system is unhealthy, the SDK will keep halving the `traces_sample_rate` set by you in 10 second intervals until recovery. This downsampling helps ensure that the system stays stable and reduces SDK overhead under high load. - -This option is enabled by default. - - - - - -When enabled, the source location will be added to database queries. - -This option is disabled by default. - - - - - -The threshold in milliseconds for adding the source location to database queries. The query location will be added to the query for queries slower than the specified threshold. - -You need to set `enable_db_query_source` to `True` for this to work. - -Default is `100` ms. - - - - - - - -Set this boolean to `false` to disable tracing for `OPTIONS` requests. This options default value will likely be changed in the next major version, meaning you will have to set it to `true` if you want to keep tracing `OPTIONS` requests. - - - - - - - - - -## Experimental Features - - - -An optional property that configures which features are in experimental mode. This property is either an `Object Type` with properties or a key/value `TypedDict`, depending the language. Experimental features are still in-progress and may have bugs. We recognize the irony. - - - -## Hybrid SDK Options - - - -Set this boolean to `false` to disable the native SDK. This will disable all native crash and error handling and, instead, the SDK will only capture errors on the upper layer. - - - - - -Set this boolean to `false` to disable the auto initialization of the native layer SDK. Doing so means you will need to initialize the native SDK manually. Do not use this to disable the native layer. - - - -To disable the native layer, use [enableNative](#enableNative). - -You should follow the [guide to native initialization](/platforms/react-native/manual-setup/native-init/) if you chose to use this option. - - - - - -You should follow the [guide to native initialization](/platforms/flutter/native-init/) if you chose to use this option. - - - - - - - -Set this boolean to `false` to disable hard crash handling from the native layer. Doing so means that the SDK won't capture events for hard crashes on Android and iOS if the error was caused by native code. - - - - - -Set this boolean to `false` to disable the native nagger alert being shown. - - - - - -Set this boolean to `false` to disable the [release health](/product/releases/health/) feature. - - - - - -Set this to change the default interval to end a session (release health) if the app goes to the background. Default is 30,000. - - - - - -Set this boolean to `false` to disable the scope sync from Java to NDK on Android. - - - - - -Set this boolean to `true` to automatically attach all threads to all logged events on Android. - - - - - -Set this boolean to `false` to disable auto [performance monitoring](/product/performance/) tracking. - - - - - - - -Set this boolean to `false` to disable auto [performance monitoring](/product/performance/) tracking. - - - - - - - -Set this boolean to `false` to disable [out of memory](/platforms/apple/guides/ios/configuration/out-of-memory/) tracking on iOS. - - - - - - - Available since version 8.0.0 of Sentry Apple SDK. It was named - `enableOutOfMemoryTracking` before the 8.0.0 release. - - -Set this boolean to `false` to disable [watchdog termination](/platforms/apple/guides/ios/configuration/watchdog-terminations/) tracking on iOS. - - - - - -Set this callback, which is called after the Sentry React Native SDK initializes its Native SDKs (Android and iOS). - - - - - -Set this boolean to `false` to disable sync of `Scope` data to Android and iOS SDKs. - - - - - -Set this boolean to `false` to disable reporting all the package dependencies. - - - - - -Set this boolean to `true` to enable ANR (Application Not Responding) detection on Android. - - - - - -Set this to change the default interval of the ANR detection. The default is `5` seconds. - - - - - -Set this boolean to `true` to enable reporting [FlutterErrorDetails.silent](https://api.flutter.dev/flutter/foundation/FlutterErrorDetails/silent.html) errors automatically. - - - - - -Set this boolean to `false` to disable automatic app start tracking. - - - - - -Set this boolean to `false` to disable automatic breadcrumbs on the Native platforms. - - - - - -Set this boolean to `false` to disable automatic User Interactions breadcrumbs. - - - - - -Set this boolean to `false` to disable automatic User Interactions tracing. - - - - - -Sets the Proguard UUID for Android platform - - - - diff --git a/src/platforms/native/common/configuration/releases.mdx b/src/platforms/native/common/configuration/releases.mdx index c0f624f1db625..9452a9f9a258a 100644 --- a/src/platforms/native/common/configuration/releases.mdx +++ b/src/platforms/native/common/configuration/releases.mdx @@ -1,19 +1,9 @@ --- title: Releases & Health -sidebar_order: 40 description: "Learn how to configure your SDK to tell Sentry about your releases." +sidebar_order: 40 --- - - - - -The Crash Free Session Rate requires [native support](/platforms/unity/native-support/). On platforms that don't yet have native support, the SDK reports sessions that did not end gracefully as _Abnormal_, which leads to 100% crash free sessions being recorded. If you're building on a platform that doesn't have native support yet, you should monitor your app's _Abnormal_ rate. - - - - - A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you can: - Determine issues and regressions introduced in a new release @@ -21,12 +11,6 @@ A release is a version of your code that is deployed to an - -Additionally, releases are used for applying [source maps](/platforms/javascript/sourcemaps/) to minified JavaScript to view original, untransformed source code. - - - ## Bind the Version Include a release ID (often called a "version") when you initialize the SDK. @@ -74,8 +58,6 @@ If you don't tell Sentry about a new release, Sentry will automatically create a After configuring your SDK, you can install a repository integration or manually supply Sentry with your own commit metadata. Read our documentation about [setting up releases](/product/releases/setup/) for further information about integrations, associating commits, and telling Sentry when deploying releases. - - ## Release Health Monitor the [health of releases](/product/releases/health/) by observing user adoption, usage of the application, percentage of [crashes](/product/releases/health/#crash), and [session data](/product/releases/health/#session). Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the [Release Details](/product/releases/release-details/) graphs and filters. @@ -92,21 +74,4 @@ In order to monitor release health, the SDK sends session data. A session represents the interaction between the user and the application. Sessions contain a timestamp, a status (if the session was OK or if it crashed), and are always linked to a release. Most Sentry SDKs can manage sessions automatically. - - - - - - - - - -Release health support for .NET is currently limited to single-instance **client** applications only. This means it can be used with WPF, Xamarin, WinForms and similar app models. -Support for server frameworks such as ASP.NET is planned. - - - - - - diff --git a/src/platforms/native/common/configuration/sampling.mdx b/src/platforms/native/common/configuration/sampling.mdx index 6c2d3b831dcae..9e85b364c32be 100644 --- a/src/platforms/native/common/configuration/sampling.mdx +++ b/src/platforms/native/common/configuration/sampling.mdx @@ -1,28 +1,7 @@ --- title: Sampling -sidebar_title: Sampling -sidebar_order: 50 description: "Learn how to configure the volume of error and transaction events sent to Sentry." -supported: - - javascript - - node - - python - - php - - java - - ruby - - go - - react-native - - android - - dotnet - - apple - - javascript.cordova - - unity - - dart - - flutter - - rust - - native -redirect_from: - - /performance/sampling/ +sidebar_order: 50 --- Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. @@ -41,35 +20,6 @@ Changing the error sample rate requires re-deployment. In addition, setting an S - - -### Dynamically Sampling Error Events - -To sample error events dynamically, set the to a function that returns the desired sample rate for the event. The takes two arguments, and , which it uses to inform the sampling decision. - - - -Your function **must return a valid value**. A valid value is either: - -- A **floating-point number** between `0.0` and `1.0` (inclusive) indicating the probability an error gets sampled, **or** -- A **boolean** indicating whether or not to sample the error. - - - -One potential use case for the is to apply different sample rates for different exception types. For instance, if you would like to sample some exception called `MyException` at 50%, discard all events of another exception called `MyIgnoredException`, and sample all other exception types at 100%, you could use the following code when initializing the SDK: - - - - - -You can define at most one of the and the . If both are set, the will control sampling, and the will be ignored. - - - - - - - ## Sampling Transaction Events We recommend sampling your transactions for two reasons: @@ -96,58 +46,22 @@ The Sentry SDKs have two configuration options to control the volume of transact By default, none of these options are set, meaning no transactions will be sent to Sentry. You must set either one of the options to start sending transactions. - - Sampling functions () are currently not supported by this platform. - - ### Setting a Uniform Sample Rate - - -### Setting a Sampling Function - - - -## Sampling Context Data - -### Default Sampling Context Data - -The information contained in the object passed to the when a transaction is created varies by platform and integration. - - - -### Custom Sampling Context Data - -When using custom instrumentation to create a transaction, you can add data to the by passing it as an optional second argument to . This is useful if there's data to which you want the sampler to have access but which you don't want to attach to the transaction as `tags` or `data`, such as information that's sensitive or that’s too large to send with the transaction. For example: - - - - - ## Inheritance Whatever a transaction's sampling decision, that decision will be passed to its child spans and from there to any transactions they subsequently cause in other services. - - -(See Distributed Tracing for more about how that propagation is done.) - - - - - (See Distributed Tracing for more about how that propagation is done.) - - If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. @@ -158,16 +72,6 @@ In some SDKs, for convenience, the If you're using a rather than a , the decision will always be inherited. - - -## Forcing a Sampling Decision - -If you know at transaction creation time whether or not you want the transaction sent to Sentry, you also have the option of passing a sampling decision directly to the transaction constructor (note, not in the object). If you do that, the transaction won't be subject to the , nor will be run, so you can count on the decision that's passed not to be overwritten. - - - - - ## Precedence There are multiple ways for a transaction to end up with a sampling decision. @@ -185,14 +89,8 @@ When there's the potential for more than one of these to come into play, the fol 1. If is not defined, but there's a parent sampling decision, the parent sampling decision will be used. 1. If is not defined and there's no parent sampling decision, will be used. - - Forcing a sampling decision by passing it into is currently not supported by this platform. - - - - diff --git a/src/platforms/native/common/data-management/debug-files/file-formats/index.mdx b/src/platforms/native/common/data-management/debug-files/file-formats/index.mdx index 8b019342fc86b..9eb297cc2a983 100644 --- a/src/platforms/native/common/data-management/debug-files/file-formats/index.mdx +++ b/src/platforms/native/common/data-management/debug-files/file-formats/index.mdx @@ -42,136 +42,10 @@ Still, it is always a good idea to provide all available debug information. `sentry-cli` can be used to list properties of supported debug files and validate their contents. See [_Debug Information Files in sentry-cli_](/product/cli/dif/) for more information. - - -## Mach-O and dSYM - -Executables, dynamic libraries and debug companions on all Apple platforms use -the _Mach Object_, or short _Mach-O_, container format. This applies to iOS, -iPadOS, tvOS, watchOS, macOS, and visionOS. - -- **Executables** do not carry a file extension. For desktop applications, they - are often placed in app bundle structures with the `.app` suffix. Unless - stripped manually, executables contain unwind information and a symbol table. - Debug information is never stored in executables. - -- **Dynamic Libraries** use the `.dylib` extension, and otherwise behave exactly - the same as executables. - -- **Debug Companions** are placed in a folder structure with the `.dSYM` - extension, and are located at `.dSYM/Contents/Resources/DWARF/`. - They usually contain a symbol table and debug information, but rarely unwind - information. - -When building an application with Xcode or with the `clang` compiler, debug -information is automatically placed in a dSYM file. When linking manually, -however, the dSYM file must be created using the following command: - -```bash -dsymutil /path/to/output[.dylib] -``` - -## Executable and Linkable Format (ELF) - -On Linux distributions, executables and debug information are stored in _ELF_ -containers. Unlike other platforms, there is no dedicated container or specifier -for debug companion files. - -Debug information is part of the binary (executable or library) and stripped -when generating release builds due to their size. However, there is a way to -retain them in a separate file (either in a different location or with `.debug` -extension): - -```bash -# There is an executable called "binary" in the CWD -objcopy --only-keep-debug binary binary.debug -objcopy --strip-debug --strip-unneeded binary -objcopy --add-gnu-debuglink=binary.debug binary -``` - -This results in the following structure: - -- **Executables** do not carry a file extension. If stripped like above, - executables contain a symbol table, but no debug information. If the build - run omits frame pointers, unwind information will also be retained. Both can - be further stripped using flags like `--strip-all`. - -- **Shared Libraries** use the `.so` extension, and otherwise behave exactly - the same as executables. - -- **Debug Companions** do not carry a standard file extension, but are often - named `.debug`. If stripped like above, these files contain unwind - information, debug information and a symbol table. - -Shared libraries installed via package managers usually provide their debugging -information in separate `*-dev` packages and put it in locations like -`/usr/local/debug/...`. To receive symbolicated stack traces from those -libraries, make sure to also upload their symbols in addition to your app’s -symbols. - -ELF supports the compression of debug information which can significantly reduce -the time required to upload debug information files to Sentry and thus improve -build times. `gcc` (version 5 or newer) and `clang` (version 5 or newer) support -this by passing the `-gz` flag to both the compiler and linker. The common way -to compress debug information, however, is when stripping the executable: - -```bash -# Note the --compress-debug-sections option -objcopy --only-keep-debug --compress-debug-sections=zlib binary binary.debug -``` - -This can be verified by checking for the `C` flag in `readelf`, corresponding to -`SHF_COMPRESSED`: - -```bash -readelf -S path/to/file - ... - [21] .debug_info PROGBITS 0000000000000000 00000370 - 000000000000e133 0000000000000000 C 0 0 1 -``` - -## PE and PDB - -Executables and dynamic libraries on Microsoft Windows, and those created by the -.NET platform on all operating systems, use the _Portable Executable_ (_PE_) -container format. Associated debug information is stored in _Program Database_ -(_PDB_) files. - -- **Executables** use an `.exe` file extension. Only when compiled for 64-bit - architectures, they contain unwind information. Otherwise, they do not contain - any usable information and will be omitted for the upload to Sentry. - -- **Dynamic Libraries** use the `.dll` file extension, and otherwise behave - exactly the same as executables. - -- **Debug Companions** are stored in `.pdb` files. They usually contain debug - information and in most cases symbol tables. For 32-bit programs, they also - contain unwind information. In rare cases, they might have different file - names than their corresponding executable. - -- The .NET platform uses a variation of this format, called [Portable PDBs](https://github.com/dotnet/core/blob/main/Documentation/diagnostics/portable_pdb.md). - Portable PDBs are supported as of Sentry 22.11.0 (or Sentry CLI 2.8.0, or Symbolic 10.0.0). - -## Breakpad Symbols - -The Google Breakpad library has established a platform-independent ASCII format -to store debug information. Such files are usually generated for applications -using Breakpad, Crashpad, or the Electron Framework. - -The Breakpad repository includes `dump_syms` tools for each platform that can -convert from native debug files to Breakpad symbols. These converters bundle all -available information into one file, such that only one file needs to be -uploaded. - -In contrast to native debug files, Breakpad symbols discard a lot of information -that is not required to process minidumps. Most notably, inline functions are -not declared, such that Sentry is not able to display inline frames in stack -traces. + ## WASM - - For WebAssembly, we support [DWARF in WASM containers](https://yurydelendik.github.io/webassembly-dwarf/). Note that we do not support source maps, which are also a format used for WASM debugging, but have shortcomings that make them impractical for a crash reporting @@ -182,20 +56,4 @@ add build IDs and split files called [wasm-split](https://github.com/getsentry/s to help you create a debug companion file ready for uploading to Sentry while removing all debug information from the release binary. - - -## ProGuard Mappings - - - - -The recommended method for [Android users is to use the Gradle plugin](/platforms/android/configuration/gradle/). - - - - -ProGuard mapping files allow Sentry to resolve obfuscated Java classpaths and -method names into their original form. In that sense, they act as debug -information files for Java and Android applications. - - + diff --git a/src/platforms/native/common/data-management/debug-files/identifiers/index.mdx b/src/platforms/native/common/data-management/debug-files/identifiers/index.mdx index 046a8f3403240..b59fa2955eb22 100644 --- a/src/platforms/native/common/data-management/debug-files/identifiers/index.mdx +++ b/src/platforms/native/common/data-management/debug-files/identifiers/index.mdx @@ -41,48 +41,9 @@ files that match it in the _Debug Files_ settings screen. `sentry-cli` can help to print properties of debug information files like their debug identifier. See [_Checking Debug Information Files_](/product/cli/dif/#checking-files) for more information. - + -## GNU Build Identifiers - -For ELF files on Linux, Sentry uses the GNU build identifier to compute the -debug identifier. All recent compilers and linkers support the emission of build -IDs, but sometimes they might require additional configuration. `gcc` does this -by default, for `clang` use one of the following flags: - -- `--build-id=uuid` for a fast but non-reproducible random identifier. -- `--build-id=sha1` for a slower but reproducible identifier generated by - hashing the first page of the code section. - -_The identifier needs to be present and identical in the binary as well -as stripped debug information files._ If the ID is missing for some reason, -upload the files before stripping so that `sentry-cli` can compute a stable -identifier from the unstripped file. - -## PDB Age Mismatches - -Microsoft PDBs compose their identifiers from two parts: A unique signature and -an age field. The signature is generated when the PDB is written initially and -usually changes with every build. The age is a counter that is incremented every -time the PDB is modified. - -PE files, such as executables and dynamic libraries, specify the full identifier -of the corresponding PDB in their header. This includes the age. If the PDB is -modified after the PE has been generated, however, its age might diverge. This -can lead to different identifiers: - -``` -PE: 3003763b-afcb-4a97-aae3-28de8f188d7c-2 -PDB: 3003763b-afcb-4a97-aae3-28de8f188d7c-4 -``` - -`sentry-cli` can detect these differences during the upload process and -associates the same identifier to both files. However, this requires that both -files are uploaded in the same invocation of the upload command. Otherwise, the -identifiers diverge and Sentry might not be able to resolve the correct file -for symbolication. - - + ## WASM Build IDs @@ -95,26 +56,4 @@ Our recommendation is to embed a UUID in the `build_id` custom section as raw binary. Our [`wasm-split`](https://github.com/getsentry/symbolicator/tree/master/crates/wasm-split) tool can do this for you automatically. - - -## ProGuard UUIDs - -Unlike other debug information files, ProGuard files do not have an intrinsic -unique identifier. Sentry CLI assigns them a SHA1 UUID based on the checksum of -the file. You can use `sentry-cli debug-files check` on a ProGuard file to see the -generated UUID. - -If you need to generate the UUID yourself, you can do so with the following -algorithm (Python code for reference): - -```python -import uuid - -NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, "guardsquare.com") - -def get_proguard_uuid(filename): - with open(filename, 'rb') as f: - return uuid.uuid5(NAMESPACE, f.read()) -``` - - + diff --git a/src/platforms/native/common/data-management/debug-files/index.mdx b/src/platforms/native/common/data-management/debug-files/index.mdx index e1faa24c06079..a3a2f4e61b28f 100644 --- a/src/platforms/native/common/data-management/debug-files/index.mdx +++ b/src/platforms/native/common/data-management/debug-files/index.mdx @@ -2,19 +2,6 @@ title: "Debug Information Files" description: "Learn about how debug information files allow Sentry to extract stack traces and provide more information about crash reports for most compiled platforms." sidebar_order: 200 -redirect_from: - - /workflow/debug-files/ -supported: - - native - - android - - cocoa - - javascript.capacitor - - apple - - unity - - unreal - - dotnet - - flutter - - react-native --- Debug information files allow Sentry to extract stack traces and provide more @@ -23,23 +10,7 @@ in debug files includes original function names, paths to source files and line numbers, source code context, or the placement of variables in memory. Sentry can use some of this information and display it on the issue details page. - - -Each major platform uses different debug information files. We currently support -the following formats: - -- [_dSYM files_](./file-formats/#mach-o-and-dsym) for iOS, iPadOS, - tvOS, watchOS, macOS, and visionOS -- [_ELF symbols_](./file-formats/#executable-and-linkable-format-elf) for Linux and - Android (NDK) -- [_PDB files_](./file-formats/#pe-and-pdb) for Windows and .NET -- [_Breakpad symbols_](./file-formats/#breakpad-symbols) for all - platforms -- [_WASM files_](./file-formats/#wasm) for WebAssembly -- [_ProGuard mappings_](./file-formats/#proguard-mappings) for - Java and Android - - + diff --git a/src/platforms/native/common/data-management/debug-files/source-context/index.mdx b/src/platforms/native/common/data-management/debug-files/source-context/index.mdx index 6837281d75e7b..cbd8ac2e74e9b 100644 --- a/src/platforms/native/common/data-management/debug-files/source-context/index.mdx +++ b/src/platforms/native/common/data-management/debug-files/source-context/index.mdx @@ -24,63 +24,6 @@ needs to be uploaded alongside the debug information files. The recommended way to do this is by using `sentry-cli`. See [Creating Source Bundles](/product/cli/dif/#creating-source-bundles) for more information. - - - - - - -For .NET projects, you can [configure MSBuild](../../../configuration/msbuild/) to -call `sentry-cli` automatically. Enable the `SentryUploadSources` property to -create and upload source bundles automatically while uploading symbols. - - - -Alternatively, you can embedded source code directly into .NET Portable PDB files by using the -[`EmbedAllSources`](https://github.com/dotnet/sourcelink/blob/main/docs/README.md#embedallsources) -property in your project file. After the PDBs have been uploaded to Sentry, the sources will be -extracted from them automatically. - -Also note that the similar `EmbedUntrackedSources` option is not yet supported, but may be added -in the future. Referer to [this issue](https://github.com/getsentry/symbolic/issues/735) for details. - - - - - - - - - -For Flutter Android, iOS, and macOS, follow the instructions in the [Debug Symbols](/platforms/flutter/upload-debug/#uploading-source-code-context-for-flutter-android-ios-and-macos) guide. - - - - - - - -To get source context for your Apple project, follow the instructions in the [Uploading Debug Symbols](/platforms/apple/sourcecontext) guide. - - - - - -To get source context for React Native JavaScript code, follow the instructions in the [Source Maps](/platforms/react-native/sourcemaps/) guide. -For native Android and iOS code, follow the instructions in the [Debug Symbols](/platforms/react-native/upload-debug/) guide. - - - - - - - -For Android, follow the instructions in the [Android Source Context](/platforms/android/enhance-errors/source-context) guide. - - - - - After they've been uploaded you can review and manage source bundles the same as any other debug information file. See [Managing Debug Information Files](../#managing-debug-information-files). Source bundles will be tagged with `sources`, and will carry the same filename as the diff --git a/src/platforms/native/common/data-management/debug-files/upload/index.mdx b/src/platforms/native/common/data-management/debug-files/upload/index.mdx index 569a369364761..cd1f15f769c2f 100644 --- a/src/platforms/native/common/data-management/debug-files/upload/index.mdx +++ b/src/platforms/native/common/data-management/debug-files/upload/index.mdx @@ -4,15 +4,6 @@ description: "Learn about uploading debug information files to Sentry." sidebar_order: 3 --- - - - -The Sentry SDK for Unity automatically uploads debug files at build time. That means you don't need to use `sentry-cli` directly. -You can find more information about this in the [Unity native support documentation](/platforms/unity/native-support/). - - - - The most straightforward way to provide Sentry with debug information file is to upload them using `sentry-cli`. Depending on your workflow, you may want to upload as part of your build pipeline or when deploying and publishing your @@ -20,25 +11,6 @@ application: ![](debug-files-workflow.png) - - - -Depending on application type, target platform, and build configuration, the -Sentry support for .NET may require uploading debug files in order to show a -complete stack trace including file names and line numbers. This is especially -true for mobile apps targeting Android or iOS, such as those developed with -.NET MAUI. - -To make this easier, the `Sentry` NuGet package (as of version 3.26.1) includes -the Sentry CLI as a bundled tool, and will invoke it when building -your project if the msbuild property `SentryUploadSymbols` is set to true (default to false). -Refer to [msbuild configuration](/platforms/dotnet/configuration/msbuild) for details. - -The remaining information on this page describes invoking the Sentry CLI manually. - - - - Files can be uploaded using the `debug-files upload` command. This command will scan a diff --git a/src/platforms/native/common/data-management/sensitive-data/index.mdx b/src/platforms/native/common/data-management/sensitive-data/index.mdx index 758520870265a..e7995b1bfe39e 100644 --- a/src/platforms/native/common/data-management/sensitive-data/index.mdx +++ b/src/platforms/native/common/data-management/sensitive-data/index.mdx @@ -7,8 +7,6 @@ keywords: - gdpr - "personally identifiable data" - compliance -redirect_from: - - /learn/sensitive-data/ --- As with any third-party service it's important to understand what data is being sent to Sentry, and where relevant ensure sensitive data either never reaches the Sentry servers, or at the very least it doesn’t get stored. @@ -33,76 +31,6 @@ If you are using Sentry in your mobile app, read our [frequently asked questions - + -## Personally Identifiable Information (PII) - -Our newer SDKs do not purposefully send PII to stay on the safe side. This behavior is controlled by an option called [`send-default-pii`](../../configuration/options/#send-default-pii). - -Turning this option on is required for certain features in Sentry to work, but also means you will need to be even more careful about what data is being sent to Sentry (using the options below). - - - - - -If you _do not_ wish to use the default PII behavior, you can also choose to identify users in a more controlled manner, using our [user identity context](../../enriching-events/identify-user/). - - - - - -## Scrubbing Data - - - -### `event_scrubber` - -You can use the configuration parameter to simplify removing sensitive data from your event payload. - - - - - -### & - -SDKs provide a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. Some SDKs also provide a hook which does the same thing for transactions. We recommend using and in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. - - - -Sensitive data may appear in the following areas: - -- Stack-locals → Some SDKs (Python, PHP and Node) will pick up variable values within the stack trace. These can be scrubbed, or this behavior can be disabled altogether if necessary. -- Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. -- User context → Automated behavior is controlled via . -- HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. -- Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. - -For more details and data filtering instructions, see Filtering Events. - -### Examples - -**Contextual information** - -Instead of sending confidential information in plaintext, consider hashing it: - - - -This will allow you to correlate it within internal systems if needed, but keep it confidential from Sentry. - -**User details** - -Your organization may determine that emails are not considered confidential, but if they are, consider instead sending your internal identifier: - - - -Doing this will ensure you still benefit from user-impact related features. - -**Logging integrations** - -As a best practice you should always avoid logging confidential information. If you have legacy systems you need to work around, consider the following: - -- Anonymize the confidential information within the log statements (for example, swap out email addresses -> for internal identifiers) -- Use to filter it out from breadcrumbs before it is attached -- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/breadcrumbs/)) - - + diff --git a/src/platforms/native/common/debug-information.mdx b/src/platforms/native/common/debug-information.mdx index 694476850e5a6..0271f37844971 100644 --- a/src/platforms/native/common/debug-information.mdx +++ b/src/platforms/native/common/debug-information.mdx @@ -15,32 +15,7 @@ libraries. If you are not sure which files are required, go to _Project Settings > Processing Issues_, which shows a list of all the necessary files and instructions to retrieve them. - - -In addition to Debug Information Files, Sentry needs _Call Frame Information_ -(CFI) to extract accurate stack traces from minidumps of optimized release -builds. CFI is usually part of the executables and not copied to debug symbols. -Unless you are uploading Breakpad symbols, be sure to also include the binaries -when uploading files to Sentry. - - - - - -For WASM, you need to provide both the debug information and the original code -in the same debug information file. To do this, we provide a custom -tool called [wasm-split](https://github.com/getsentry/symbolicator/tree/master/crates/wasm-split) -that can do the splitting for you: - -```shell -wasm-split /path/to/file.wasm -d /path/to/file.debug.wasm --strip -``` - -This command modifies the `file.wasm` in place to add the `build_id`, then removes all -debug information. The debug information is put in a `file.debug.wasm` which -then needs to be uploaded to Sentry. - - + For more information on uploading debug information and their supported formats, see [Debug Information Files](../data-management/debug-files/). diff --git a/src/platforms/native/common/enriching-events/tags/index.mdx b/src/platforms/native/common/enriching-events/tags/index.mdx index 991c050477b2c..88da04ff5ed78 100644 --- a/src/platforms/native/common/enriching-events/tags/index.mdx +++ b/src/platforms/native/common/enriching-events/tags/index.mdx @@ -14,11 +14,7 @@ _Tag keys_ have a maximum length of 32 characters and can contain only letters ( _Tag values_ have a maximum length of 200 characters and they cannot contain the newline (`\n`) character. - - -Defining tags is easy, and will bind them to the [current scope](../scopes/) ensuring all future events within scope contain the same tags. - - + Define the tag: diff --git a/src/platforms/native/common/index.mdx b/src/platforms/native/common/index.mdx index 9c9dc4538d5d7..b0d68246f31e1 100644 --- a/src/platforms/native/common/index.mdx +++ b/src/platforms/native/common/index.mdx @@ -2,15 +2,7 @@ On this page, we get you up and running with Sentry's SDK. - - - - -Get started using a guide listed in the right sidebar. - - - - + Don't already have an account and Sentry project established? Head over to [sentry.io](https://sentry.io/signup/), then return to this page.