more docs

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).
+
+<Alert level="" title="Learn about SDK usage">
+
+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/).
+
+</Alert>
+
+## 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:
+
+<PlatformContent includePath="enriching-events/breadcrumbs/breadcrumbs-example" />
+
+## Customize Breadcrumbs
+
+SDKs allow you to customize breadcrumbs through the <PlatformIdentifier name="before-breadcrumb" /> 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`:
+
+<PlatformContent includePath="enriching-events/breadcrumbs/before-breadcrumb" />

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)
+
+<Note>
+
+If you need to be able to search on custom data, [use tags](../tags) instead.
+
+</Note>
+
+## 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:
+
+<PlatformContent includePath="enriching-events/set-context" />
+
+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 <PlatformIdentifier name="set-extra" />.

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:
+
+<DefinitionList>
+
+### `id`
+
+<Note>
+
+If you don't provide an `id`, the SDK falls back to `installationId`, which the SDK randomly generates once during an app's installation.
+
+</Note>
+
+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 <PlatformIdentifier name="send-default-pii" /> 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.
+
+</DefinitionList>
+
+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:
+
+<PlatformContent includePath="enriching-events/set-user" />
+
+You can also clear the currently set user:
+
+<PlatformContent includePath="enriching-events/unset-user" />

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 <PlatformIdentifier name="configure-scope" /> at any point in
+time to modify data stored on the scope. This is useful for doing things like
+[modifying the context](../context/).
+
+<Alert>
+
+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.
+
+</Alert>
+
+When you call a global function such as <PlatformIdentifier name="capture-event" /> 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 <PlatformIdentifier name="configure-scope" /> 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.
+
+<PlatformContent includePath="enriching-events/scopes/configure-scope" />
+
+You can also apply this configuration when unsetting a user at logout:
+
+<PlatformContent includePath="enriching-events/unset-user" />
+
+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 <PlatformIdentifier name="with-scope" />, <PlatformIdentifier name="push-scope" /> 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:
+
+<PlatformContent includePath="enriching-events/scopes/scope-callback-param" />
+
+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.
+
+<Alert level="info" title="Important">
+
+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.
+
+</Alert>

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
+        });
+}
+```

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' }
+```

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 = '[email protected]'
+}
+```

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
+}
+```

platform-includes/enriching-events/set-context/powershell.mdx

@@ -0,0 +1,9 @@
+```powershell
+Edit-SentryScope {
+    $_.Contexts['character'] = @{
+        Name       = 'Mighty Fighter'
+        Age        = 19
+        AttackType = 'melee'
+    };
+}
+```

platform-includes/enriching-events/set-user/powershell.mdx

@@ -0,0 +1,6 @@
+```powershell
+Edit-SentryScope {
+    $_.User.Id = '42'
+    $_.User.Email = '[email protected]'
+}
+```

platform-includes/enriching-events/unset-user/powershell.mdx

@@ -0,0 +1,5 @@
+```powershell
+Edit-SentryScope {
+    $_.User = $null
+}
+```