diff --git a/docs/platforms/powershell/configuration/draining.mdx b/docs/platforms/powershell/configuration/draining.mdx new file mode 100644 index 0000000000000..7ed1a445a6f2a --- /dev/null +++ b/docs/platforms/powershell/configuration/draining.mdx @@ -0,0 +1,10 @@ +--- +title: Shutdown and Draining +sidebar_order: 70 +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. + + diff --git a/docs/platforms/powershell/configuration/environments.mdx b/docs/platforms/powershell/configuration/environments.mdx new file mode 100644 index 0000000000000..71a8cf9446de3 --- /dev/null +++ b/docs/platforms/powershell/configuration/environments.mdx @@ -0,0 +1,15 @@ +--- +title: Environments +sidebar_order: 30 +description: "Learn how to configure your SDK to tell Sentry about your environments." +--- + +Environments tell you where an error occurred, whether that's in your production system, your staging server, or elsewhere. + +Sentry automatically creates an environment when it receives an event with the `environment` parameter set. + +Environments are case-sensitive. The environment name can't contain newlines, spaces or forward slashes, can't be the string "None", or exceed 64 characters. You can't delete environments, but you can [hide](/product/sentry-basics/environments/#hidden-environments) them. + + + +Environments help you better filter issues, releases, and user feedback in the Issue Details page of sentry.io, which you learn more about in our [documentation that covers using environments](/product/sentry-basics/environments/). diff --git a/docs/platforms/powershell/configuration/filtering.mdx b/docs/platforms/powershell/configuration/filtering.mdx new file mode 100644 index 0000000000000..eea43d4ba860c --- /dev/null +++ b/docs/platforms/powershell/configuration/filtering.mdx @@ -0,0 +1,45 @@ +--- +title: Filtering +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. + +The Sentry SDKs have several configuration options to help you filter out events. + +We also offer [Inbound Filters](/product/data-management-settings/filtering/) to filter events in sentry.io. We recommend filtering at the client level though, because it removes the overhead of sending events you don't actually want. Learn more about the [fields available in an event](https://develop.sentry.dev/sdk/event-payloads/). + +## Filtering Error Events + +Configure your SDK to filter error events by using the callback method and configuring, enabling, or disabling integrations. + +### Using + +All Sentry SDKs support 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/). + +## 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 + + \ No newline at end of file diff --git a/docs/platforms/powershell/configuration/index.mdx b/docs/platforms/powershell/configuration/index.mdx new file mode 100644 index 0000000000000..cff67a5bf5f5c --- /dev/null +++ b/docs/platforms/powershell/configuration/index.mdx @@ -0,0 +1,7 @@ +--- +title: Configuration +description: "Additional configuration options for the SDK." +sidebar_order: 5 +--- + + diff --git a/docs/platforms/powershell/configuration/options.mdx b/docs/platforms/powershell/configuration/options.mdx new file mode 100644 index 0000000000000..ac586cac74ecb --- /dev/null +++ b/docs/platforms/powershell/configuration/options.mdx @@ -0,0 +1,183 @@ +--- +title: Basic Options +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 +initialized. + + + +## Common Options + +The list of common options across SDKs. These work more or less the same in all SDKs, but some subtle differences will exist to better support the platform. Options that can be read from an environment variable (`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`) are read automatically. + + + +The _DSN_ tells the SDK where to send the events. If this value is not provided, the SDK will try to read it from the `SENTRY_DSN` environment variable. If that variable also does not exist, the SDK will just not send any events. + +In runtimes without a process environment (such as the browser) that fallback does not apply. + +Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization). + + + + + +Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications. + +Defaults to `true` for PowerShell. + + + + + +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. + + + + + +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 + + + + + +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 a hash of the script file contents. The dist has a max length of 64 characters. + + + + + +Sets the identifier for the version of the currently running application. 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). + + + + + +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`. + + + + + +Configures the sample rate for error events, in the range of `0.0` to `1.0`. The default is `1.0` which means that 100% of error events are sent. If set to `0.1` only 10% of error events will be sent. Events are picked randomly. + + + + + +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. + +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/). + + + + + +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. + + + +## Hooks + +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. + +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 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. + + + +## 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. + + + + + +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. + + + +## 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. + + + + + +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. + + diff --git a/docs/platforms/powershell/configuration/releases.mdx b/docs/platforms/powershell/configuration/releases.mdx new file mode 100644 index 0000000000000..c0cd837dee5b0 --- /dev/null +++ b/docs/platforms/powershell/configuration/releases.mdx @@ -0,0 +1,77 @@ +--- +title: Releases & Health +description: "Learn how to configure your SDK to tell Sentry about your releases." +sidebar_order: 40 +--- + +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 +- Predict which commit caused an issue and who is likely responsible +- Resolve issues by including the issue number in your commit message +- Receive email notifications when your code gets deployed + +## Bind the Version + +Include a release ID (often called a "version") when you initialize the SDK. + +The release name cannot: + +- contain newlines, tabulator characters, forward slashes(`/`) or back slashes(`\`) +- be (in their entirety) period (`.`), double period (`..`), or space ( ) +- exceed 200 characters + +The value can be arbitrary, but we recommend either of these naming strategies: + +- **Semantic Versioning**: `package@version` or `package@version+build` (for example, `my.project.name@2.3.12+1234`) + - `package` is the unique identifier of the project/app + - `version` is the semver-like structure `...-` + - `build` is the number that identifies an iteration of your app +- **Commit SHA**: If you use a version control system like Git, we recommend using the identifying hash (for example, the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let Sentry CLI automatically determine this hash for supported version control systems. Learn more in our [Sentry CLI](/product/cli/releases/#creating-releases) documentation. + + + +Releases are global per organization; prefix them with something project-specific for easy differentiation. + + + +The behavior of a few features depends on whether a project is using semantic or time-based versioning. + +- Regression detection +- `release:latest` + +We automatically detect whether a project is using semantic or time-based versioning based on: + +- If ≤ 2 releases total: we look at most recent release. +- If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver. +- If 10 or more releases: if any of the most recent 3 releases is semver, and 3 out of the most recent 10 releases is semver, then the project is semver. + +## Setting a Release + + + +How you make the release name (or version) available to your code is up to you. For example, you could use an environment variable that is set during the build process or during initial start-up. + +Setting the release name tags each event with that release name. We recommend that you tell Sentry about a new release before sending events with that release name, as this will unlock a few more features. Learn more in our [Releases](/product/releases/) documentation. + +If you don't tell Sentry about a new release, Sentry will automatically create a release entity in the system the first time it sees an event with that release ID. + +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. + + + +Crash reporting and app hang detection are not available for watchOS. + + + +In order to monitor release health, the SDK sends session data. + +### 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. + + diff --git a/docs/platforms/powershell/configuration/sampling.mdx b/docs/platforms/powershell/configuration/sampling.mdx new file mode 100644 index 0000000000000..2c8aff45559ed --- /dev/null +++ b/docs/platforms/powershell/configuration/sampling.mdx @@ -0,0 +1,102 @@ +--- +title: Sampling +description: "Learn how to configure the volume of error and transaction events sent to Sentry." +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. + +## Sampling Error Events + +To send a representative sample of your errors to Sentry, set the option in your SDK configuration to a number between `0` (0% of errors sent) and `1` (100% of errors sent). This is a static rate, which will apply equally to all errors. For example, to sample 25% of your errors: + + + +The error sample rate defaults to `1`, meaning all errors are sent to Sentry. + + + +Changing the error sample rate requires re-deployment. In addition, setting an SDK sample rate limits visibility into the source of events. Setting a rate limit for your project (which only drops events when volume is high) may better suit your needs. + + + +## Sampling Transaction Events + +We recommend sampling your transactions for two reasons: + +1. Capturing a single trace involves minimal overhead, but capturing traces for _every_ page load or _every_ API request may add an undesirable load to your system. +2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs. + +Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you’re not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume. + +## Configuring the Transaction Sample Rate + +The Sentry SDKs have two configuration options to control the volume of transactions sent to Sentry, allowing you to take a representative sample: + +1. Uniform sample rate (): + + - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur. + - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior + +2. Sampling function () which: + - Samples different transactions at different rates + - Filters out some + transactions entirely + - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior + +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. + +### 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. + +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. + + + +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. + +- Random sampling according to a static sample rate set in +- Random sampling according to a sample function rate returned by +- Absolute decision (100% chance or 0% chance) returned by +- If the transaction has a parent, inheriting its parent's sampling decision +- Absolute decision passed to + +When there's the potential for more than one of these to come into play, the following precedence rules apply: + +1. If a sampling decision is passed to , that decision will be used, overriding everything else. +1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction. We advise against overriding the parent sampling decision because it will break distributed traces) +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. diff --git a/docs/platforms/powershell/data-management/index.mdx b/docs/platforms/powershell/data-management/index.mdx new file mode 100644 index 0000000000000..9150409f3ddf8 --- /dev/null +++ b/docs/platforms/powershell/data-management/index.mdx @@ -0,0 +1,7 @@ +--- +title: Data Management +description: Manage your events by pre-filtering, scrubbing sensitive information, and forwarding them to other systems. +sidebar_order: 4000 +--- + + diff --git a/docs/platforms/powershell/data-management/sensitive-data/index.mdx b/docs/platforms/powershell/data-management/sensitive-data/index.mdx new file mode 100644 index 0000000000000..714f44ce93dcc --- /dev/null +++ b/docs/platforms/powershell/data-management/sensitive-data/index.mdx @@ -0,0 +1,84 @@ +--- +title: "Scrubbing Sensitive Data" +description: "Learn about filtering or scrubbing sensitive data within the SDK, so that data is not sent with the event. You can also configure server-side scrubbing to ensure the data is not stored." +sidebar_order: 100 +keywords: + - pii + - gdpr + - "personally identifiable data" + - compliance +--- + +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. + +These are some great examples for data scrubbing that every company should think about: + +- PII (Personally Identifiable Information) such as a user's name or email address, which post-GDPR should be on every company's mind. +- Authentication credentials, like your AWS password or key. +- Confidential IP (Intellectual Property), such as your favorite color, or your upcoming plans for world domination. + +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. +- [configuring server-side scrubbing](/product/data-management-settings/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. + + + +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](/product/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). + +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 + +### & + +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/docs/platforms/powershell/enriching-events/attachments/index.mdx b/docs/platforms/powershell/enriching-events/attachments/index.mdx new file mode 100644 index 0000000000000..5f8ab1b4494ba --- /dev/null +++ b/docs/platforms/powershell/enriching-events/attachments/index.mdx @@ -0,0 +1,72 @@ +--- +title: Attachments +description: "Learn more about how Sentry can store additional files in the same request as event attachments." +--- + +Sentry can enrich your events for further investigation by storing additional files, such as config or log files, as attachments. + +## Creating Attachments + +The simplest way to create an attachment is to use a `path`. The SDK will read the contents of the file each time it prepares an event or transaction, then adds the attachment to the same [envelope](https://develop.sentry.dev/sdk/envelopes/). If the SDK can't read the file, the SDK logs an error message and drops the attachment. + + + +Alternately, use `bytes` to initialize an attachment. When doing so, you also need to specify a filename. + + + +If your SDK supports offline caching, which is typical for mobile, each attachment is stored to disk for each event or transaction you capture when the device is offline. When using large attachments, this storage can consume the disk space if the device is offline for a longer time period. You can specify [maximum attachment size](#maximum-attachment-size) to drop large attachments and avoid this issue. + +In addition, you can set these parameters: + +`filename` + +The filename is the name of the file to display in Sentry. When using bytes you have to specify a filename, whereas with a path you don't as the SDK is going to use the last path component. + +`contentType` + +The type of content stored in this attachment. Any [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) may be used; the default is `application/octet-stream`. + +## Uploading Attachments + +Attachments live on the Scope. You can either add an attachment on the global scope to be sent with every event or add it on the local Scope to just send the attachment with one specific event. + + + + + +Sentry allows at most 20MB for a compressed request, and at most 100MB of uncompressed attachments per event, including the crash report file (if applicable). Uploads exceeding this size are rejected with HTTP error `413 Payload Too Large` and the data is dropped immediately. To add larger or more files, consider secondary storage options. + + + +Attachments persist for 30 days; if your total storage included in your quota is exceeded, attachments will not be stored. You can delete attachments or their containing events at any time. Deleting an attachment does not affect your quota - Sentry counts an attachment toward your quota as soon as it is stored. + +Learn more about how attachments impact your [quota](/product/accounts/quotas/). + +### Access to Attachments + +To limit access to attachments, navigate to your organization's **General Settings**, then select the _Attachments Access_ dropdown to set appropriate access — any member of your organization, the organization billing owner, member, admin, manager, or owner. + +![Attachments Access](/platforms/dotnet/common/enriching-events/attachments/attachments-access.png) + +By default, access is granted to all members when storage is enabled. If a member does not have access to the project, the ability to download an attachment is not available; the button will be greyed out in Sentry. The member may only view that an attachment is stored. + +## Viewing Attachments + +Attachments display on the bottom of the **Issue Details** page for the event that is shown. + +![Attachments Access Denied](/platforms/dotnet/common/enriching-events/attachments/attachments-access-denied.png) + +Alternately, attachments also appear in the _Attachments_ tab on the **Issue Details** page, where you can view the _Type_ of attachment, as well as associated events. Click the Event ID to open the **Issue Details** of that specific event. + +![Attachments List Example](/platforms/dotnet/common/enriching-events/attachments/attachments-list-example.png) + +## Maximum Attachment Size + +The maximum size for each attachment is set on `SentryOptions.MaxAttachmentSize`. + +The scale is bytes and the default is `20 MiB`. Please also check the +[maximum attachment size of Relay](/product/relay/options/) +to make sure your attachments don't get discarded there. + + diff --git a/docs/platforms/powershell/enriching-events/breadcrumbs/index.mdx b/docs/platforms/powershell/enriching-events/breadcrumbs/index.mdx new file mode 100644 index 0000000000000..dc56402c268f5 --- /dev/null +++ b/docs/platforms/powershell/enriching-events/breadcrumbs/index.mdx @@ -0,0 +1,30 @@ +--- +title: Breadcrumbs +description: "Learn more about what Sentry uses to create a trail of events (breadcrumbs) that happened prior to an issue." +--- + +Sentry uses _breadcrumbs_ to create a trail of events that happened prior to an issue. These events are very similar to traditional logs, but can record more rich structured data. + +This page provides an overview of manual breadcrumb recording and customization. Learn more about the information that displays on the **Issue Details** page and how you can filter breadcrumbs to quickly resolve issues in [Using Breadcrumbs](/product/error-monitoring/breadcrumbs). + + + +Developers who want to modify the breadcrumbs interface can learn more in our [developer documentation about the Breadcrumbs Interface](https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/). + + + +## Manual Breadcrumbs + +You can manually add breadcrumbs whenever something interesting happens. For example, you might manually record a breadcrumb if the user authenticates or another state change occurs. + +Manually record a breadcrumb: + + + +## Customize Breadcrumbs + +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`: + + diff --git a/docs/platforms/powershell/enriching-events/context/index.mdx b/docs/platforms/powershell/enriching-events/context/index.mdx new file mode 100644 index 0000000000000..b8e4cf8329ef3 --- /dev/null +++ b/docs/platforms/powershell/enriching-events/context/index.mdx @@ -0,0 +1,38 @@ +--- +title: Context +description: "Custom contexts allow you to attach arbitrary data (strings, lists, dictionaries) to an event." +--- + +Custom contexts allow you to attach arbitrary data to an event. Often, this context is shared among any issue captured in its lifecycle. You cannot search these, but they are viewable on the issue page: + +![Custom contexts as viewed on the Additional Data section of an event](/platforms/dotnet/common/enriching-events/context/additional_data.png) + + + +If you need to be able to search on custom data, [use tags](../tags) instead. + + + +## Structured Context + +The best way to attach custom data is with a structured context. A context must always be an object and its values can be arbitrary. + +Then, use `Contexts` and give the context a unique name: + + + +There are no restrictions on context name. In the context object, all keys are allowed except for `type`, which is used internally. + +Learn more about conventions for common contexts in the [contexts interface developer documentation](https://develop.sentry.dev/sdk/event-payloads/contexts/). + +## Size Limitations + +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/data-handling/). + +## Additional Data + +**Additional Data is deprecated** in favor of structured contexts. + +Sentry used to support adding unstructured "Additional Data" via . diff --git a/docs/platforms/powershell/enriching-events/identify-user/index.mdx b/docs/platforms/powershell/enriching-events/identify-user/index.mdx new file mode 100644 index 0000000000000..30284c057879a --- /dev/null +++ b/docs/platforms/powershell/enriching-events/identify-user/index.mdx @@ -0,0 +1,49 @@ +--- +title: Users +description: "Learn how to configure the SDK to capture the user and gain critical pieces of information that construct a unique identity in Sentry." +--- + +Users consist of a few critical pieces of information that construct a unique identity in Sentry. Each of these is optional, but one **must** be present for the Sentry SDK to capture the user: + + + +### `id` + + + +If you don't provide an `id`, the SDK falls back to `installationId`, which the SDK randomly generates once during an app's installation. + + + +Your internal identifier for the user. + +### `username` + +The username. Typically used as a better label than the internal id. + +### `email` + +An alternative, or addition, to the username. Sentry is aware of email addresses and can display things such as Gravatars and unlock messaging capabilities. + +### `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. + +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. + +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](/product/data-management-settings/scrubbing/) scrubbing to remove `$user.ip_address`. Adding such a rule ultimately overrules any other logic. + + + +Additionally, you can provide arbitrary key/value pairs beyond the reserved names, and the Sentry SDK will store those with the user. + +To identify the user: + + + +You can also clear the currently set user: + + diff --git a/docs/platforms/powershell/enriching-events/index.mdx b/docs/platforms/powershell/enriching-events/index.mdx new file mode 100644 index 0000000000000..1543ead81a8ea --- /dev/null +++ b/docs/platforms/powershell/enriching-events/index.mdx @@ -0,0 +1,7 @@ +--- +title: Enriching Events +description: Enrich events with additional context to make debugging simpler. +sidebar_order: 3000 +--- + + diff --git a/docs/platforms/powershell/enriching-events/scopes/index.mdx b/docs/platforms/powershell/enriching-events/scopes/index.mdx new file mode 100644 index 0000000000000..9b01857f537d1 --- /dev/null +++ b/docs/platforms/powershell/enriching-events/scopes/index.mdx @@ -0,0 +1,90 @@ +--- +title: Scopes and Hubs +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." +--- + +When an event is captured and sent to Sentry, SDKs will merge that event data with extra +information from the current scope. SDKs will typically automatically manage the scopes +for you in the framework integrations and you don't need to think about them. However, +you should know what a scope is and how you can use it for your advantage. + +## What's a Scope, What's a Hub + +You can think of the hub as the central point that our SDKs use to route an +event to Sentry. When you call `init()` a hub is created and a client and a +blank scope are created on it. That hub is then associated with the current +thread and will internally hold a stack of scopes. + +The scope will hold useful information that should be sent along with the +event. For instance [contexts](../context/) or +[breadcrumbs](../breadcrumbs/) are stored on +the scope. When a scope is pushed, it inherits all data from the parent scope +and when it pops all modifications are reverted. + +The default SDK integrations will push and pop scopes intelligently. For +instance web framework integrations will create and destroy scopes around your +routes or controllers. + +## How the Scope and Hub Work + +As you start using an SDK, a scope and hub are automatically created for you out +of the box. It's unlikely that you'll interact with the hub directly unless you're +writing an integration or you want to create or destroy scopes. Scopes, on the +other hand are more user facing. You can call at any point in +time to modify data stored on the scope. This is useful for doing things like +[modifying the context](../context/). + + + +If you are very curious about how thread locality works: On platforms such as .NET +or on Python 3.7 and later we will use "ambient data" to have either the hub flow +with your code or the hub is already a singleton that internally manages the scope. + +Effectively this means that when you spawn a task in .NET and the execution flow is +not suppressed all the context you have bound to the scope in Sentry will flow along. +If however you suppress the flow, you get new scope data. + + + +When you call a global function such as internally Sentry +discovers the current hub and asks it to capture an event. Internally the hub will +then merge the event with the topmost scope's data. + +## Configuring the Scope + +The most useful operation when working with scopes is the function. It can be used to reconfigure the current scope. + +You can, for instance, add custom tags or inform Sentry about the currently authenticated user. + + + +You can also apply this configuration when unsetting a user at logout: + + + +To learn what useful information can be associated with scopes see +[the context documentation](../context/). + +## Local Scopes + +We also support pushing and configuring a scope within a single call. This is typically +called , or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if +you only want to send data for one specific event. + +### Using Scope Callback Parameter + +In the following example we use the scope callback parameter that is available for all `capture` methods to attach a `level` and a `tag` to only one specific error: + + + +Before the callback is invoked the SDK creates a clone of the current scope, and the changes +made will stay isolated within the callback function. This allows you to +more easily isolate pieces of context information to specific locations in your code or +even call `clear` to briefly remove all context information. + + + +Any exceptions that occur within the callback function for configuring a local scope will not be +caught, and all errors that occur will be silently ignored and **not** reported. + + diff --git a/docs/platforms/powershell/enriching-events/tags/index.mdx b/docs/platforms/powershell/enriching-events/tags/index.mdx new file mode 100644 index 0000000000000..a80992f5a05db --- /dev/null +++ b/docs/platforms/powershell/enriching-events/tags/index.mdx @@ -0,0 +1,28 @@ +--- +title: Tags +description: "Tags power UI features such as filters and tag-distribution maps. Tags also help you quickly access related events and view the tag distribution for a set of events." +--- + +**Tags** are key/value string pairs that are both indexed and searchable. Tags power features in sentry.io such as filters and tag-distribution maps. Tags also help you quickly both access related events and view the tag distribution for a set of events. Common uses for tags include hostname, platform version, and user language. + +We’ll automatically index all tags for an event, as well as the frequency and the last time that Sentry has seen a tag. We also keep track of the number of distinct tags and can assist you in determining hotspots for various issues. + +_Tag keys_ have a maximum length of 32 characters and can contain only letters (`a-zA-Z`), numbers (`0-9`), underscores (`_`), periods (`.`), colons (`:`), and dashes (`-`). + +_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: + + + + + +Some tags are automatically set by Sentry. We strongly recommend against overwriting these [tags](/product/reference/search/searchable-properties/#search-properties). Instead, name your tags with your organization's nomenclature. If you overwrite an automatically set tag, you must use [explicit tag syntax](/product/reference/search/#explicit-tag-syntax) to search for it. + + + +Once you've started sending tagged data, you'll see it when logged in to sentry.io. There, you can view the filters within the sidebar on the Project page, summarized within an event, and on the Tags page for an aggregated event. + +![](/platforms/dotnet/common/enriching-events/tags/tags.png) diff --git a/docs/platforms/powershell/index.mdx b/docs/platforms/powershell/index.mdx new file mode 100644 index 0000000000000..21afbf5f1e682 --- /dev/null +++ b/docs/platforms/powershell/index.mdx @@ -0,0 +1,45 @@ +--- +title: PowerShell +caseStyle: PascalCase +supportLevel: production +sdk: sentry.powershell +categories: + - server + - desktop + - console +--- + + + +On this page, we get you up and running with Sentry's PowerShell SDK. The PowerShell Sentry SDK is tested to work with: + +- PowerShell 7.2+ on Windows, macOS, and Linux +- Windows PowerShell 5.1 + +The PowerShell SDK is based on the Sentry .NET SDK. You can refer to the [.NET SDK docs](/platforms/dotnet/configuration) for the documentation of advanced features you don't find here. + +## Install + +Sentry captures data by using an SDK within your application’s runtime. + + + +## Configure + +Configuration should happen as early as possible in your application's lifecycle. + + + +## Verify + +This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. + + + + + +Learn more about manually capturing an error or message in our Usage documentation. + + + +To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. diff --git a/docs/platforms/powershell/performance/index.mdx b/docs/platforms/powershell/performance/index.mdx new file mode 100644 index 0000000000000..3e3331bce81f4 --- /dev/null +++ b/docs/platforms/powershell/performance/index.mdx @@ -0,0 +1,38 @@ +--- +title: Set Up Performance +description: "Learn how to enable performance monitoring in your app if it is not already set up." +sidebar_order: 4000 +--- + +With [performance monitoring](/product/performance/), Sentry tracks your software performance, measuring metrics like throughput and latency, and displaying the impact of errors across multiple systems. Sentry captures distributed traces consisting of transactions and spans, which measure individual services and individual operations within those services. Learn more about our model in [Distributed Tracing](/product/sentry-basics/tracing/distributed-tracing/). + + + +If you’re adopting Performance in a high-throughput environment, we recommend testing prior to deployment to ensure that your service’s performance characteristics maintain expectations. + + + +## Configure + +First, enable tracing and configure the sampling rate for transactions. Set the sample rate for your transactions by either: + +- Setting a uniform sample rate for all transactions using the option in your SDK config to a number between `0` and `1`. (For example, to send 20% of transactions, set to `0.2`.) +- Controlling the sample rate based on the transaction itself and the context in which it's captured, by providing a function to the config option. + +The two options are meant to be mutually exclusive. If you set both, will take precedence. + + + +Learn more about performance monitoring options, or how to sample transactions. + +## Verify + +Test out tracing by starting and finishing a transaction, which you _must_ do so transactions can be sent to Sentry. Learn how in our Custom Instrumentation content. + +While you're testing, set to `1.0`, as that ensures that every transaction will be sent to Sentry. + +Once testing is complete, you may want to set a lower value, or switch to using to selectively sample and filter your transactions, based on contextual data. + +## Next Steps + + diff --git a/docs/platforms/powershell/performance/instrumentation/custom-instrumentation.mdx b/docs/platforms/powershell/performance/instrumentation/custom-instrumentation.mdx new file mode 100644 index 0000000000000..add6773ee1f09 --- /dev/null +++ b/docs/platforms/powershell/performance/instrumentation/custom-instrumentation.mdx @@ -0,0 +1,17 @@ +--- +title: Custom Instrumentation +description: "Learn how to capture performance data on any action in your app." +sidebar_order: 20 +--- + + + +To capture transactions and spans customized to your organization's needs, you must first set up performance monitoring. + + + + + + + + diff --git a/docs/platforms/powershell/performance/instrumentation/index.mdx b/docs/platforms/powershell/performance/instrumentation/index.mdx new file mode 100644 index 0000000000000..31b4b4f67612f --- /dev/null +++ b/docs/platforms/powershell/performance/instrumentation/index.mdx @@ -0,0 +1,9 @@ +--- +title: Instrumentation +description: "Learn how to instrument performance in your app." +sidebar_order: 20 +--- + +Instrumenting performance monitoring is specific to your SDK. + + diff --git a/docs/platforms/powershell/performance/instrumentation/performance-metrics.mdx b/docs/platforms/powershell/performance/instrumentation/performance-metrics.mdx new file mode 100644 index 0000000000000..da290a2153e4f --- /dev/null +++ b/docs/platforms/powershell/performance/instrumentation/performance-metrics.mdx @@ -0,0 +1,66 @@ +--- +title: Performance Metrics +description: "Learn how to attach performance metrics to your transactions." +sidebar_order: 20 +--- + +Sentry's SDKs support sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry. + +## Custom Metrics + +In addition to automatic performance metrics, the SDK supports setting [custom performance metrics](/product/performance/metrics/#custom-performance-metrics) on transactions. This allows you to define metrics that are important to your application and send them to Sentry. + +To set a performance metric, you need to supply the following: + +- name (`string`) +- value (any numeric type - `float`, `integer`, etc.) +- unit (`string`, Defaults to the string `none` if omitted.) + +Sentry supports adding arbitrary custom units, but we recommend using one of the [supported units listed below](./#supported-performance-metric-units). + + + + + +Currently, unit conversion is only supported once the data has already been stored. This means that, for example, `('myMetric', 60, 'second')` and `('myMetric', 3, 'minute')` would not be aggregated, but rather stored as two separate metrics. To avoid this, make sure to use a consistent unit when recording a custom metric. + + + +## Supported Performance Metric Units + +Units augment metric values by giving meaning to what otherwise might be abstract numbers. Adding units also allows Sentry to offer controls - unit conversions, filters, and so on - based on those units. For values that are unitless, you can supply an empty string or `none`. + +### Duration Units + +- `nanosecond` +- `microsecond` +- `millisecond` +- `second` +- `minute` +- `hour` +- `day` +- `week` + +### Information Units + +- `bit` +- `byte` +- `kilobyte` +- `kibibyte` +- `megabyte` +- `mebibyte` +- `gigabyte` +- `gibibyte` +- `terabyte` +- `tebibyte` +- `petabyte` +- `pebibyte` +- `exabyte` +- `exbibyte` + +### Fraction Units + +- `ratio` +- `percent` + +If you want to explore further, you can find details about supported units in our [event ingestion documentation](https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html). diff --git a/docs/platforms/powershell/performance/troubleshooting/index.mdx b/docs/platforms/powershell/performance/troubleshooting/index.mdx new file mode 100644 index 0000000000000..ae3f809c8df2c --- /dev/null +++ b/docs/platforms/powershell/performance/troubleshooting/index.mdx @@ -0,0 +1,21 @@ +--- +title: Troubleshooting +description: "Learn how to troubleshoot your performance monitoring setup." +sidebar_order: 40 +--- + +If you need help managing transactions, you can read more here. If you need additional help, you can ask on GitHub. Customers on a paid plan may also contact support. + +## Control Data Truncation + +Currently, every tag has a maximum character limit of 200 characters. Tags over the 200 character limit will become truncated, losing potentially important information. To retain this data, you can split data over several tags instead. + +For example, a 200+ character tagged request: + +`https://empowerplant.io/api/0/projects/ep/setup_form/?user_id=314159265358979323846264338327&tracking_id=EasyAsABC123OrSimpleAsDoReMi&product_name=PlantToHumanTranslator&product_id=161803398874989484820458683436563811772030917980576` + +The 200+ character request above will become truncated to: + +`https://empowerplant.io/api/0/projects/ep/setup_form/?user_id=314159265358979323846264338327&tracking_id=EasyAsABC123OrSimpleAsDoReMi&product_name=PlantToHumanTranslator&product_id=1618033988749894848` + + diff --git a/docs/platforms/powershell/troubleshooting.mdx b/docs/platforms/powershell/troubleshooting.mdx new file mode 100644 index 0000000000000..eb75724af8e95 --- /dev/null +++ b/docs/platforms/powershell/troubleshooting.mdx @@ -0,0 +1,19 @@ +--- +title: Troubleshooting +sidebar_order: 9000 +description: "Learn more about how to troubleshoot common issues. " +--- + +## The event is dropped by Sentry because it's too large + +> Sentry: (Error) Sentry rejected the envelope 5bfe4129cb2446c08768b16479865035. Status code: RequestEntityTooLarge. Error detail: failed to read request body. Error causes: A payload reached size limit. + +You can have the [Sentry SDK write these envelopes to a path](https://github.com/getsentry/sentry-dotnet/blob/e62013ca63436d2a786fb229570e96f42c7c4044/src/Sentry/Http/HttpTransportBase.cs#L341-L363) in order to troubleshoot why they are too large. +Set the environment variable `SENTRY_KEEP_LARGE_ENVELOPE_PATH` to the directory you want these to be written to. +Make sure the process the SDK is running in has write access to it. + +## Unhandled exceptions are not captured + +Currently, the SDK captures exceptions that are explicitly handled by ane of the following methods: +- piping the `ErrorRecord` inside a `catch` statement or in a `trap` using `$_ | Out-Sentry` +- using `Invoke-WithSentry { ... }` diff --git a/docs/platforms/powershell/usage/index.mdx b/docs/platforms/powershell/usage/index.mdx new file mode 100644 index 0000000000000..91c3aead08e03 --- /dev/null +++ b/docs/platforms/powershell/usage/index.mdx @@ -0,0 +1,32 @@ +--- +title: Usage +description: "Use the SDK to manually capture errors and other events." +sidebar_order: 10 +--- + +Sentry's SDK hooks into your runtime environment and automatically reports errors, uncaught exceptions, and unhandled rejections as well as other types of errors depending on the platform. + + + +Key terms: + +- An _event_ is one instance of sending data to Sentry. Generally, this data is an error or exception. +- An _issue_ is a grouping of similar events. +- The reporting of an event is called _capturing_. + When an event is captured, it’s sent to Sentry. + + + +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. + +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. + +## Capturing Errors + + + +## Capturing Messages + +Another common operation is to capture a bare message. A message is textual information that should be sent to Sentry. Typically, our SDKs don't automatically capture messages, but you can capture them manually. + + diff --git a/docs/platforms/powershell/usage/set-level/index.mdx b/docs/platforms/powershell/usage/set-level/index.mdx new file mode 100644 index 0000000000000..b84aa4001e095 --- /dev/null +++ b/docs/platforms/powershell/usage/set-level/index.mdx @@ -0,0 +1,9 @@ +--- +title: Set the Level +description: "The level - similar to logging levels - is generally added by default based on the integration. You can also override it within an event." +sidebar_order: 5 +--- + +The level - similar to logging levels - is generally added by default based on the integration. You can also override it within an event. + + diff --git a/package.json b/package.json index 08cad564e825d..01afeec0f792e 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,7 @@ "next-auth": "^4.24.5", "next-mdx-remote": "^4.4.1", "nextjs-toploader": "^1.6.6", - "platformicons": "^5.9.2", + "platformicons": "^5.10.2", "prism-sentry": "^1.0.2", "prismjs": "^1.27.0", "query-string": "^6.13.1", diff --git a/platform-includes/capture-error/powershell.mdx b/platform-includes/capture-error/powershell.mdx new file mode 100644 index 0000000000000..4b869c7064e68 --- /dev/null +++ b/platform-includes/capture-error/powershell.mdx @@ -0,0 +1,26 @@ +In PowerShell you can capture any `[ErrorRecord]` object that you caught: + +```powershell +try +{ + AFunctionThatMightFail +} +catch +{ + $_ | Out-Sentry +} +``` + +Or you can install a `trap` in a block to log errors that occur within that block. +Be sure to understand how `trap` works especially in regards to scope and how the execution continues/breaks when `trap` is used. + +```powershell +AFunctionThatMightFail + +# The trap will get called even if it is declared after the code that throws. +# It's because traps are processed by PowerShell before the script is executed. +trap +{ + $_ | Out-Sentry +} +``` diff --git a/platform-includes/capture-message/powershell.mdx b/platform-includes/capture-message/powershell.mdx new file mode 100644 index 0000000000000..f2728e2e1b014 --- /dev/null +++ b/platform-includes/capture-message/powershell.mdx @@ -0,0 +1,3 @@ +```powershell +"Something went wrong" | Out-Sentry +``` diff --git a/platform-includes/configuration/auto-session-tracking/powershell.mdx b/platform-includes/configuration/auto-session-tracking/powershell.mdx new file mode 100644 index 0000000000000..13052f40e2ef0 --- /dev/null +++ b/platform-includes/configuration/auto-session-tracking/powershell.mdx @@ -0,0 +1,14 @@ +We mark the session as: + +- Healthy +- Abnormal +- Errored: if the SDK captures an event that contains an exception (this includes manually captured errors). +- Crashed + +To enable sending sessions, set the `AutoSessionTracking` flag to `$true`. When enabled, the SDK is creating a session on application startup and ending it on shut down. + +```powershell +Start-Sentry { + $_.AutoSessionTracking = $true +} +``` diff --git a/platform-includes/configuration/before-send-transaction/powershell.mdx b/platform-includes/configuration/before-send-transaction/powershell.mdx new file mode 100644 index 0000000000000..5edc3107d0f09 --- /dev/null +++ b/platform-includes/configuration/before-send-transaction/powershell.mdx @@ -0,0 +1,29 @@ +A `Func` can be used to update the transaction or drop it by returning `null` before it gets sent to Sentry. For example: + +```powershell +Start-Sentry { + $_.Dsn = 'https://key@127.0.0.1/1' + + # Add this to the SDK initialization callback + $_.SetBeforeSendTransaction([System.Func[Sentry.SentryTransaction, Sentry.SentryTransaction]] { + param([Sentry.SentryTransaction]$sentryTransaction) + + # Modify the transaction + if ($sentryTransaction.Operation -eq 'http.server') + { + return $null; # Drop the transaction by returning null + } + + return #sentryTransaction; + }); +} +``` + +```csharp +using Sentry; + + +options.SetBeforeSendTransaction((sentryTransaction, hint) => +{ +}); +``` diff --git a/platform-includes/configuration/before-send/powershell.mdx b/platform-includes/configuration/before-send/powershell.mdx new file mode 100644 index 0000000000000..3ae2bc1114042 --- /dev/null +++ b/platform-includes/configuration/before-send/powershell.mdx @@ -0,0 +1,19 @@ +A `Func` can be used to mutate, discard (return null), or return a completely new event. + +```powershell +Start-Sentry { + $_.Dsn = 'https://key@127.0.0.1/1' + + # Capture all events in BeforeSend callback & drop them. + $_.SetBeforeSend([System.Func[Sentry.SentryEvent, Sentry.SentryEvent]] { + param([Sentry.SentryEvent]$event_) + + if ($null -ne $event_.Exception -and $event_.Exception.Message.Contains("Noisy Exception")) + { + return $null # Don't send this event to Sentry + } + + return $event_ + }); +} +``` diff --git a/platform-includes/configuration/config-intro/powershell.mdx b/platform-includes/configuration/config-intro/powershell.mdx new file mode 100644 index 0000000000000..d4cc800452a93 --- /dev/null +++ b/platform-includes/configuration/config-intro/powershell.mdx @@ -0,0 +1,26 @@ +For example, initialize with `Start-Sentry` in your PowerShell script: + + + +```powershell +Start-Sentry { + # A Sentry Data Source Name (DSN) is required. + # See https://docs.sentry.io/product/sentry-basics/dsn-explainer/ + # You can set it in the SENTRY_DSN environment variable, or you can set it in code here. + $_.Dsn = '___PUBLIC_DSN___' + + # When debug is enabled, the Sentry client will emit detailed debugging information to the console. + # This might be helpful, or might interfere with the normal operation of your application. + # We enable it here for demonstration purposes when first trying Sentry. + # You shouldn't do this in your applications unless you're troubleshooting issues with Sentry. + # Alternatively, you can pass `-Debug` to the `Start-Sentry` command. + $_.Debug = $true + + # This option is recommended. It enables Sentry's "Release Health" feature. + $_.AutoSessionTracking = $true + + # This option will enable Sentry's tracing features. You still need to start transactions and spans. + # Example sample rate for your transactions: captures 10% of transactions + $_.TracesSampleRate = 0.1 +} +``` diff --git a/platform-includes/configuration/drain-example/powershell.mdx b/platform-includes/configuration/drain-example/powershell.mdx new file mode 100644 index 0000000000000..6ee7768ea8982 --- /dev/null +++ b/platform-includes/configuration/drain-example/powershell.mdx @@ -0,0 +1,11 @@ +The .NET SDK gracefully handles shutdown, waiting up to `ShutdownTimeout` seconds to flush captured events. + +This happens in a variety of different situations: + +- Automatically, in the case of a normal application exit. +- Automatically, in the case of an unhandled exception. +- Automatically, for integrations that use dependency injection (`UseSentry`, `AddSentry`, etc.). +- Manually, if you dispose of the result of `SentrySdk.Init` (which is optional). +- Manually, if you call `SentrySdk.Flush` or `SentrySdk.FlushAsync`. + +In most cases, you can rely on the automatic approaches and don't need to worry about this. diff --git a/platform-includes/configuration/sample-rate/powershell.mdx b/platform-includes/configuration/sample-rate/powershell.mdx new file mode 100644 index 0000000000000..9ee95273ccdef --- /dev/null +++ b/platform-includes/configuration/sample-rate/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Start-Sentry { + $_.SampleRate = 0.25 +} +``` diff --git a/platform-includes/enriching-events/attachment-init-with-bytes/powershell.mdx b/platform-includes/enriching-events/attachment-init-with-bytes/powershell.mdx new file mode 100644 index 0000000000000..2ac074ba65d58 --- /dev/null +++ b/platform-includes/enriching-events/attachment-init-with-bytes/powershell.mdx @@ -0,0 +1,7 @@ +```powershell +# Add an in-memory attachment to the current scope +Edit-SentryScope { + [byte[]] $data = 1, 2, 3, 4, 5 + [Sentry.ScopeExtensions]::AddAttachment($_, $data, 'filename.bin') +} +``` diff --git a/platform-includes/enriching-events/attachment-init-with-path/powershell.mdx b/platform-includes/enriching-events/attachment-init-with-path/powershell.mdx new file mode 100644 index 0000000000000..14238f499be66 --- /dev/null +++ b/platform-includes/enriching-events/attachment-init-with-path/powershell.mdx @@ -0,0 +1,6 @@ +```powershell +# Add a file attachment to the current scope +Edit-SentryScope { + [Sentry.ScopeExtensions]::AddAttachment($_, 'your/path/file.log') +} +``` diff --git a/platform-includes/enriching-events/attachment-max-size/powershell.mdx b/platform-includes/enriching-events/attachment-max-size/powershell.mdx new file mode 100644 index 0000000000000..aec55773dbd9a --- /dev/null +++ b/platform-includes/enriching-events/attachment-max-size/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Start-Sentry { + $_.MaxAttachmentSize = 5 * 1024 * 1024 # 5 MiB +} +``` diff --git a/platform-includes/enriching-events/attachment-upload/powershell.mdx b/platform-includes/enriching-events/attachment-upload/powershell.mdx new file mode 100644 index 0000000000000..07a965575bf3d --- /dev/null +++ b/platform-includes/enriching-events/attachment-upload/powershell.mdx @@ -0,0 +1,16 @@ +```powershell +# Global Scope +Edit-SentryScope { + [Sentry.ScopeExtensions]::AddAttachment($_, 'your/path/file.log') +} + +# Local Scope +'message' | Out-Sentry -EditScope { + [Sentry.ScopeExtensions]::AddAttachment($_, 'your/path/file.log') +} + +# Clear all attachments in the global scope +Edit-SentryScope { + $scope.ClearAttachments(); +} +``` diff --git a/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/powershell.mdx b/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/powershell.mdx new file mode 100644 index 0000000000000..362c5542868b0 --- /dev/null +++ b/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/powershell.mdx @@ -0,0 +1,12 @@ +```powershell +Start-Sentry { + $_.SetBeforeBreadcrumb([System.Func[Sentry.Breadcrumb, Sentry.Breadcrumb]] { + param([Sentry.Breadcrumb]$breadcrumb) + # Ignore breadcrumbs from Spammy logger + if ($breadcrumb.Category -eq "Spammy.Logger") { + return $null + } + return $breadcrumb + }); +} +``` diff --git a/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/powershell.mdx b/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/powershell.mdx new file mode 100644 index 0000000000000..3290f942e5b5d --- /dev/null +++ b/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/powershell.mdx @@ -0,0 +1,7 @@ +```powershell +# Simple breadcrumb with just a message +'hello there' | Add-SentryBreadcrumb + +# More complext breadcrumb +Add-SentryBreadcrumb -Message 'hello there' -Category 'cat' -Type 'foo' -Level Warning -Data @{ 'key' = 'value' } +``` diff --git a/platform-includes/enriching-events/scopes/configure-scope/powershell.mdx b/platform-includes/enriching-events/scopes/configure-scope/powershell.mdx new file mode 100644 index 0000000000000..384fcf5e6f5fc --- /dev/null +++ b/platform-includes/enriching-events/scopes/configure-scope/powershell.mdx @@ -0,0 +1,7 @@ +```powershell +Edit-SentryScope { + $_.SetTag("my-tag", "my value") + $_.User.Id = '42' + $_.User.Email = 'john.doe@example.com' +} +``` diff --git a/platform-includes/enriching-events/scopes/scope-callback-param/powershell.mdx b/platform-includes/enriching-events/scopes/scope-callback-param/powershell.mdx new file mode 100644 index 0000000000000..53d724b059fe4 --- /dev/null +++ b/platform-includes/enriching-events/scopes/scope-callback-param/powershell.mdx @@ -0,0 +1,18 @@ +```powershell +try { + throw "my error" +} catch { + # will be tagged with my-tag="my value" + $_ | Out-Sentry -EditScope { + $_.SetTag("my-tag", "my value") + $_.Level = [Sentry.SentryLevel]::Warning + } +} + +try { + throw "my other error" +} catch { + # will not be tagged with my-tag + $_ | Out-Sentry +} +``` diff --git a/platform-includes/enriching-events/set-context/powershell.mdx b/platform-includes/enriching-events/set-context/powershell.mdx new file mode 100644 index 0000000000000..aecf287ef1d44 --- /dev/null +++ b/platform-includes/enriching-events/set-context/powershell.mdx @@ -0,0 +1,9 @@ +```powershell +Edit-SentryScope { + $_.Contexts['character'] = @{ + Name = 'Mighty Fighter' + Age = 19 + AttackType = 'melee' + }; +} +``` diff --git a/platform-includes/enriching-events/set-tag/powershell.mdx b/platform-includes/enriching-events/set-tag/powershell.mdx new file mode 100644 index 0000000000000..7a96b70f5f229 --- /dev/null +++ b/platform-includes/enriching-events/set-tag/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Edit-SentryScope { + $_.SetTag("page.locale", "de-at") +} +``` diff --git a/platform-includes/enriching-events/set-user/powershell.mdx b/platform-includes/enriching-events/set-user/powershell.mdx new file mode 100644 index 0000000000000..76e36a0871dc7 --- /dev/null +++ b/platform-includes/enriching-events/set-user/powershell.mdx @@ -0,0 +1,6 @@ +```powershell +Edit-SentryScope { + $_.User.Id = '42' + $_.User.Email = 'john.doe@example.com' +} +``` diff --git a/platform-includes/enriching-events/unset-user/powershell.mdx b/platform-includes/enriching-events/unset-user/powershell.mdx new file mode 100644 index 0000000000000..d14c4fcfcc955 --- /dev/null +++ b/platform-includes/enriching-events/unset-user/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Edit-SentryScope { + $_.User = $null +} +``` diff --git a/platform-includes/getting-started-config/powershell.mdx b/platform-includes/getting-started-config/powershell.mdx new file mode 100644 index 0000000000000..b722fc0f79985 --- /dev/null +++ b/platform-includes/getting-started-config/powershell.mdx @@ -0,0 +1,11 @@ +Once this is done, Sentry's PowerShell SDK can be used to capture errors. + + + +```powershell +# You may need to import the module if you've just installed it. +Import-Module Sentry + +# Start the Sentry SDK with the default options. +Start-Sentry '___PUBLIC_DSN___' +``` diff --git a/platform-includes/getting-started-install/powershell.mdx b/platform-includes/getting-started-install/powershell.mdx new file mode 100644 index 0000000000000..6fa029484a0c1 --- /dev/null +++ b/platform-includes/getting-started-install/powershell.mdx @@ -0,0 +1,5 @@ +Install our PowerShell SDK using [PowerShellGet](https://learn.microsoft.com/en-us/powershell/gallery/powershellget/install-powershellget): + +```powershell +Install-Module -Name Sentry -Scope CurrentUser -Repository PSGallery -Force +``` diff --git a/platform-includes/getting-started-verify/powershell.mdx b/platform-includes/getting-started-verify/powershell.mdx new file mode 100644 index 0000000000000..d088f199ead71 --- /dev/null +++ b/platform-includes/getting-started-verify/powershell.mdx @@ -0,0 +1,10 @@ +```powershell +try +{ + throw 'Test error' +} +catch +{ + $_ | Out-Sentry +} +``` diff --git a/platform-includes/performance/add-spans-example/powershell.mdx b/platform-includes/performance/add-spans-example/powershell.mdx new file mode 100644 index 0000000000000..faacc05dd82cd --- /dev/null +++ b/platform-includes/performance/add-spans-example/powershell.mdx @@ -0,0 +1,22 @@ +You can add individual spans to a transaction by calling the `StartChild` method on a transaction. +This method returns a new `SentrySpan` object that you can use to record the duration of the operation that the span represents. +When you're done with the operation, you can call the `Finish` method on the span to mark it as finished. + +```powershell +# Transaction can be started by providing, at minimum, the name and the operation +$transaction = Start-SentryTransaction 'test-transaction-name' 'test-transaction-operation' + +# Transactions can have child spans (and those spans can have child spans as well) +$span = $transaction.StartChild("test-child-operation") +# ... +# (Perform the operation represented by the span/transaction) +# ... +$span.Finish() # Mark the span as finished + +$span = $transaction.StartChild("another-span") +# ... +$span.Finish() + + +$transaction.Finish() # Mark the transaction as finished and send it to Sentry +``` diff --git a/platform-includes/performance/always-inherit-sampling-decision/powershell.mdx b/platform-includes/performance/always-inherit-sampling-decision/powershell.mdx new file mode 100644 index 0000000000000..df475333aad3e --- /dev/null +++ b/platform-includes/performance/always-inherit-sampling-decision/powershell.mdx @@ -0,0 +1,23 @@ +```powershell +Start-Sentry { + // OR: Determine traces sample rate based on the sampling context + $_.TracesSampler = [System.Func[Sentry.TransactionSamplingContext, System.Nullable`1[System.Double]]] { + param([Sentry.TransactionSamplingContext]$context) + + # If this is the continuation of a trace, just use that decision (rate controlled by the caller) + if ($context.TransactionContext.IsParentSampled) + { + return 1.0 # Keep all traces complete + } + + + # the rest of sampling logic, for example: + if ($context.TransactionContext.Name -eq 'important-endpoint') + { + return 1.0 # 100% for an important endpoint + } + + return 0.5 # 50% for everything else + } +} +``` diff --git a/platform-includes/performance/configure-sample-rate/powershell.mdx b/platform-includes/performance/configure-sample-rate/powershell.mdx new file mode 100644 index 0000000000000..0ef2be04f41e4 --- /dev/null +++ b/platform-includes/performance/configure-sample-rate/powershell.mdx @@ -0,0 +1,6 @@ +```powershell +Start-Sentry { + # Example uniform sample rate: capture 100% of transactions + $_.TracesSampleRate = 1.0 +} +``` diff --git a/platform-includes/performance/custom-performance-metrics/powershell.mdx b/platform-includes/performance/custom-performance-metrics/powershell.mdx new file mode 100644 index 0000000000000..85f398a805522 --- /dev/null +++ b/platform-includes/performance/custom-performance-metrics/powershell.mdx @@ -0,0 +1,13 @@ +The following example shows how to set custom metrics on a `transaction`, including how obtain the current `span` and get its `transaction`. +If you already have the `transaction` or `span`, you can use it directly. + +```powershell +# Record amount of memory used +[Sentry.SpanDataExtensions]::SetMeasurement($transaction, 'memory_used', 64, [Sentry.MeasurementUnit+Information]::Megabyte) + +# Record time it took to load user profile +[Sentry.SpanDataExtensions]::SetMeasurement($transaction, 'user_profile_loading_time', 1.3, [Sentry.MeasurementUnit+Duration]::Second) + +# Record number of times the screen was loaded +[Sentry.SpanDataExtensions]::SetMeasurement($transaction, 'screen_load_count', 4) +``` diff --git a/platform-includes/performance/custom-sampling-context/powershell.mdx b/platform-includes/performance/custom-sampling-context/powershell.mdx new file mode 100644 index 0000000000000..90786c038bca6 --- /dev/null +++ b/platform-includes/performance/custom-sampling-context/powershell.mdx @@ -0,0 +1,10 @@ +```powershell +# Starts the transaction with +# name = "GET /search" +# op = "http +# CustomSamplingContext = hashtable +$transaction = Start-SentryTransaction "GET /search", "http" @{ + 'user_id' = 42 + 'search_results' = @{} +} +``` diff --git a/platform-includes/performance/default-sampling-context-platform/dotnet.mdx b/platform-includes/performance/default-sampling-context-platform/dotnet.mdx index d139ffd6deec3..be8f228ebd716 100644 --- a/platform-includes/performance/default-sampling-context-platform/dotnet.mdx +++ b/platform-includes/performance/default-sampling-context-platform/dotnet.mdx @@ -1 +1 @@ -For .NET-based SDKs, it includes a [Transaction Context](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Protocol/TransactionContext.cs) and a custom sampling context (`string` to `object` dictionary). +For .NET-based SDKs, it includes a [Transaction Context](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/TransactionContext.cs) and a custom sampling context (`string` to `object` dictionary). diff --git a/platform-includes/performance/default-sampling-context-platform/powershell.mdx b/platform-includes/performance/default-sampling-context-platform/powershell.mdx new file mode 100644 index 0000000000000..be8f228ebd716 --- /dev/null +++ b/platform-includes/performance/default-sampling-context-platform/powershell.mdx @@ -0,0 +1 @@ +For .NET-based SDKs, it includes a [Transaction Context](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/TransactionContext.cs) and a custom sampling context (`string` to `object` dictionary). diff --git a/platform-includes/performance/default-sampling-context/powershell.mdx b/platform-includes/performance/default-sampling-context/powershell.mdx new file mode 100644 index 0000000000000..a6a92c2a989d8 --- /dev/null +++ b/platform-includes/performance/default-sampling-context/powershell.mdx @@ -0,0 +1 @@ + diff --git a/platform-includes/performance/enable-manual-instrumentation/powershell.mdx b/platform-includes/performance/enable-manual-instrumentation/powershell.mdx new file mode 100644 index 0000000000000..a149671f67bff --- /dev/null +++ b/platform-includes/performance/enable-manual-instrumentation/powershell.mdx @@ -0,0 +1,12 @@ +To instrument certain regions of your code, you can create transactions to capture them. + +```powershell +# Transaction can be started by providing, at minimum, the name and the operation +$transaction = Start-SentryTransaction 'test-transaction-name' 'test-transaction-operation' + +# ... +# (Perform the operation represented by the span/transaction) +# ... + +$transaction.Finish() # Mark the transaction as finished and send it to Sentry +``` diff --git a/platform-includes/performance/force-sampling-decision/powershell.mdx b/platform-includes/performance/force-sampling-decision/powershell.mdx new file mode 100644 index 0000000000000..0a360475fb77c --- /dev/null +++ b/platform-includes/performance/force-sampling-decision/powershell.mdx @@ -0,0 +1,3 @@ +```powershell +Start-SentryTransaction "GET /search" "http" -ForceSampled +``` diff --git a/platform-includes/performance/retrieve-transaction/powershell.mdx b/platform-includes/performance/retrieve-transaction/powershell.mdx new file mode 100644 index 0000000000000..b2aac6161c3bd --- /dev/null +++ b/platform-includes/performance/retrieve-transaction/powershell.mdx @@ -0,0 +1,16 @@ +## Retrieve a Transaction + +In cases where you want to attach Spans to an already ongoing Transaction you can use `SentrySdk.GetSpan()`. If there is a running Transaction or Span currently on the scope, this method will return a `SentryTransaction` or `SentrySpan`; otherwise, it returns `$null`. + +```powershell +$span = [Sentry.SentrySdk]::GetSpan() + +if ($null -eq $span) +{ + $span = Start-SentryTransaction 'task' 'op' +} +else +{ + $span = $span.StartChild('subtask') +} +``` diff --git a/platform-includes/performance/sampling-function-intro/powershell.mdx b/platform-includes/performance/sampling-function-intro/powershell.mdx new file mode 100644 index 0000000000000..5abec3c0a6984 --- /dev/null +++ b/platform-includes/performance/sampling-function-intro/powershell.mdx @@ -0,0 +1,5 @@ +To use the sampling function, set the option in your `SentrySdk.Init()` to a function that will accept a dictionary and return a sample rate between 0 and 1. For example: + + + +Additionally, your sampling function may also return `null`, which indicates that no sampling decision has been made. In such case, the trace will retain the previous decision if it has been made (for example if it was started from an incoming trace header), or fall back to the value configured in . diff --git a/platform-includes/performance/traces-sample-rate/powershell.mdx b/platform-includes/performance/traces-sample-rate/powershell.mdx new file mode 100644 index 0000000000000..2035c898eb2b5 --- /dev/null +++ b/platform-includes/performance/traces-sample-rate/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Start-Sentry { + $_.TracesSampleRate = 0.2 +} +``` diff --git a/platform-includes/performance/traces-sampler-as-filter/powershell.mdx b/platform-includes/performance/traces-sampler-as-filter/powershell.mdx new file mode 100644 index 0000000000000..93b49ff3f60dc --- /dev/null +++ b/platform-includes/performance/traces-sampler-as-filter/powershell.mdx @@ -0,0 +1,18 @@ +```powershell +Start-Sentry { + $_.TracesSampler = [System.Func[Sentry.TransactionSamplingContext, System.Nullable`1[System.Double]]] { + param([Sentry.TransactionSamplingContext]$context) + + if (/* make a decision based on `samplingContext` */) { + # Drop this transaction, by setting its sample rate to 0% + return 0 + } else if (/* ... */) { + # Override sample rate for other cases (replaces `options.TracesSampleRate`) + return 0.1 + } + + # Can return `null` to fallback to the rate configured by `options.TracesSampleRate` + return $null + } +} +``` diff --git a/platform-includes/performance/traces-sampler-as-sampler/powershell.mdx b/platform-includes/performance/traces-sampler-as-sampler/powershell.mdx new file mode 100644 index 0000000000000..da6a6707f88a7 --- /dev/null +++ b/platform-includes/performance/traces-sampler-as-sampler/powershell.mdx @@ -0,0 +1,44 @@ +```powershell +Start-Sentry { + // Add this to the SDK initialization callback + // To set a uniform sample rate + $_.TracesSampleRate = 1.0 + + // OR: Determine traces sample rate based on the sampling context + $_.TracesSampler = [System.Func[Sentry.TransactionSamplingContext, System.Nullable`1[System.Double]]] { + param([Sentry.TransactionSamplingContext]$context) + + # If this is the continuation of a trace, just use that decision (rate controlled by the caller) + if ($null -ne $context.TransactionContext.IsParentSampled) + { + if ($context.TransactionContext.IsParentSampled.Value) + { + return 1.0 + } + else + { + return 0.0 + } + } + + # Otherwise, sample based on a custom sampling context you set with your transactions. + switch ( $context.CustomSamplingContext['__HttpPath'] ) + { + # These are important - take a big sample + '/payment' { 0.5 } + + # Search is less important and happen much more frequently - only take 1% + '/search' { 0.01 } + + # The health check endpoint is just noise - drop all transactions + '/health' { 0.0 } + + # Default sample rate + default { 0.1 } + + # Or return null to fallback to options.TracesSampleRate (1.0 in this case) + # default { $null } + } + } +} +``` diff --git a/platform-includes/performance/uniform-sample-rate/powershell.mdx b/platform-includes/performance/uniform-sample-rate/powershell.mdx new file mode 100644 index 0000000000000..379dbf2808748 --- /dev/null +++ b/platform-includes/performance/uniform-sample-rate/powershell.mdx @@ -0,0 +1,3 @@ +To do this, set the option when you initialize the SDK to a number between 0 and 1. With this option set, every transaction created will have that percentage chance of being sent to Sentry. (So, for example, if you set to `0.2`, approximately 20% of your transactions will get recorded and sent.) That looks like this: + + diff --git a/platform-includes/sensitive-data/set-tag/powershell.mdx b/platform-includes/sensitive-data/set-tag/powershell.mdx new file mode 100644 index 0000000000000..1f265237c7725 --- /dev/null +++ b/platform-includes/sensitive-data/set-tag/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Edit-SentryScope { + $_.SetTag("birthday", $BirthdayHash) +} +``` diff --git a/platform-includes/sensitive-data/set-user/powershell.mdx b/platform-includes/sensitive-data/set-user/powershell.mdx new file mode 100644 index 0000000000000..04f13da7b8c1c --- /dev/null +++ b/platform-includes/sensitive-data/set-user/powershell.mdx @@ -0,0 +1,11 @@ +```powershell +# User ID: +Edit-SentryScope { + $_.User.Id = $actualUser.Id +} + +# OR username: +Edit-SentryScope { + $_.User.Username = $actualUser.Username +} +``` diff --git a/platform-includes/set-environment/powershell.mdx b/platform-includes/set-environment/powershell.mdx new file mode 100644 index 0000000000000..3a67c88050327 --- /dev/null +++ b/platform-includes/set-environment/powershell.mdx @@ -0,0 +1,5 @@ +```powershell +Start-Sentry { + $_.Environment = "production" +} +``` diff --git a/platform-includes/set-level/powershell.mdx b/platform-includes/set-level/powershell.mdx new file mode 100644 index 0000000000000..ca46031c74de7 --- /dev/null +++ b/platform-includes/set-level/powershell.mdx @@ -0,0 +1,7 @@ +```powershell +[Sentry.SentrySdk]::ConfigureScope([System.Action[Sentry.Scope]] { + param([Sentry.Scope]$scope) + + $scope.Level = [SentryLevel]::Warning + }) +``` diff --git a/src/components/platformIcon.tsx b/src/components/platformIcon.tsx index 1600eb3ed2136..37981234007a3 100644 --- a/src/components/platformIcon.tsx +++ b/src/components/platformIcon.tsx @@ -84,6 +84,7 @@ import NodejsSVG from 'platformicons/svg/nodejs.svg'; import PerlSVG from 'platformicons/svg/perl.svg'; import PhpSVG from 'platformicons/svg/php.svg'; import PostgresqlSVG from 'platformicons/svg/postgresql.svg'; +import PowershellSVG from 'platformicons/svg/powershell.svg'; import PyramidSVG from 'platformicons/svg/pyramid.svg'; import PythonSVG from 'platformicons/svg/python.svg'; import QtSVG from 'platformicons/svg/qt.svg'; @@ -209,6 +210,7 @@ import NodejsSVGLarge from 'platformicons/svg_80x80/nodejs.svg'; import PerlSVGLarge from 'platformicons/svg_80x80/perl.svg'; import PhpSVGLarge from 'platformicons/svg_80x80/php.svg'; import PostgresqlSVGLarge from 'platformicons/svg_80x80/postgresql.svg'; +import PowershellSVGLarge from 'platformicons/svg_80x80/powershell.svg'; import PyramidSVGLarge from 'platformicons/svg_80x80/pyramid.svg'; import PythonSVGLarge from 'platformicons/svg_80x80/python.svg'; import QtSVGLarge from 'platformicons/svg_80x80/qt.svg'; @@ -591,6 +593,10 @@ const formatToSVG = { sm: PostgresqlSVG, lg: PostgresqlSVGLarge, }, + powershell: { + sm: PowershellSVG, + lg: PowershellSVGLarge, + }, pyramid: { sm: PyramidSVG, lg: PyramidSVGLarge, @@ -887,6 +893,7 @@ export const PLATFORM_TO_ICON = { 'python-sqlalchemy': 'sqlalchemy', 'python-tornado': 'tornado', 'python-tryton': 'tryton', + powershell: 'powershell', qt: 'qt', 'react-native': 'react-native', ruby: 'ruby', diff --git a/src/data/platforms.yml b/src/data/platforms.yml index 7f9ca36945b1e..437e0c9a6812e 100644 --- a/src/data/platforms.yml +++ b/src/data/platforms.yml @@ -113,3 +113,7 @@ - slug: deno type: framework name: Deno +- slug: powershell + type: language + name: PowerShell + case_style: PascalCase diff --git a/yarn.lock b/yarn.lock index e41d53d353463..2b9d717a3f473 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8069,10 +8069,10 @@ pkg-dir@^4.2.0: dependencies: find-up "^4.0.0" -platformicons@^5.9.2: - version "5.10.1" - resolved "https://registry.yarnpkg.com/platformicons/-/platformicons-5.10.1.tgz#1c9c39f7ab2ce5cab31f43f38d492440fb89fbbc" - integrity sha512-B5f0RnatfiW3mBAMzQ9liNL7G0XIlzvGQ+2jaw91rDh2ZLOfqw2KklROhnVdYZ5YTwnKXAn3UAF3i3yS6f1q5w== +platformicons@^5.10.2: + version "5.10.2" + resolved "https://registry.yarnpkg.com/platformicons/-/platformicons-5.10.2.tgz#9e17969f9ba07ca068ccd8f70251477ebe4a65ed" + integrity sha512-JhvTyqenbHm6ibZD6BMiY7yrtZTnd4vXKav+rt0Q4zVXWExC3LzKU2SQwSLWT+RSxJV1Cy/FW/qMgmY2hh6/9A== dependencies: "@types/node" "*" "@types/react" "*"