Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: PowerShell #9198

Merged
merged 11 commits into from
Mar 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/platforms/powershell/configuration/draining.mdx
Original file line number Diff line number Diff line change
@@ -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.

<PlatformContent includePath="configuration/drain-example" />
15 changes: 15 additions & 0 deletions docs/platforms/powershell/configuration/environments.mdx
Original file line number Diff line number Diff line change
@@ -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.

<PlatformContent includePath="set-environment" />

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/).
vaind marked this conversation as resolved.
Show resolved Hide resolved
45 changes: 45 additions & 0 deletions docs/platforms/powershell/configuration/filtering.mdx
Original file line number Diff line number Diff line change
@@ -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 <PlatformIdentifier name="before-send" /> callback method and configuring, enabling, or disabling integrations.

### Using <PlatformIdentifier name="before-send" />

All Sentry SDKs support the <PlatformIdentifier name="before-send" /> 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. <PlatformIdentifier name="before-send" /> 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.

<PlatformContent includePath="configuration/before-send/" />

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 <PlatformIdentifier name="traces-sampler" /> or <PlatformIdentifier name="before-send-transaction" /> 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 <PlatformIdentifier name="traces-sampler" />

**Note:** The <PlatformIdentifier name="traces-sampler" /> and <PlatformIdentifier name="traces-sample-rate" /> config options are mutually exclusive. If you define a <PlatformIdentifier name="traces-sampler" /> 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:

<PlatformContent includePath="performance/traces-sampler-as-filter" />

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 <PlatformIdentifier name="traces-sampler" /> 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 <PlatformLink to="/configuration/sampling/#inheritance">Inheriting the parent sampling decision</PlatformLink> to learn more.

Learn more about <PlatformLink to="/configuration/sampling/">configuring the sample rate</PlatformLink>.

### Using <PlatformIdentifier name="before-send-transaction" />

<PlatformContent includePath="configuration/before-send-transaction" />
7 changes: 7 additions & 0 deletions docs/platforms/powershell/configuration/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: Configuration
description: "Additional configuration options for the SDK."
sidebar_order: 5
---

<PageGrid />
183 changes: 183 additions & 0 deletions docs/platforms/powershell/configuration/options.mdx
Original file line number Diff line number Diff line change
@@ -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.

<PlatformContent includePath="configuration/config-intro" />

## Common Options
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be an include file shared by .NET/Unity/PowerShell?

It's going out of sync quickly otherwise

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above, this page is not .net specific, there are actually 18 copies of the same content right now, so any effort to reintegrate should be, IMO, done for all SDKs.


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.

<ConfigKey name="dsn">

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).

</ConfigKey>

<ConfigKey name="is-global-mode-enabled">

Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications.

Defaults to `true` for PowerShell.

</ConfigKey>

<ConfigKey name="debug">

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.

</ConfigKey>

<ConfigKey name="diagnostic-level">

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

</ConfigKey>

<ConfigKey name="dist">

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.

</ConfigKey>

<ConfigKey name="release">

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 <SandboxLink scenario="releases">sandbox</SandboxLink>.

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).

</ConfigKey>

<ConfigKey name="environment">

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`.

</ConfigKey>

<ConfigKey name="sample-rate">

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.

</ConfigKey>

<ConfigKey name="max-breadcrumbs">

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.

</ConfigKey>

<ConfigKey name="max-cache-items">

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`.

</ConfigKey>

<ConfigKey name="attach-stacktrace">

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.

</ConfigKey>

<ConfigKey name="send-default-pii">

If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent.

<Note>

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.

</Note>

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/).

</ConfigKey>

<ConfigKey name="send-client-reports">

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.

</ConfigKey>

## Hooks

These options can be used to hook the SDK in various ways to customize the reporting of events.

<ConfigKey name="before-send">

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 <PlatformIdentifier name="before-send" /> is executed, all scope data has already been applied to the event. Further modification of the scope won't have any effect.

</ConfigKey>

<ConfigKey name="before-breadcrumb">

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.

</ConfigKey>

## Transport Options

Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.

<ConfigKey name="transport">

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.

</ConfigKey>

<ConfigKey name="init-cache-flush-timeout">

When caching is enabled (that is, <PlatformIdentifier name="cache-directory-path" /> 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.

</ConfigKey>

<ConfigKey name="shutdown-timeout">

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.

</ConfigKey>

## Tracing Options

<ConfigKey name="enable-tracing">

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.

</ConfigKey>

<ConfigKey name="traces-sample-rate">

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 <PlatformIdentifier name="traces-sampler" /> must be defined to enable tracing.

</ConfigKey>

<ConfigKey name="traces-sampler">

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 <PlatformIdentifier name="traces-sample-rate" /> must be defined to enable tracing.

</ConfigKey>
77 changes: 77 additions & 0 deletions docs/platforms/powershell/configuration/releases.mdx
Original file line number Diff line number Diff line change
@@ -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 <PlatformLink to="/configuration/environments/">environment</PlatformLink>. 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, `[email protected]+1234`)
- `package` is the unique identifier of the project/app
- `version` is the semver-like structure `<major>.<minor?>.<patch?>.<revision?>-<prerelease?>`
- `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.

<Note>

Releases are global per organization; prefix them with something project-specific for easy differentiation.

</Note>

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

<PlatformContent includePath="set-release" notateUnsupported />

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.
vaind marked this conversation as resolved.
Show resolved Hide resolved

<Note>

Crash reporting and app hang detection are not available for watchOS.

</Note>

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.

<PlatformContent includePath="configuration/auto-session-tracking" />
Loading
Loading