From d4b0d53a1da7453281a2402e90a1a4574e7922a7 Mon Sep 17 00:00:00 2001
From: Abhijeet Prasad <aprasad@sentry.io>
Date: Tue, 12 Jul 2022 14:17:45 -0400
Subject: [PATCH] feat(perf): Add Performance Metrics Docs

Adds documentation around automatic and custom performance metrics.
---
 .../javascript.mdx                            |  9 ++
 .../custom-performance-metrics/javascript.mdx | 14 ++++
 .../instrumentation/performance-metrics.mdx   | 84 +++++++++++++++++++
 3 files changed, 107 insertions(+)
 create mode 100644 src/includes/performance/automatic-performance-metrics/javascript.mdx
 create mode 100644 src/includes/performance/custom-performance-metrics/javascript.mdx
 create mode 100644 src/platforms/common/performance/instrumentation/performance-metrics.mdx

diff --git a/src/includes/performance/automatic-performance-metrics/javascript.mdx b/src/includes/performance/automatic-performance-metrics/javascript.mdx
new file mode 100644
index 0000000000000..76d26e0658c1d
--- /dev/null
+++ b/src/includes/performance/automatic-performance-metrics/javascript.mdx
@@ -0,0 +1,9 @@
+The JavaScript Browser SDKs automatically collect the following performance metrics
+
+- First Paint: `fp`
+- First Contentful Paint: `fcp`
+- Larget Contentful Paint: `lcp`
+- First Input Delay: `fcp`
+- Cumulative Layout Shift: `cls`
+- Time to First Byte: `ttfb`
+- Time to First Byte Request Time: `ttfb.requesttime`
diff --git a/src/includes/performance/custom-performance-metrics/javascript.mdx b/src/includes/performance/custom-performance-metrics/javascript.mdx
new file mode 100644
index 0000000000000..f0fbe670e3ad8
--- /dev/null
+++ b/src/includes/performance/custom-performance-metrics/javascript.mdx
@@ -0,0 +1,14 @@
+Supported in Sentry's JavaScript SDK version `7.0.0` and above.
+
+```javascript
+const transaction = Sentry.getCurrentHub().getScope().getTransaction();
+
+// Record amount of memory used
+transaction.setMeasurement('memoryUsed', 123, 'byte');
+
+// Record time when Footer component renders on page
+transaction.setMeasurement('ui.footerComponent.render', 1.3, 'second');
+
+// Record amount of times localStorage was read
+transaction.setMeasurement('localStorageRead', 4);
+```
diff --git a/src/platforms/common/performance/instrumentation/performance-metrics.mdx b/src/platforms/common/performance/instrumentation/performance-metrics.mdx
new file mode 100644
index 0000000000000..dd575da3cf1b0
--- /dev/null
+++ b/src/platforms/common/performance/instrumentation/performance-metrics.mdx
@@ -0,0 +1,84 @@
+---
+title: Performance Metrics
+sidebar_order: 20
+supported:
+  - javascript
+notSupported:
+  - javascript.cordova
+  - javascript.electron
+  - react-native
+  - dotnet
+  - python
+  - go
+  - java
+  - android
+  - ruby
+  - java.spring-boot
+  - apple
+  - unity
+  - dart
+  - flutter
+  - rust
+  - native
+  - php
+  - native.breakpad
+  - native.crashpad
+  - native.minidumps
+  - unreal
+  - native.wasm
+description: "Learn how to attach performance metrics to your transactions."
+---
+
+The Sentry SDK supports sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry.
+
+<PlatformContent includePath="performance/automatic-performance-metrics" />
+
+In addition to automatic performance metrics, the SDK supports setting custom performance metrics on transactions. This allows you to define metrics that are important to your application and send them to Sentry.
+
+To set a performance metric, supply a name (string), value (numeric - float, integer, etc.), and unit (string). Sentry supports adding arbitrary custom units, but we recommend using one of the [supported units listed below](./#supported-performance-metric-units).
+
+<PlatformContent includePath="performance/custom-performance-metrics" />
+
+## Supported Performance Metric Units
+
+Units augment metric values by giving them a magnitude and semantics. Sentry leverages units associated with performance metrics to apply built-in unit conversions and controls in the product. For values that are unitless, you can supply an empty string or `none`.
+
+### Duration Units
+
+A time duration.
+
+- `nanosecond`
+- `microsecond`
+- `millisecond`
+- `second`
+- `minute`
+- `hour`
+- `day`
+- `week`
+
+### Information Units
+
+Size of information derived from bytes.
+
+- `bit`
+- `byte`
+- `kilobyte`
+- `kibibyte`
+- `megabyte`
+- `mebibyte`
+- `gigabyte`
+- `gibibyte`
+- `terabyte`
+- `tebibyte`
+- `petabyte`
+- `petabyte`
+- `pebibyte`
+- `exabyte`
+- `exbibyte`
+
+## Fraction Units
+
+- `ratio`
+- `percent`
+
+For those looking to explore further, details about the supported list of units can be found in our [event ingestion documentation](https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html).