Update: Performance Docs (#1801)

MimiDumpling · web-flow · commit c703d8087dbb · 2020-06-30T17:17:40.000-07:00
Performance docs need a few more details before GA
diff --git a/__tests__/__snapshots__/documentation.js.snap b/__tests__/__snapshots__/documentation.js.snap
@@ -285,11 +285,11 @@ Array [
   "performance-monitoring/discover-queries/index.html",
   "performance-monitoring/discover-queries/query-builder/index.html",
   "performance-monitoring/distributed-tracing/index.html",
+  "performance-monitoring/getting-started/index.html",
   "performance-monitoring/performance/event-detail/index.html",
   "performance-monitoring/performance/index.html",
   "performance-monitoring/performance/metrics/index.html",
   "performance-monitoring/performance/transaction-summary/index.html",
-  "performance-monitoring/setup/index.html",
   "platforms/android/index.html",
   "platforms/android/migrate/index.html",
   "platforms/cocoa/dsym/index.html",
diff --git a/nginx.conf b/nginx.conf
@@ -527,6 +527,10 @@ server {
   location = /guides/manage-event-stream/ {
     return 302 /accounts/quotas/manage-event-stream-guide/;
   }
+  
+  location = /performance-monitoring/setup/ {
+    return 302 /performance-monitoring/getting-started/;
+  }
 
   # these should match what is in server.js
   location ~ ^/(platforms|clients|error-reporting|enriching-error-data|performance-monitoring|workflow|data-management|accounts|cli|api|guides|support|sdks)/ {
diff --git a/src/_data/platforms.yml b/src/_data/platforms.yml
@@ -3,7 +3,7 @@
       support_level: production
       type: framework
       name: Node.js
-      doc_link: /performance-monitoring/setup/?platform=node
+      doc_link: /performance-monitoring/getting-started/?platform=node
       wizard_parent: node
       wizard:
         - _documentation/performance-monitoring/configuration/node.md#node-tracing
@@ -173,7 +173,7 @@
       support_level: production
       type: language
       name: Python
-      doc_link: /performance-monitoring/setup/?platform=python
+      doc_link: /performance-monitoring/getting-started/?platform=python
       wizard_parent: python
       wizard:
             - _documentation/performance-monitoring/configuration/python.md#python-tracing
diff --git a/src/collections/_documentation/performance-monitoring/configuration/javascript.md b/src/collections/_documentation/performance-monitoring/configuration/javascript.md
@@ -172,3 +172,88 @@ function processItem(item, transaction) {
   });
 }
 ```
+
+**Grouping Transactions**
+
+When Sentry captures transactions, they are assigned a transaction name. This name is generally auto-generated by the Sentry SDK based on the framework integrations you are using. If you can't leverage the automatic transaction generation (or want to customize how transaction names are generated) you can use a global event processor that is registered when you initialize the SDK with your configuration.
+
+An example of doing this in a node.js application:
+
+```javascript
+import { addGlobalEventProcessor } from '@sentry/node';
+
+addGlobalEventProcess(event => {
+  // if event is a transaction event
+  if (event.type === "transaction") {
+	event.transaction = sanitizeTransactionName(event.transaction);
+  }
+  return event;
+});
+```
+
+For browser JavaScript applications using the `Tracing` integration, the `beforeNavigate` option  can be used to better group navigation/pageload transactions together based on URL.
+
+```javascript
+import * as Sentry from '@sentry/browser';
+import { Integrations as ApmIntegrations } from '@sentry/apm';
+
+Sentry.init({
+	// ...
+  integrations: [
+    new ApmIntegrations.Tracing({
+      beforeNavigate: (location) => {        
+        // You could use your UI's routing library to find the matching
+		    // route template here. We don't have one right now, so do some basic
+		    // parameter replacements.
+        return location.pathname
+        .replace(/\d+/g, '<digits>')
+        .replace(/[a-f0-9]{32}/g, '<hash>');
+      },
+    }),
+  ],
+});
+```
+
+**Adding Query Information and Parameters to Spans**
+
+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`
+
+Instead, using `span.setTag` splits the details of this request over several tags. This could be done over `baseUrl`, `endpoint`, `parameters`, in this case, resulting in three different tags:
+
+```javascript
+const span = transaction.startChild({
+  op: "request",
+  description: "setup form"
+});
+span.setTag("baseUrl", baseUrl);
+span.setTag("endpoint", endpoint);
+span.setTag("parameters", parameters);
+http.get(`${base_url}/${endpoint}/`, data=parameters);
+...
+```
+
+baseUrl
+
+: `https://empowerplant.io`
+
+endpoint
+
+: `api/0/projects/ep/setup_form`
+
+parameters
+
+: ```{
+"user_id": 314159265358979323846264338327,
+"tracking_id": "EasyAsABC123OrSimpleAsDoReMi",
+"product_name": PlantToHumanTranslator,
+"product_id": 161803398874989484820458683436563811772030917980576,
+}
+```
diff --git a/src/collections/_documentation/performance-monitoring/configuration/python.md b/src/collections/_documentation/performance-monitoring/configuration/python.md
@@ -4,15 +4,13 @@ hide_from_sidebar: true
 
 To get started with performance monitoring using Sentry's Python SDK, first install the `sentry_sdk` package:
 
-```
-$ pip install sentry_sdk
+```python
+import sentry_sdk
 ```
 
 Next, initialize the integration in your call to `sentry_sdk.init`:
 
 ```python
-import sentry_sdk
-
 sentry_sdk.init(
     "___PUBLIC_DSN___", 
     traces_sample_rate = 0.25
@@ -101,3 +99,51 @@ def process_item(item):
 ```
 
 <!-- ENDWIZARD -->
+
+**Adding Query Information and Parameters to Spans**
+
+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`
+
+Instead, using `span.set_tag` splits the details of this query over several tags. This could be done over `base_url`, `endpoint`, `parameters`, in this case, resulting in three different tags:
+```python
+import sentry_sdk
+...
+with sentry_sdk.start_span(op="request", transaction="setup form") as span:
+    span.set_tag("base_url", base_url)
+    span.set_tag("endpoint", endpoint)
+    span.set_tag("parameters", parameters)
+    make_request(
+        "{base_url}/{endpoint}/".format(
+            base_url=base_url,
+            endpoint=endpoint,
+        ),
+        data=parameters
+    )
+    ...
+```
+
+baseUrl
+
+: `https://empowerplant.io`
+
+endpoint
+
+: `api/0/projects/ep/setup_form`
+
+parameters
+
+: ```{
+"user_id": 314159265358979323846264338327,
+"tracking_id": "EasyAsABC123OrSimpleAsDoReMi",
+"product_name": PlantToHumanTranslator,
+"product_id": 161803398874989484820458683436563811772030917980576,
+}
+```
diff --git a/src/collections/_documentation/performance-monitoring/getting-started.md b/src/collections/_documentation/performance-monitoring/getting-started.md
@@ -1,5 +1,5 @@
 ---
-title: Setup
+title: Getting Started
 sidebar_order: 0
 ---
 
diff --git a/src/collections/_documentation/performance-monitoring/performance/event-detail.md b/src/collections/_documentation/performance-monitoring/performance/event-detail.md
@@ -10,7 +10,7 @@ From [Performance](/performance-monitoring/performance/index) and [Discover](/pe
 Information about this specific event is located in the sidebar, listing out the Event ID, date and time of occurrence, project, and downloadable JSON package. More can be found under Event Tag Details. You'll also get a breakdown of operations, which will correspond to the waterfall span view as a legend.
 
 {% capture __alert_content -%}
-Currently, only root transactions are searchable. Any span data that inherits from it's root are not. 
+Currently, only root transactions are searchable. Any span data that inherits from its root are not. 
 {%- endcapture -%}
 {%- include components/alert.html
     title="Warning"
@@ -20,20 +20,30 @@ Currently, only root transactions are searchable. Any span data that inherits fr
 
 ## Span View
 
+The span view is a split view where the left-hand side shows the transaction’s span tree, and the right-hand side represents each span as a colored rectangle. Within the tree view, Sentry identifies spans by their `op` and `description` values. If a span doesn’t have a description, Sentry uses the span’s id as a fallback. The first span listed is always the transaction’s root span, from which all other spans in the transaction descend.
+
 [{% asset performance/span-details.png alt="Span detail view shows the span id, trace id, parent span id, and other data such as tags." %}]({% asset performance/span-details.png @path %})
 
+To find these views, you can either go through the [Transaction Summary](/performance-monitoring/performance/transaction-summary) or [Query Builder](/performance-monitoring/discover-queries/query-builder/). Event IDs will be linked to open the corresponding Event Detail.
+
+**With Transaction Summary**
+
+Select the [Performance Homepage](/performance-monitoring/performance/index), then click the affected transaction to display the trace data.
+
+**With Query Builder**
+
+Scroll down to the "Trace Details" context panel in either the Issue Details or the Discover Event Details page, and click on the "View Summary" button. This will maintain the context of the current Sentry event.
+
+_Note_: Users on the Team or Business plans can also view a list of transaction events by clicking on the "Transactions" pre-built query in [Discover](/performance-monitoring/discover-queries/index) or by performing a search with the `event.type:transaction` condition the Discover Query Builder view.
+
 ### Minimap
 
-The minimap reflects the entirety of the transaction broken into spans. You can either click and drag your cursor across the minimap to zoom in or adjust the window selection by dragging the handlebar in from the side. This will affect the range you see in the waterfall view. 
+The minimap (top of the span view) reflects the entirety of the transaction broken into spans. You can either click and drag your cursor across the minimap to zoom in or adjust the window selection by dragging the handlebar (black dashed lines) in from the side. This will affect the range you see in the waterfall view. 
 
 ### Waterfall
 
 The waterfall view is a split view where the left reflects the transaction's span tree, and the right reflects each span as a horizontal bar (colors represent the operation). Within the tree, Sentry identifies spans by their `operation` and `description` values. If a span doesn't have a description, Sentry uses the span's ID as a fallback. The first span listed is always the transaction's root span, from which all other spans in the transaction descend. 
 
-_Missing Instrumentation_ 
-
-Gaps between spans may be marked as "Missing Instrumentation." TThis means a duration in the transaction that isn't accounted for by any of the transaction's spans. It likely means that you need to manually instrument that part of your process. Go back to the [performance setup](/performance-monitoring/setup) for details. 
-
 ### Span Details
 
 Clicking on a span row expands the details of that span. From here, you can see all attached properties, such as tags and other field data. With the Trace ID, you'll be able to view all transactions within that given trace. Click "Search by Trace" to view that Discover list. Learn more about [distributed tracing](/performance-monitoring/distributed-tracing/) in our docs. 
@@ -49,7 +59,7 @@ The trace view may be limited to one project at a time if you're on the [Team pl
     level="info"
 %}
 
-_Traversing Transactions_
+**Traversing Transactions**
 
 Some spans within a transaction may be the parent of another transaction. Under these circumstances, some Span IDs will have a "View Child" or "View Children" button. These will potentially lead to another transaction or a list of transactions. 
 
@@ -63,3 +73,49 @@ Traversing between parent and child transactions is only available on the [Busin
     content=__alert_content
     level="info"
 %}
+
+**Adding Query Information and Parameters to Spans**
+
+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`
+
+Instead, using `span.set_tag` you could split the details of this query over several tags. This could be done over `columns`, `tables`, `conditions`, in this case, resulting in three different tags:
+
+```python
+import sentry_sdk
+
+...
+
+with sentry_sdk.start_span(op="db", transaction="query api") as span:
+    span.set_tag("columns", columns)
+    span.set_tag("tables", tables)
+    span.set_tag("conditions", conditions)
+    span.set_tag("query_format", query_format)
+    query_format = "SELECT {columns} FROM {tables} WHERE {conditions}"
+    query = query_format.format(
+        columns=columns,
+        tables=tables,
+        conditions=conditions,
+    )
+    ...
+```
+
+columns
+: `first_column, second_column, third_columns, fourth_column, fifth_column, sixth_column`
+
+tables
+: `this_is_a_long_table_name`
+
+conditions
+: `first_column=some_value AND second_column=some_other_value AND third_column=yet_another_value`
+
+### Missing Instrumentation 
+
+Gaps between spans may be marked as "Missing Instrumentation." This means a duration in the transaction that isn't accounted for by any of the transaction's spans. It likely means that you need to manually instrument that part of your process. Go back to the [performance setup](/performance-monitoring/setup) for details. 
diff --git a/src/collections/_documentation/performance-monitoring/performance/transaction-summary.md b/src/collections/_documentation/performance-monitoring/performance/transaction-summary.md
@@ -36,7 +36,9 @@ The table also updates dynamically if you change any of the selections in the gl
 
 When viewing transactions, you may want to create more curated views. Click "Open in Discover" above the table to create a custom query to investigate further. For more details, see the full documentation for the Discover [Query Builder](/performance-monitoring/discover-queries/query-builder/).
 
-## Metrics Sidebar
+_Note_: Currently, only transaction data - the transaction name and any attributes the transaction inherits from its root span - is searchable. Data contained in spans other than the root span is not indexed and therefore cannot be searched.
+
+## Related Issues
 
 The sidebar contains helpful supplementary information about this transaction's [User Misery](/performance-monitoring/performance/metrics/#user-misery), [Apdex](/performance-monitoring/performance/metrics/#apdex), [Throughput](/performance-monitoring/performance/metrics/#throughput-total-tpm-tps), [Latency](/performance-monitoring/performance/metrics/#latency), and more. You'll also find a Tag Summary (facet map) for a list of common tags related to this transaction.
 
