respond to PR comments

Author: lobsterkatie

src/components/platformSidebar.tsx

@@ -83,7 +83,9 @@ export const PlatformSidebar = ({
       <DynamicNav
         root={`/${pathRoot}/performance`}
         title="Performance Monitoring"
-        prependLinks={[[`/${pathRoot}/performance/`, "Enabling Tracing"]]}
+        prependLinks={[
+          [`/${pathRoot}/performance/`, "Enabling Performance Monitoring"],
+        ]}
         suppressMissing
         tree={tree}
       />

src/docs/product/performance/distributed-tracing.mdx

@@ -233,9 +233,9 @@ Individual spans aren't sent to Sentry; rather, the entire transaction is sent a
 
 When you enable sampling in your tracing setup, you choose a percentage of collected transactions to send to Sentry. For example, if you had an endpoint that received 1000 requests per minute, a sampling rate of `0.25` would result in approximately 250 transactions (25%) being sent to Sentry each minute. (The number is approximate because each request is either tracked or not, independently and pseudorandomly, with a 25% probability. So in the same way that 100 fair coins, when flipped, result in approximately 50 heads, the SDK will "decide" to collect a trace in approximately 250 cases.) Because you know the sampling percentage, you can then extrapolate your total traffic volume.
 
-When collecting traces, we **strongly recommend** sampling your data, for two reasons. First, though capturing a single trace involves minimal overhead, capturing traces for every single page load, or every single API request, has the potential to add an undesirable amount of load to your system. Second, by enabling sampling you'll more easily prevent yourself from exceeding your organization's [event quota](/accounts/quotas/), which will help you manage costs.
+When collecting traces, we recommend sampling your data, for two reasons. First, though capturing a single trace involves minimal overhead, capturing traces for every single page load, or every single API request, has the potential to add an undesirable amount of load to your system. Second, enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor it to your organization's needs.
 
-When choosing a sampling rate, the goal is to not collect _too_ much data (given the reasons above) but also to collect enough data that you are able to draw meaningful conclusions. If you're not sure what rate to choose, we recommend starting with a low value and gradually increasing it as you learn more about your traffic patterns and volume, until you've found a rate which lets you balance performance and cost concerns with data accuracy.
+When choosing a sampling rate, the goal is to not collect _too_ much data (given the reasons above) but also to collect enough data that you are able to draw meaningful conclusions. If you're not sure what rate to choose, we recommend starting with a low value and gradually increasing it as you learn more about your traffic patterns and volume, until you've found a rate which lets you balance performance and volume concerns with data accuracy.
 
 ### Consistency Within a Trace
 

src/includes/performance/default-sampling-context/javascript.mdx

@@ -5,7 +5,7 @@ For browser-based SDKs, it includes the following:
 {
   transactionContext: {
     name: string; // human-readable identifier, like "GET /users"
-    op: string; // short descriptor of transaction type, like "pageload"
+    op: string; // short description of transaction type, like "pageload"
   }
   parentSampled: boolean; // if this transaction has a parent, its sampling decision
   location: Location | WorkerLocation; // the window.location or self.location object

src/includes/performance/default-sampling-context/node.mdx

@@ -4,7 +4,7 @@ The information contained in the `samplingContext` object passed to the `tracesS
 {
   transactionContext: {
     name: string; // human-readable identifier, like "GET /users"
-    op: string; // short descriptor of transaction type, like "pageload"
+    op: string; // short description of transaction type, like "pageload"
   }
   parentSampled: boolean; // if this transaction has a parent, its sampling decision
   request: object // in server contexts, information about the incoming request

src/platforms/common/configuration/filtering.mdx

@@ -6,9 +6,11 @@ notSupported:
   - perl
 ---
 
-There are many reasons you might want to send every possible event to Sentry. While sending all errors ensures you’ll be notified in real-time when problems occur in your code, often applications generate many errors, and thus many notifications. Similarly, while transaction events give you a detailed look into every user's experience (not just those with problems), they also get sent by **every user**, and thus can pile up and eat through your quota very quickly.
+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.
 
-To help with those problems, the Sentry SDKs have several configuration options you can use to prevent unwanted events from getting sent to Sentry, as well as ways to send only a representative sample of those you do want.. (The Sentry UI also offers methods to filter events, which you can read more about [here](/product/error-monitoring/filtering/).)
+The Sentry SDKs have several configuration options to help you control this, allowing you to both filter out events you don't want and to take a representative sample of those you do.
+
+**Note:**: The Sentry UI also offers methods to filter events, by using [Inbound Filters](/product/error-monitoring/filtering/). We recommend filtering at the client level though, because it removes the overhead of sending events you don't actually want.
 
 ## Filtering Error Events
 
@@ -30,7 +32,7 @@ Typically a `hint` holds the original exception so that additional data can be e
 
 <PlatformContent includePath="configuration/before-send-hint" />
 
-When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from a log record or exception instance. For better customization, SDKs send these objects to certain callbacks (`before-send`, `before-breadcrumb` or the event processor system in the SDK).
+When the SDK creates an event or breadcrumb for transmission, that transmission is typically created from some sort of source object. For instance, an error event is typically created from a log record or exception instance. For better customization, SDKs send these objects to certain callbacks (`beforeSend`, `beforeBreadcrumb` or the event processor system in the SDK).
 
 ### Using Hints
 
@@ -89,17 +91,17 @@ To send a representative sample of your errors to Sentry, set the `sampleRate` o
 
 <PlatformContent includePath="configuration/sample-rate" />
 
-<Note><markdown>
-
-The error sample rate is not dynamic; changing it 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.
-
-</markdown></Note>
+**Note:** The error sample rate is not dynamic; changing it 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.
 
 <PlatformSection supported={["javascript", "node"]}><markdown>
 
 ## Filtering Transaction Events
 
-To prevent certain transactions from being reported to Sentry, use the `tracesSampler` configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. (It also allows you to sample different transactions at different rates.) In its simplest form, used just for filtering, it looks like this:
+To prevent certain transactions from being reported to Sentry, use the `tracesSampler` configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. (It also allows you to sample different transactions at different rates.)
+
+**Note:** The `tracesSampler` and `tracesSampleRate` config options are mutually exclusive. If you define a `tracesSampler` 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, it looks like this:
 
 ```javascript
 tracesSampler: samplingContext => {
@@ -111,20 +113,14 @@ tracesSampler: samplingContext => {
 };
 ```
 
-<Note><markdown>
-
-The `tracesSampler` and `tracesSampleRate` config options are mutually exclusive. If you define a `tracesSampler` in order 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.
-
-</markdown></Note>
-
 To learn more about the `tracesSampler` option, please see [Sampling Transactions](/platforms/javascript/performance/sampling/).
 
 </markdown></PlatformSection>
 
 ## Sampling Transaction Events
 
-For Sentry's Performance Monitoring, we recommend sampling your data for two reasons. First, though capturing a single trace involves minimal overhead, capturing traces for every single page load, or every single API request, has the potential to add an undesirable amount of load to your system. Second, by enabling sampling you’ll more easily prevent yourself from exceeding your organization’s [event quota](/accounts/quotas/).
+For Sentry's Performance Monitoring, we recommend sampling your data for two reasons. First, though capturing a single trace involves minimal overhead, capturing traces for every single page load, or every single API request, has the potential to add an undesirable amount of load to your system. Second, enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor it to your organization's needs.
 
-When choosing a sampling rate, the goal is not to collect *too* much data, but to collect sufficient data so you can 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, until you’ve found a rate that balances performance and cost concerns with data accuracy.
+When choosing a sampling rate, the goal is not to collect *too* much data, but to collect sufficient data so you can 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, until you’ve found a rate that balances performance and volume concerns with data accuracy.
 
 To set a sample rate for your transactions, provide a number between `0` (0% of transactions sent) and `1` (100% of transactions sent) to the `tracesSampleRate` configuration option. For example, including `tracesSampleRate: 0.2` in your SDK config will cause the SDK to only send 20% of possible transaction events.

src/platforms/javascript/common/performance/automatic.mdx

@@ -118,7 +118,7 @@ Sentry.init({
 
 ### shouldCreateSpanForRequest
 
-This function can be used to filter our unwanted Spans like XHR's running health checks or something similar. By default `shouldCreateSpanForRequest` is already filtering out what was defined in `tracingOrigins`.
+This function can be used to filter out unwanted spans such as XHR's running health checks or something similar. By default `shouldCreateSpanForRequest` already filters out everything but what was defined in `tracingOrigins`.
 
 ```javascript
 import * as Sentry from "@sentry/browser";
@@ -128,11 +128,8 @@ Sentry.init({
   integrations: [
     new Integrations.BrowserTracing({
       shouldCreateSpanForRequest: url => {
-        // Example of filter out spans that contain `health`
-        if (url.match(/health/)) {
-          return false;
-        }
-        return true;
+        // Do not create spans for outgoing requests to a `/health/` endpoint
+        return !url.match(/\/health\/?$/);
       },
     }),
   ],

src/platforms/javascript/common/performance/manual.mdx

@@ -16,7 +16,7 @@ span.finish(); // Remember that only finished spans will be sent with the transa
 transaction.finish(); // Finishing the transaction will send it to Sentry
 ```
 
-Here is a different example. If you want to create a transaction for a user interaction on your page, you need to do the following:
+For example, if you want to create a transaction for a user interaction on your page, you can do this:
 
 ```javascript
 // Let's say this function is invoked when a user clicks on the checkout button of your shop
@@ -45,15 +45,15 @@ shopCheckout() {
 
 This example will send a transaction `shopCheckout` to Sentry. The transaction will contain a `task` span that measures how long `processAndValidateShoppingCart` took. Finally, the call to `transaction.finish()` will finish the transaction and send it to Sentry.
 
-#### Adding Additional Spans to the Transaction
+You can also take advantage of promises when creating spans for async operations. Keep in mind, though, that a span must finish before `transaction.finish()` is called in order to be included in the transaction.
 
-The next example contains the implementation of the hypothetical `processItem` function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add to it all newly created spans as child operations. Keep in mind that each individual span needs to be manually finished; otherwise, that span will not show up in the transaction.
+For example:
 
 ```javascript
 function processItem(item, transaction) {
   const span = transaction.startChild({
     op: "http",
-    description: "GET /",
+    description: `GET /items/:item-id`,
   });
 
   return new Promise((resolve, reject) => {

src/platforms/javascript/common/performance/sampling.mdx

@@ -4,13 +4,13 @@ sidebar_order: 20
 description: "Learn how to configure the volume of transactions sent to Sentry."
 ---
 
-There are two ways to control the volume of transactions sent to Sentry.
+You can control the volume of transactions sent to Sentry in two ways.
 
 ## Uniform Sample Rate
 
 Setting a uniform sample rate is a good option if you want an even cross-section of transactions, no matter where in your app or under what circumstances they occur, and are happy with the default inheritance and precedence behavior described below.
 
-To do this, set the `tracesSampleRate` option in your `Sentry.init()` to a number between 0 and 1, and every transaction created will have that percentage chance of being sent to Sentry. (So, for example, if you set `tracesSampleRate` to `0.2`, approximately 20% of your transactions will get recorded and sent.) That looks like this:
+To do this, set the `tracesSampleRate` option in your `Sentry.init()` 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 `tracesSampleRate` to `0.2`, approximately 20% of your transactions will get recorded and sent.) That looks like this:
 
 ```javascript {tabTitle: ESM}
 // If you're using one of our integration packages, like `@sentry/react` or `@sentry/angular`,
@@ -50,13 +50,13 @@ Sentry.init({
 
 ## Dynamic Sampling Function
 
-Providing a sampling function is a good option if you
+Providing a sampling function is a good option if you:
 
 - want to sample different transactions at different rates
 - want to filer out some transactions entirely
 - want to modify the default precedence and inheritance behavior described below
 
-To sample dynamically, set the `tracesSampler` option in your `Sentry.init()` to a function which will accept a `samplingContext` object and return a sample rate between 0 and 1. For example:
+To sample dynamically, set the `tracesSampler` option in your `Sentry.init()` to a function that will accept a `samplingContext` object and return a sample rate between 0 and 1. For example:
 
 ```javascript
 tracesSampler: samplingContext => {
@@ -75,7 +75,7 @@ tracesSampler: samplingContext => {
 };
 ```
 
-For convenience, the function can also return a boolean. Returning `true` is equivalent to returning `1`, and will guarantee the transaction will be sent to Sentry. Returning `false` is equivalent to returning `0` and will guarantee the transaction witll **not** be sent to Sentry.
+For convenience, the function can also return a boolean. Returning `true` is equivalent to returning `1`, and will guarantee the transaction will be sent to Sentry. Returning `false` is equivalent to returning `0` and will guarantee the transaction will **not** be sent to Sentry.
 
 ### Default Sampling Context Data
 
@@ -132,9 +132,9 @@ There are multiple ways for a transaction to end up with a sampling decision.
 - If the transaction has a parent, inheriting its parent's sampling decision
 - Absolute decision passed to `startTransaction`
 
-When there's the potential for more than one of these to come into play, the decision is resolved according to the following precedence rules:
+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 `startTransaction` (`startTransaction({name: "my transaction", sampled: true})`), that decision will be used, regardlesss of anything else
 2. If `tracesSampleRate` is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, or use the sampling context data to make its own decision or choose a sample rate for the transaction.
-3. If `tracesSampler` is not defined, but there's a parent sampling decision, it will be used.
+3. If `tracesSampler` is not defined, but there's a parent sampling decision, the parent sampling decision will be used.
 4. If `tracesSampler` is not defined and there's no parent sampling decision, `tracesSampleRate` will be used.

src/platforms/javascript/index.mdx

@@ -125,7 +125,7 @@ Sentry.init({
 });
 ```
 
-Performance data is transmitted using a new event type called “transactions,” which you can learn about in [Distributed Tracing](/product/performance/distributed-tracing/). To begin capturing transactions, install the tracing package and set either `tracesSampleRate` or `tracesSampler` in your [SDK configuration](/platforms/javascript/configuration/options/#common-options). These determine what percentage of potential transactions get sent to Sentry; we recommend capturing only a sample to avoid consuming your quota too quickly.
+Performance data is transmitted using a new event type called “transactions,” which you can learn about in [Distributed Tracing](/product/performance/distributed-tracing/). To begin capturing transactions, install the tracing package and set either `tracesSampleRate` or `tracesSampler` in your [SDK configuration](/platforms/javascript/configuration/options/#common-options). These determine what percentage of potential transactions get sent to Sentry; we recommend capturing only a sample, as one way to adjust your overall Sentry volume to meet your needs.
 
 Learn more about `tracesSampleRate` and `tracesSampler` in [Sampling Transactions](/performance/sampling).