diff --git a/docs/platforms/python/configuration/draining.mdx b/docs/platforms/python/configuration/draining.mdx index bfc710688e786..14648c8704239 100644 --- a/docs/platforms/python/configuration/draining.mdx +++ b/docs/platforms/python/configuration/draining.mdx @@ -4,8 +4,7 @@ sidebar_order: 80 description: "Learn more about the default behavior of our SDK if the application shuts down unexpectedly." --- -The default behavior of most SDKs is to send out events over the network -asynchronously in the background. This means that some events might be lost if the application shuts down unexpectedly. The SDKs provide mechanisms to cope with this. +By default the SDK sends out events over the network on a background thread. This means that some events might be lost if the application shuts down unexpectedly. The SDK provides mechanisms to cope with this. The Python SDK automatically drains on shutdown unless the `AtexitIntegration` is removed or the `shutdown_timeout` config key is set to 0. If you need to manually drain, the client provides a `close` method: diff --git a/docs/platforms/python/configuration/draining__v1.x.mdx b/docs/platforms/python/configuration/draining__v1.x.mdx index e08e0ead38837..0f2c7470b3006 100644 --- a/docs/platforms/python/configuration/draining__v1.x.mdx +++ b/docs/platforms/python/configuration/draining__v1.x.mdx @@ -4,8 +4,7 @@ sidebar_order: 80 description: "Learn more about the default behavior of our SDK if the application shuts down unexpectedly." --- -The default behavior of most SDKs is to send out events over the network -asynchronously in the background. This means that some events might be lost if the application shuts down unexpectedly. The SDKs provide mechanisms to cope with this. +By default the SDK sends out events over the network on a background thread. This means that some events might be lost if the application shuts down unexpectedly. The SDK provides mechanisms to cope with this. The Python SDK automatically drains on shutdown unless the `AtexitIntegration` is removed or the `shutdown_timeout` config key is set to 0. To manually drain the client provides a `close` method: diff --git a/docs/platforms/python/configuration/filtering/index.mdx b/docs/platforms/python/configuration/filtering/index.mdx index 53bd20ccc230e..c3865d08a9501 100644 --- a/docs/platforms/python/configuration/filtering/index.mdx +++ b/docs/platforms/python/configuration/filtering/index.mdx @@ -62,7 +62,7 @@ Typically, a `hint` holds the original exception so that additional data can be -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). +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, the SDK sends these objects to certain callbacks (, and event processors). ### Using Hints @@ -75,7 +75,7 @@ Event and breadcrumb `hints` are objects containing various information used to 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. +For breadcrumbs, the use of `hints` depends on the type of breadcrumb. For logs, the hint contains the original `logging` log record. diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 6cb5c4fa6cdaa..b2eaebb22e513 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -240,7 +240,7 @@ These options can be used to hook the SDK in various ways to customize the repor -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 function is called with the event payload, and can return a modified event object, or `None` to skip reporting the event. This can be used, for instance, for manual PII stripping before sending. By the time `before_send` is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect. @@ -248,13 +248,13 @@ By the time `before_send` is executed, all scope data has already been applied t -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 transaction event object, and can return a modified transaction event object, or `None` to skip reporting the event. One way this might be used is for manual PII stripping before sending. -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. +This function is called with a 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. @@ -277,7 +277,7 @@ Transports are used to send events to Sentry. Transports can be customized to so -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. +Switches out the transport used to send events. 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. @@ -313,7 +313,7 @@ A dict containing additional proxy headers (usually for authentication) to be fo -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. +Controls how many seconds to wait before shutting down. The SDK sends events from a background queue. This queue is given a certain amount to drain pending events. 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. diff --git a/docs/platforms/python/configuration/sampling.mdx b/docs/platforms/python/configuration/sampling.mdx index 928bfb6e072b8..7c2b691b3f5c7 100644 --- a/docs/platforms/python/configuration/sampling.mdx +++ b/docs/platforms/python/configuration/sampling.mdx @@ -75,7 +75,7 @@ By default, none of these options are set, meaning no transactions will be sent ### Default Sampling Context Data -The information contained in the object passed to the when a transaction is created varies by platform and integration. +The information contained in the object passed to the when a transaction is created varies by integration. diff --git a/docs/platforms/python/configuration/sessions.mdx b/docs/platforms/python/configuration/sessions.mdx index 82032edbd5666..bab570ccc4e03 100644 --- a/docs/platforms/python/configuration/sessions.mdx +++ b/docs/platforms/python/configuration/sessions.mdx @@ -4,7 +4,7 @@ sidebar_order: 50 description: "Learn how to configure your SDK to tell Sentry about users sessions." --- -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. +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. The SDK manages sessions automatically on supported web frameworks. diff --git a/docs/platforms/python/data-management/sensitive-data/index.mdx b/docs/platforms/python/data-management/sensitive-data/index.mdx index cfdd550386895..2a9a54f636b54 100644 --- a/docs/platforms/python/data-management/sensitive-data/index.mdx +++ b/docs/platforms/python/data-management/sensitive-data/index.mdx @@ -19,7 +19,7 @@ These are some great examples for data scrubbing that every company should think We offer the following options depending on your legal and operational needs: -- filtering or scrubbing sensitive data within the SDK, so that data is _not sent to_ Sentry. Different SDKs have different capabilities, and configuration changes require a redeployment of your application. +- filtering or scrubbing sensitive data within the SDK, so that data is _not sent to_ Sentry. Configuration changes require a redeployment of your application. - [configuring server-side scrubbing](/security-legal-pii/scrubbing/server-side-scrubbing/) to ensure Sentry does _not store_ data. Configuration changes are done in the Sentry UI and apply immediately for new events. - [running a local Relay](/product/relay/) on your own server between the SDK and Sentry, so that data is _not sent to_ Sentry while configuration can still be applied without deploying. @@ -27,13 +27,11 @@ We offer the following options depending on your legal and operational needs: Ensure that your team is aware of your company's policy around what can and cannot be sent to Sentry. We recommend determining this policy early in your implementation and communicating it as well as enforcing it via code review. -If you are using Sentry in your mobile app, read our [frequently asked questions about mobile data privacy](/security-legal-pii/security/mobile-privacy/) to assist with Apple App Store and Google Play app privacy details. - ## 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). +The SDK purposefully does not 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). @@ -49,18 +47,18 @@ You can use the configuration param ### & -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. +The SDK provides 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. The SDK also provide a hook which does the same thing for transactions. We recommend using and in the SDK 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. Most SDKs will add the HTTP query string and fragment as a data attribute to the breadcrumb, which may need to be scrubbed. +- Stack-locals → The SDK picks up variable values within the stack trace. These can be scrubbed, or this behavior can be disabled altogether if necessary. +- Breadcrumbs → The SDK picks up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. The SDK will also record database queries, which may need to be scrubbed. The SDK will add the HTTP query string and fragment as a data attribute to the breadcrumb, 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. -- HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. +- HTTP context → Query strings are picked up in web frameworks as part of the HTTP request context. +- Transaction Names → In certain situations, transaction names might contain sensitive data. For example, an HTTP request 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 SDK can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the web framework, your routing configuration, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. +- HTTP Spans → The SDK includes the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. For more details and data filtering instructions, see Filtering Events. @@ -88,4 +86,4 @@ As a best practice you should always avoid logging confidential information. If - 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/)) +- Set the `level` parameter in the logging integrations you use to `None`. diff --git a/docs/platforms/python/enriching-events/breadcrumbs/index.mdx b/docs/platforms/python/enriching-events/breadcrumbs/index.mdx index 0770caef65c39..9ba63f9278681 100644 --- a/docs/platforms/python/enriching-events/breadcrumbs/index.mdx +++ b/docs/platforms/python/enriching-events/breadcrumbs/index.mdx @@ -21,7 +21,7 @@ Manually record a breadcrumb: -The available breadcrumb keys are `type`, `category`, `message`, `level`, `timestamp` (which many SDKs will set automatically for you), and `data`, which is the place to put any additional information you'd like the breadcrumb to include. Using keys other than these six won't cause an error, but will result in the data being dropped when the event is processed by Sentry. +The available breadcrumb keys are `type`, `category`, `message`, `level`, `timestamp` (which defaults to the system's wall-clock time), and `data`, which is the place to put any additional information you'd like the breadcrumb to include. Using keys other than these six won't cause an error, but will result in the data being dropped when the event is processed by Sentry. ## Automatic Breadcrumbs @@ -31,7 +31,7 @@ The available breadcrumb keys are `type`, `category`, `message`, `level`, `times SDKs allow you to customize breadcrumbs through the hook. -This hook is passed an already assembled breadcrumb and, in some SDKs, an optional hint. The function can modify the breadcrumb or decide to discard it entirely by returning `null`: +This hook is passed an already assembled breadcrumb and a `hint` object containing extra metadata. The function can modify the breadcrumb or decide to discard it entirely by returning `None`: diff --git a/docs/platforms/python/enriching-events/context/index.mdx b/docs/platforms/python/enriching-events/context/index.mdx index 36da3d54f7593..e71058c2634d2 100644 --- a/docs/platforms/python/enriching-events/context/index.mdx +++ b/docs/platforms/python/enriching-events/context/index.mdx @@ -29,7 +29,7 @@ Learn more about conventions for common contexts in the [contexts interface deve When sending context, _consider payload size limits_. Sentry does not recommend sending the entire application state and large data blobs in contexts. If you exceed the maximum payload size, Sentry will respond with HTTP error `413 Payload Too Large` and reject the event. -The Sentry SDK will try its best to accommodate the data you send and trim large context payloads. Some SDKs can truncate parts of the event; for more details, see the [developer documentation on SDK data handling](https://develop.sentry.dev/sdk/expected-features/data-handling/). +The Sentry SDK will try its best to accommodate the data you send and trim large context payloads. The SDK can truncate parts of the event; for more details, see the [developer documentation on SDK data handling](https://develop.sentry.dev/sdk/expected-features/data-handling/). ## Additional Data diff --git a/docs/platforms/python/enriching-events/identify-user/index.mdx b/docs/platforms/python/enriching-events/identify-user/index.mdx index 7a264d900126e..2b1810d7b1b48 100644 --- a/docs/platforms/python/enriching-events/identify-user/index.mdx +++ b/docs/platforms/python/enriching-events/identify-user/index.mdx @@ -22,11 +22,9 @@ An alternative, or addition, to the username. Sentry is aware of email addresses ### `ip_address` The user's IP address. If the user is unauthenticated, Sentry uses the IP address as a unique identifier for the user. -Serverside SDKs that instrument incoming requests will attempt to pull the IP address from the HTTP request data (`request.env.REMOTE_ADDR` field in JSON), if available. That might require set to `true` in the SDK options. +The SDK will attempt to pull the IP address from the HTTP request data on incoming requests (`request.env.REMOTE_ADDR` field in JSON), if available. That requires set to `true` in the SDK options. -If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. - -If the field is omitted, the default value is `null`. However, due to backwards compatibility concerns, certain platforms (in particular JavaScript) have a different default value for `"{{auto}}"`. SDKs and other clients should not rely on this behavior and should set IP addresses or `"{{auto}}"` explicitly. +If the user's `ip_address` is set to `"{{auto}}"`, Sentry will infer the IP address from the connection between your app and Sentry's server. If the field is omitted, the default value is `None`. To opt out of storing users' IP addresses in your event data, you can go to your project settings, click on "Security & Privacy", and enable "Prevent Storing of IP Addresses" or use Sentry's [server-side data](/security-legal-pii/scrubbing/) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. diff --git a/docs/platforms/python/enriching-events/scopes/index.mdx b/docs/platforms/python/enriching-events/scopes/index.mdx index 7a04b98a105c9..be42c9ed7253a 100644 --- a/docs/platforms/python/enriching-events/scopes/index.mdx +++ b/docs/platforms/python/enriching-events/scopes/index.mdx @@ -1,6 +1,6 @@ --- title: Scopes -description: "SDKs will typically automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage." +description: "The SDK will in most cases automatically manage the scopes for you in the framework integrations. Learn what a scope is and how you can use it to your advantage." --- Scopes store extra data that the SDK adds to your event when sending the event to Sentry. While the SDKs typically manage the scope automatically, understanding how scopes work and how you can manage them manually can be helpful. diff --git a/docs/platforms/python/tracing/span-metrics/performance-metrics.mdx b/docs/platforms/python/tracing/span-metrics/performance-metrics.mdx index 409c4b778e6d0..3869d416a690e 100644 --- a/docs/platforms/python/tracing/span-metrics/performance-metrics.mdx +++ b/docs/platforms/python/tracing/span-metrics/performance-metrics.mdx @@ -6,7 +6,7 @@ notSupported: - javascript.cordova --- -Sentry's SDKs support sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry. +The SDK supports sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry. ## Custom Measurements diff --git a/docs/platforms/python/usage/index.mdx b/docs/platforms/python/usage/index.mdx index 81fb185015616..d6f8b4e674d6f 100644 --- a/docs/platforms/python/usage/index.mdx +++ b/docs/platforms/python/usage/index.mdx @@ -17,7 +17,7 @@ Key terms: -The most common form of capturing is to capture errors. What can be captured as an error varies by platform. In general, if you have something that looks like an exception, it can be captured. For some SDKs, you can also omit the argument to and Sentry will attempt to capture the current exception. It is also useful for manual reporting of errors or messages to Sentry. +Python exceptions are captured in Sentry. You can omit the argument to and Sentry will attempt to capture the current exception. It is also useful for manual reporting of exceptions or messages to Sentry. While capturing an event, you can also record the breadcrumbs that lead up to that event. Breadcrumbs are different from events: they will not create an event in Sentry, but will be buffered until the next event is sent. Learn more about breadcrumbs in our Breadcrumbs documentation. diff --git a/docs/platforms/python/usage/sdk-fingerprinting/index.mdx b/docs/platforms/python/usage/sdk-fingerprinting/index.mdx index 9bc4a4d4b772c..1ad207b349b4e 100644 --- a/docs/platforms/python/usage/sdk-fingerprinting/index.mdx +++ b/docs/platforms/python/usage/sdk-fingerprinting/index.mdx @@ -11,7 +11,7 @@ By default, Sentry will run one of our built-in grouping algorithms to generate 1. In your SDK, using SDK Fingerprinting, as documented below 2. In your project, using [Fingerprint Rules](/concepts/data-management/event-grouping/fingerprint-rules/) or [Stack Trace Rules](/concepts/data-management/event-grouping/stack-trace-rules/) -In supported SDKs, you can override Sentry's default grouping that passes the fingerprint attribute as an array of strings. The length of a fingerprint's array is not restricted. This works similarly to the [fingerprint rules functionality](/concepts/data-management/event-grouping/fingerprint-rules/), which is always available and can achieve similar results. +You can override Sentry's default grouping that passes the fingerprint attribute as an array of strings. The length of a fingerprint's array is not restricted. This works similarly to the [fingerprint rules functionality](/concepts/data-management/event-grouping/fingerprint-rules/), which can achieve similar results. ## Basic Example diff --git a/platform-includes/configuration/breadcrumb-hints/python.mdx b/platform-includes/configuration/breadcrumb-hints/python.mdx new file mode 100644 index 0000000000000..fe84f55093596 --- /dev/null +++ b/platform-includes/configuration/breadcrumb-hints/python.mdx @@ -0,0 +1,3 @@ +`log_record` + +For breadcrumbs created from logging integrations. The record holds the original console log level and the original input data to the log function. diff --git a/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/python.mdx b/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/python.mdx new file mode 100644 index 0000000000000..6a28a96561ec0 --- /dev/null +++ b/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/python.mdx @@ -0,0 +1,11 @@ +The Python SDK captures breadcrumbs automatically for: + +- Incoming HTTP requests are included in breadcrumbs by default in supported web frameworks. + +- Logs at or above a configured `level` are captured as breadcrumbs when using Python’s built-in logging module or other supported logging integrations. + +- Database queries and Redis commands are added as breadcrumbs for supported libraries. + +- Breadcrumbs are created for Popen subprocesses. + +- Breadcrumbs are made for the start and end of Spark jobs and submission and completion of Spark stages.