Skip to content

Commit 5cb8c88

Browse files
vaindvaind
authored
feat: PowerShell (#9198)
1 parent 541d8ad commit 5cb8c88

File tree

72 files changed

+1589
-6
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+1589
-6
lines changed

‎docs/platforms/powershell/configuration/draining.mdx

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Shutdown and Draining
3+
sidebar_order: 70
4+
description: "Learn more about the default behavior of our SDK if the application shuts down unexpectedly."
5+
---
6+
7+
The default behavior of most SDKs is to send out events over the network
8+
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.
9+
10+
<PlatformContent includePath="configuration/drain-example" />

‎docs/platforms/powershell/configuration/environments.mdx

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Environments
3+
sidebar_order: 30
4+
description: "Learn how to configure your SDK to tell Sentry about your environments."
5+
---
6+
7+
Environments tell you where an error occurred, whether that's in your production system, your staging server, or elsewhere.
8+
9+
Sentry automatically creates an environment when it receives an event with the `environment` parameter set.
10+
11+
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.
12+
13+
<PlatformContent includePath="set-environment" />
14+
15+
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/).

‎docs/platforms/powershell/configuration/filtering.mdx

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Filtering
3+
description: "Learn more about how to configure your SDK to filter events reported to Sentry."
4+
sidebar_order: 60
5+
---
6+
7+
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.
8+
9+
The Sentry SDKs have several configuration options to help you filter out events.
10+
11+
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/).
12+
13+
## Filtering Error Events
14+
15+
Configure your SDK to filter error events by using the <PlatformIdentifier name="before-send" /> callback method and configuring, enabling, or disabling integrations.
16+
17+
### Using <PlatformIdentifier name="before-send" />
18+
19+
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.
20+
21+
<PlatformContent includePath="configuration/before-send/" />
22+
23+
Note also that breadcrumbs can be filtered, as discussed in [our Breadcrumbs documentation](/product/error-monitoring/breadcrumbs/).
24+
25+
## Filtering Transaction Events
26+
27+
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.
28+
29+
### Using <PlatformIdentifier name="traces-sampler" />
30+
31+
**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.
32+
33+
In its simplest form, used just for filtering the transaction, it looks like this:
34+
35+
<PlatformContent includePath="performance/traces-sampler-as-filter" />
36+
37+
It also allows you to sample different transactions at different rates.
38+
39+
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.
40+
41+
Learn more about <PlatformLink to="/configuration/sampling/">configuring the sample rate</PlatformLink>.
42+
43+
### Using <PlatformIdentifier name="before-send-transaction" />
44+
45+
<PlatformContent includePath="configuration/before-send-transaction" />

‎docs/platforms/powershell/configuration/index.mdx

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Configuration
3+
description: "Additional configuration options for the SDK."
4+
sidebar_order: 5
5+
---
6+
7+
<PageGrid />

‎docs/platforms/powershell/configuration/options.mdx

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: Basic Options
3+
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."
4+
sidebar_order: 1
5+
---
6+
7+
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
8+
initialized.
9+
10+
<PlatformContent includePath="configuration/config-intro" />
11+
12+
## Common Options
13+
14+
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.
15+
16+
<ConfigKey name="dsn">
17+
18+
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.
19+
20+
In runtimes without a process environment (such as the browser) that fallback does not apply.
21+
22+
Learn more about [DSN utilization](/product/sentry-basics/dsn-explainer/#dsn-utilization).
23+
24+
</ConfigKey>
25+
26+
<ConfigKey name="is-global-mode-enabled">
27+
28+
Specifies whether to use global scope management mode. Should be `true` for client applications and `false` for server applications.
29+
30+
Defaults to `true` for PowerShell.
31+
32+
</ConfigKey>
33+
34+
<ConfigKey name="debug">
35+
36+
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.
37+
38+
</ConfigKey>
39+
40+
<ConfigKey name="diagnostic-level">
41+
42+
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:
43+
44+
- `debug`: **default** The most verbose mode
45+
- `info`: Informational messages
46+
- `warning`: Warning that something might not be right
47+
- `error`: Only SDK internal errors are printed
48+
- `fatal`: Only critical errors are printed
49+
50+
</ConfigKey>
51+
52+
<ConfigKey name="dist">
53+
54+
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.
55+
56+
</ConfigKey>
57+
58+
<ConfigKey name="release">
59+
60+
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>.
61+
62+
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).
63+
64+
</ConfigKey>
65+
66+
<ConfigKey name="environment">
67+
68+
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).
69+
70+
By default, the SDK reports `debug` when the debugger is attached. Otherwise, the default environment is `production`.
71+
72+
</ConfigKey>
73+
74+
<ConfigKey name="sample-rate">
75+
76+
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.
77+
78+
</ConfigKey>
79+
80+
<ConfigKey name="max-breadcrumbs">
81+
82+
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.
83+
84+
</ConfigKey>
85+
86+
<ConfigKey name="max-cache-items">
87+
88+
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`.
89+
90+
</ConfigKey>
91+
92+
<ConfigKey name="attach-stacktrace">
93+
94+
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.
95+
96+
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.
97+
98+
</ConfigKey>
99+
100+
<ConfigKey name="send-default-pii">
101+
102+
If this flag is enabled, certain personally identifiable information (PII) is added by active integrations. By default, no such data is sent.
103+
104+
<Note>
105+
106+
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.
107+
108+
</Note>
109+
110+
This option is turned off by default.
111+
112+
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/).
113+
114+
</ConfigKey>
115+
116+
<ConfigKey name="send-client-reports">
117+
118+
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.
119+
120+
</ConfigKey>
121+
122+
## Hooks
123+
124+
These options can be used to hook the SDK in various ways to customize the reporting of events.
125+
126+
<ConfigKey name="before-send">
127+
128+
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.
129+
130+
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.
131+
132+
</ConfigKey>
133+
134+
<ConfigKey name="before-breadcrumb">
135+
136+
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.
137+
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.
138+
139+
</ConfigKey>
140+
141+
## Transport Options
142+
143+
Transports are used to send events to Sentry. Transports can be customized to some degree to better support highly specific deployments.
144+
145+
<ConfigKey name="transport">
146+
147+
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.
148+
149+
</ConfigKey>
150+
151+
<ConfigKey name="init-cache-flush-timeout">
152+
153+
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.
154+
155+
The default is `1` (one) second.
156+
157+
</ConfigKey>
158+
159+
<ConfigKey name="shutdown-timeout">
160+
161+
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.
162+
163+
</ConfigKey>
164+
165+
## Tracing Options
166+
167+
<ConfigKey name="enable-tracing">
168+
169+
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.
170+
171+
</ConfigKey>
172+
173+
<ConfigKey name="traces-sample-rate">
174+
175+
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.
176+
177+
</ConfigKey>
178+
179+
<ConfigKey name="traces-sampler">
180+
181+
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.
182+
183+
</ConfigKey>

‎docs/platforms/powershell/configuration/releases.mdx

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Releases & Health
3+
description: "Learn how to configure your SDK to tell Sentry about your releases."
4+
sidebar_order: 40
5+
---
6+
7+
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:
8+
9+
- Determine issues and regressions introduced in a new release
10+
- Predict which commit caused an issue and who is likely responsible
11+
- Resolve issues by including the issue number in your commit message
12+
- Receive email notifications when your code gets deployed
13+
14+
## Bind the Version
15+
16+
Include a release ID (often called a "version") when you initialize the SDK.
17+
18+
The release name cannot:
19+
20+
- contain newlines, tabulator characters, forward slashes(`/`) or back slashes(`\`)
21+
- be (in their entirety) period (`.`), double period (`..`), or space ( )
22+
- exceed 200 characters
23+
24+
The value can be arbitrary, but we recommend either of these naming strategies:
25+
26+
- **Semantic Versioning**: `package@version` or `package@version+build` (for example, `[email protected]+1234`)
27+
- `package` is the unique identifier of the project/app
28+
- `version` is the semver-like structure `<major>.<minor?>.<patch?>.<revision?>-<prerelease?>`
29+
- `build` is the number that identifies an iteration of your app
30+
- **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.
31+
32+
<Note>
33+
34+
Releases are global per organization; prefix them with something project-specific for easy differentiation.
35+
36+
</Note>
37+
38+
The behavior of a few features depends on whether a project is using semantic or time-based versioning.
39+
40+
- Regression detection
41+
- `release:latest`
42+
43+
We automatically detect whether a project is using semantic or time-based versioning based on:
44+
45+
- If ≤ 2 releases total: we look at most recent release.
46+
- If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver.
47+
- 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.
48+
49+
## Setting a Release
50+
51+
<PlatformContent includePath="set-release" notateUnsupported />
52+
53+
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.
54+
55+
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.
56+
57+
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.
58+
59+
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.
60+
61+
## Release Health
62+
63+
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.
64+
65+
<Note>
66+
67+
Crash reporting and app hang detection are not available for watchOS.
68+
69+
</Note>
70+
71+
In order to monitor release health, the SDK sends session data.
72+
73+
### Sessions
74+
75+
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.
76+
77+
<PlatformContent includePath="configuration/auto-session-tracking" />

0 commit comments

Comments
 (0)