From d4b0d53a1da7453281a2402e90a1a4574e7922a7 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 12 Jul 2022 14:17:45 -0400 Subject: [PATCH 1/4] 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 00000000000000..76d26e0658c1db --- /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 00000000000000..f0fbe670e3ad85 --- /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 00000000000000..dd575da3cf1b09 --- /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. + + + +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). + + + +## 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). From 5f76b9b809d0372d6062c7361667a07a5b3c1dd5 Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Mon, 18 Jul 2022 13:17:53 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- .../automatic-performance-metrics/javascript.mdx | 6 +++--- .../performance/instrumentation/performance-metrics.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/includes/performance/automatic-performance-metrics/javascript.mdx b/src/includes/performance/automatic-performance-metrics/javascript.mdx index 76d26e0658c1db..f47e9614f632f0 100644 --- a/src/includes/performance/automatic-performance-metrics/javascript.mdx +++ b/src/includes/performance/automatic-performance-metrics/javascript.mdx @@ -1,9 +1,9 @@ -The JavaScript Browser SDKs automatically collect the following performance metrics +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` +- Largest Contentful Paint: `lcp` +- First Input Delay: `fid` - Cumulative Layout Shift: `cls` - Time to First Byte: `ttfb` - Time to First Byte Request Time: `ttfb.requesttime` diff --git a/src/platforms/common/performance/instrumentation/performance-metrics.mdx b/src/platforms/common/performance/instrumentation/performance-metrics.mdx index dd575da3cf1b09..6c4ff05d0096a9 100644 --- a/src/platforms/common/performance/instrumentation/performance-metrics.mdx +++ b/src/platforms/common/performance/instrumentation/performance-metrics.mdx @@ -29,7 +29,7 @@ notSupported: 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. +Sentry's SDKs support sending performance metrics data to Sentry. These are numeric values attached to transactions that are aggregated and displayed in Sentry. @@ -41,7 +41,7 @@ To set a performance metric, supply a name (string), value (numeric - float, int ## 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`. +Units augment metric values by giving meaning to what otherwise might be abstract numbers. Adding units also allows Sentry to offer controls - unit conversions, filters, etc. - based on those units. For values that are unitless, you can supply an empty string or `none`. ### Duration Units @@ -81,4 +81,4 @@ Size of information derived from bytes. - `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). +If you want to explore further, you can find details about supported units in our [event ingestion documentation](https://getsentry.github.io/relay/relay_metrics/enum.MetricUnit.html). From 45dfe1a711ccf98ba1bde60010644cd511a3e1db Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Mon, 18 Jul 2022 13:29:12 -0700 Subject: [PATCH 3/4] Apply suggestions from code review --- .../instrumentation/performance-metrics.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/platforms/common/performance/instrumentation/performance-metrics.mdx b/src/platforms/common/performance/instrumentation/performance-metrics.mdx index 6c4ff05d0096a9..46dec1750a2de3 100644 --- a/src/platforms/common/performance/instrumentation/performance-metrics.mdx +++ b/src/platforms/common/performance/instrumentation/performance-metrics.mdx @@ -35,7 +35,12 @@ Sentry's SDKs support sending performance metrics data to Sentry. These are nume 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). +To set a performance metric, you need to supply the following: +- name (`string`) +- value (any numeric type - `float`, `integer`, etc.) +- unit (`string`, can be empty or the string `'none'`). + +Sentry supports adding arbitrary custom units, but we recommend using one of the [supported units listed below](./#supported-performance-metric-units). @@ -45,8 +50,6 @@ Units augment metric values by giving meaning to what otherwise might be abstrac ### Duration Units -A time duration. - - `nanosecond` - `microsecond` - `millisecond` @@ -58,8 +61,6 @@ A time duration. ### Information Units -Size of information derived from bytes. - - `bit` - `byte` - `kilobyte` From 4a3e8385e23687a5e856b69f28eafb7411981de4 Mon Sep 17 00:00:00 2001 From: Katie Byers Date: Tue, 19 Jul 2022 11:36:03 -0700 Subject: [PATCH 4/4] Add warning about consistent metrics --- .../performance/instrumentation/performance-metrics.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/platforms/common/performance/instrumentation/performance-metrics.mdx b/src/platforms/common/performance/instrumentation/performance-metrics.mdx index 46dec1750a2de3..730e6290cc3e1b 100644 --- a/src/platforms/common/performance/instrumentation/performance-metrics.mdx +++ b/src/platforms/common/performance/instrumentation/performance-metrics.mdx @@ -44,6 +44,12 @@ Sentry supports adding arbitrary custom units, but we recommend using one of the + + +For the moment, unit conversion is only supported once the data has already been stored. This means that, for example, `('myMetric', 60, 'second')` and `('myMetric', 3, 'minute')` would not be aggregated, but rather stored as two separate metrics. To avoid this, make sure to use a consistent unit when recording a custom metric. + + + ## Supported Performance Metric Units Units augment metric values by giving meaning to what otherwise might be abstract numbers. Adding units also allows Sentry to offer controls - unit conversions, filters, etc. - based on those units. For values that are unitless, you can supply an empty string or `none`.