From d4bf6d66d66ff26f4de6ada51636920a9e81ed62 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Tue, 29 Aug 2023 12:16:46 -0400 Subject: [PATCH 1/5] feat(js): Document new performance APIs --- .../add-active-span/javascript.mdx | 9 ++++ .../performance/add-active-span/node.mdx | 9 ++++ .../add-independent-span/javascript.mdx | 17 +++++++ .../performance/add-independent-span/node.mdx | 17 +++++++ .../add-spans-example/javascript.mdx | 2 +- .../enable-manual-instrumentation/apple.mdx | 2 + .../enable-manual-instrumentation/dart.mdx | 2 + .../enable-manual-instrumentation/dotnet.mdx | 2 + .../enable-manual-instrumentation/go.mdx | 2 + .../enable-manual-instrumentation/java.mdx | 2 + .../java.spring-boot.mdx | 2 + .../java.spring.mdx | 2 + .../javascript.mdx | 2 + .../enable-manual-instrumentation/native.mdx | 2 + .../enable-manual-instrumentation/php.mdx | 2 + .../enable-manual-instrumentation/python.mdx | 2 + .../enable-manual-instrumentation/ruby.mdx | 2 + .../enable-manual-instrumentation/rust.mdx | 2 + .../performance/get-span/javascript.mdx | 15 ++++++ .../performance/get-span/node.mdx | 15 ++++++ .../span-api-version/javascript.mdx | 5 ++ .../performance/span-api-version/node.mdx | 5 ++ .../custom-instrumentation.mdx | 46 +++++++++++++++++-- 23 files changed, 162 insertions(+), 4 deletions(-) create mode 100644 src/platform-includes/performance/add-active-span/javascript.mdx create mode 100644 src/platform-includes/performance/add-active-span/node.mdx create mode 100644 src/platform-includes/performance/add-independent-span/javascript.mdx create mode 100644 src/platform-includes/performance/add-independent-span/node.mdx create mode 100644 src/platform-includes/performance/get-span/javascript.mdx create mode 100644 src/platform-includes/performance/get-span/node.mdx create mode 100644 src/platform-includes/performance/span-api-version/javascript.mdx create mode 100644 src/platform-includes/performance/span-api-version/node.mdx diff --git a/src/platform-includes/performance/add-active-span/javascript.mdx b/src/platform-includes/performance/add-active-span/javascript.mdx new file mode 100644 index 0000000000000..11f097c6ed730 --- /dev/null +++ b/src/platform-includes/performance/add-active-span/javascript.mdx @@ -0,0 +1,9 @@ +You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to measure how long it will take. The span is automatically finished when the callback is finished. This will work with both sync and async callbacks. + +```javascript +const result = Sentry.startActiveSpan({ name: "Important Function" }, () => { + return expensiveFunction(); +}); +``` + +The span named `Important Function` will become the active span for the duration of the callback, which means that any child spans will be attached to it. diff --git a/src/platform-includes/performance/add-active-span/node.mdx b/src/platform-includes/performance/add-active-span/node.mdx new file mode 100644 index 0000000000000..11f097c6ed730 --- /dev/null +++ b/src/platform-includes/performance/add-active-span/node.mdx @@ -0,0 +1,9 @@ +You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to measure how long it will take. The span is automatically finished when the callback is finished. This will work with both sync and async callbacks. + +```javascript +const result = Sentry.startActiveSpan({ name: "Important Function" }, () => { + return expensiveFunction(); +}); +``` + +The span named `Important Function` will become the active span for the duration of the callback, which means that any child spans will be attached to it. diff --git a/src/platform-includes/performance/add-independent-span/javascript.mdx b/src/platform-includes/performance/add-independent-span/javascript.mdx new file mode 100644 index 0000000000000..83f7baec464d2 --- /dev/null +++ b/src/platform-includes/performance/add-independent-span/javascript.mdx @@ -0,0 +1,17 @@ +```javascript +const span1 = Sentry.startSpan({ name: "first-step" }); + +firstStep(); + +const span2 = Sentry.startSpan({ name: "second-step" }); + +secondStep(); + +const span3 = Sentry.startSpan({ name: "third-step" }); + +thirdStep(); + +span1.end(); +span2.end(); +span3.end(); +``` diff --git a/src/platform-includes/performance/add-independent-span/node.mdx b/src/platform-includes/performance/add-independent-span/node.mdx new file mode 100644 index 0000000000000..83f7baec464d2 --- /dev/null +++ b/src/platform-includes/performance/add-independent-span/node.mdx @@ -0,0 +1,17 @@ +```javascript +const span1 = Sentry.startSpan({ name: "first-step" }); + +firstStep(); + +const span2 = Sentry.startSpan({ name: "second-step" }); + +secondStep(); + +const span3 = Sentry.startSpan({ name: "third-step" }); + +thirdStep(); + +span1.end(); +span2.end(); +span3.end(); +``` diff --git a/src/platform-includes/performance/add-spans-example/javascript.mdx b/src/platform-includes/performance/add-spans-example/javascript.mdx index ba3c16db165e1..803c07b4605a1 100644 --- a/src/platform-includes/performance/add-spans-example/javascript.mdx +++ b/src/platform-includes/performance/add-spans-example/javascript.mdx @@ -9,7 +9,7 @@ function shopCheckout() { // If there's currently an unfinished transaction, it may be dropped Sentry.getCurrentHub().configureScope((scope) => scope.setSpan(transaction)); - // Assume this function makes an xhr/fetch call + // Assume this function makes a fetch call const result = validateShoppingCartOnServer(); const span = transaction.startChild({ diff --git a/src/platform-includes/performance/enable-manual-instrumentation/apple.mdx b/src/platform-includes/performance/enable-manual-instrumentation/apple.mdx index 4cbbf6a0d39a1..f41cf9a8c4b64 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/apple.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/apple.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ```swift {tabTitle:Swift} import Sentry; diff --git a/src/platform-includes/performance/enable-manual-instrumentation/dart.mdx b/src/platform-includes/performance/enable-manual-instrumentation/dart.mdx index 38d5947047065..18c0931947310 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/dart.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/dart.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction that contains an expensive operation (for example, `processOrderBatch`), and sends the result to Sentry: ```dart diff --git a/src/platform-includes/performance/enable-manual-instrumentation/dotnet.mdx b/src/platform-includes/performance/enable-manual-instrumentation/dotnet.mdx index 8e47cdd2089b3..3eee739630b9e 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/dotnet.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/dotnet.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ```csharp // Transaction can be started by providing, at minimum, the name and the operation var transaction = SentrySdk.StartTransaction( diff --git a/src/platform-includes/performance/enable-manual-instrumentation/go.mdx b/src/platform-includes/performance/enable-manual-instrumentation/go.mdx index ed1ba406667c8..8e877730c43bc 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/go.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/go.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction span to time runs of an expensive operation on items from a channel. Timing for each operation is sent to Sentry and grouped by transaction name: ```go diff --git a/src/platform-includes/performance/enable-manual-instrumentation/java.mdx b/src/platform-includes/performance/enable-manual-instrumentation/java.mdx index d1dd89ff7fcbc..9727f080b15f1 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/java.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/java.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction that contains an expensive operation (for example, `processOrderBatch`), and sends the result to Sentry: ```java {tabTitle:Java} diff --git a/src/platform-includes/performance/enable-manual-instrumentation/java.spring-boot.mdx b/src/platform-includes/performance/enable-manual-instrumentation/java.spring-boot.mdx index 8bd79ee4c68b9..47bb62d25eddc 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/java.spring-boot.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/java.spring-boot.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ## Capturing Bean Method Execution Every Spring bean method execution can be turned into a transaction or a span. diff --git a/src/platform-includes/performance/enable-manual-instrumentation/java.spring.mdx b/src/platform-includes/performance/enable-manual-instrumentation/java.spring.mdx index 74d74a8e3c667..00cf47db316f0 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/java.spring.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/java.spring.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ## Capturing Bean Method Execution Every Spring bean method execution can be turned into a transaction or a span. diff --git a/src/platform-includes/performance/enable-manual-instrumentation/javascript.mdx b/src/platform-includes/performance/enable-manual-instrumentation/javascript.mdx index 58d218ef6fad6..357f0f922ef0f 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/javascript.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/javascript.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + This is valid for all JavaScript SDKs (both backend and frontend) and works independently of the `Express`, `Http`, and `BrowserTracing` integrations. ```javascript diff --git a/src/platform-includes/performance/enable-manual-instrumentation/native.mdx b/src/platform-includes/performance/enable-manual-instrumentation/native.mdx index 71f75dda079c0..6e72727def761 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/native.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/native.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ```c // Enable performance monitoring by setting a sample rate above 0 sentry_options_t *options = sentry_options_new(); diff --git a/src/platform-includes/performance/enable-manual-instrumentation/php.mdx b/src/platform-includes/performance/enable-manual-instrumentation/php.mdx index f1b06ca46fc71..00db5988d7b45 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/php.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/php.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction for a scope that contains an expensive operation (for example, `expensive_operation`), and sends the result to Sentry: ```php diff --git a/src/platform-includes/performance/enable-manual-instrumentation/python.mdx b/src/platform-includes/performance/enable-manual-instrumentation/python.mdx index cd0fd40d69358..0bb40a1317395 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/python.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/python.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction for a scope that contains an expensive operation (for example, `process_item`), and sends the result to Sentry: ```python diff --git a/src/platform-includes/performance/enable-manual-instrumentation/ruby.mdx b/src/platform-includes/performance/enable-manual-instrumentation/ruby.mdx index 1c92828984c86..1c40088f826e6 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/ruby.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/ruby.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + The following example creates a transaction for a scope that contains an expensive operation (for example, `process_item`), and sends the result to Sentry: ```ruby diff --git a/src/platform-includes/performance/enable-manual-instrumentation/rust.mdx b/src/platform-includes/performance/enable-manual-instrumentation/rust.mdx index 3ed0f46ac86ef..092709066ddff 100644 --- a/src/platform-includes/performance/enable-manual-instrumentation/rust.mdx +++ b/src/platform-includes/performance/enable-manual-instrumentation/rust.mdx @@ -1,3 +1,5 @@ +To instrument certain regions of your code, you can create transactions to capture them. + ```rust // Transaction can be started by providing the name and the operation let tx_ctx = sentry::TransactionContext::new( diff --git a/src/platform-includes/performance/get-span/javascript.mdx b/src/platform-includes/performance/get-span/javascript.mdx new file mode 100644 index 0000000000000..7726fe8bb67e7 --- /dev/null +++ b/src/platform-includes/performance/get-span/javascript.mdx @@ -0,0 +1,15 @@ +```javascript +const span = Sentry.getActiveSpan(); + +if (span) { + span.setData("key", "value"); + + // Start a child span that will be a child of the current span. + // The child span will measure the time between span.startChild() and childSpan.finish(). + const childSpan = span.startChild({ name: "Child Span" }); + + expensiveCalculation(); + + childSpan.finish(); +} +``` diff --git a/src/platform-includes/performance/get-span/node.mdx b/src/platform-includes/performance/get-span/node.mdx new file mode 100644 index 0000000000000..7726fe8bb67e7 --- /dev/null +++ b/src/platform-includes/performance/get-span/node.mdx @@ -0,0 +1,15 @@ +```javascript +const span = Sentry.getActiveSpan(); + +if (span) { + span.setData("key", "value"); + + // Start a child span that will be a child of the current span. + // The child span will measure the time between span.startChild() and childSpan.finish(). + const childSpan = span.startChild({ name: "Child Span" }); + + expensiveCalculation(); + + childSpan.finish(); +} +``` diff --git a/src/platform-includes/performance/span-api-version/javascript.mdx b/src/platform-includes/performance/span-api-version/javascript.mdx new file mode 100644 index 0000000000000..a30cfbee06634 --- /dev/null +++ b/src/platform-includes/performance/span-api-version/javascript.mdx @@ -0,0 +1,5 @@ + + +The span APIs require SDK version `7.65.0` or higher. If you are using an older version of the SDK, you can use the [explicit transaction APIs](#start-transaction) for custom instrumentation. + + diff --git a/src/platform-includes/performance/span-api-version/node.mdx b/src/platform-includes/performance/span-api-version/node.mdx new file mode 100644 index 0000000000000..e37833a7826a6 --- /dev/null +++ b/src/platform-includes/performance/span-api-version/node.mdx @@ -0,0 +1,5 @@ + + +The below span APIs (`startActiveSpan`, `startSpan`, and `getActiveSpan`) require SDK version `7.65.0` or higher. If you are using an older version of the SDK, you can use the [explicit transaction APIs](#start-transaction) for custom instrumentation. + + diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index f2465c3729b91..1847b3c12b053 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -33,23 +33,63 @@ redirect_from: -To capture transactions customized to your organization's needs, you must first set up performance monitoring. +To capture transactions and spans customized to your organization's needs, you must first set up performance monitoring. -To instrument certain regions of your code, you can create transactions to capture them. + + + + + +To add custom performance data to your application, you need to create and use spans. Spans are a way to measure the time it takes for a specific action to occur. For example, you can create a span to measure the time it takes for a function to execute. + +To start measuring timing data, you first need to import the SDK. + + + + + +## Create Active Span + +By default created spans are considered active, which means they are put on the Sentry scope. This allows automatic instrumentation to attach child spans to that active span. + + + +## Get Active Span + +You can also get the current active span, which is useful for when you need to add new child spans. + + + +## Start Independent Spans + +If you want to add a span that is not active, you can create a independent spans. This is useful for when you have work that is grouped together under a single parent span, but is independent from the current active span. In most cases you'll want to create and use active spans. + + + +## Start Transaction + +The root span (the span that is the parent of all other spans) is known as a transaction in Sentry. This can be accessed and created separately if you need more control over the timing data or if you use a version of the SDK that does not support the top level span APIs. + + + + + + + - + From 4a36a013d4bf0eae473ac32254d89efae053793c Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 30 Aug 2023 10:10:12 -0400 Subject: [PATCH 2/5] expand active span snippets --- .../add-active-span/javascript.mdx | 22 ++++++++++++++++++- .../performance/add-active-span/node.mdx | 22 ++++++++++++++++++- .../add-independent-span/javascript.mdx | 6 ++--- .../performance/add-independent-span/node.mdx | 6 ++--- .../custom-instrumentation.mdx | 2 +- 5 files changed, 49 insertions(+), 9 deletions(-) diff --git a/src/platform-includes/performance/add-active-span/javascript.mdx b/src/platform-includes/performance/add-active-span/javascript.mdx index 11f097c6ed730..9234d962b1021 100644 --- a/src/platform-includes/performance/add-active-span/javascript.mdx +++ b/src/platform-includes/performance/add-active-span/javascript.mdx @@ -4,6 +4,26 @@ You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to const result = Sentry.startActiveSpan({ name: "Important Function" }, () => { return expensiveFunction(); }); + +const result = await Sentry.startActiveSpan( + { name: "Important Function" }, + async () => { + const res = Sentry.startActiveSpan({ name: "Child Span" }, () => { + return expensiveFunction(); + }); + + return updateRes(res); + } +); + +const result = Sentry.startActiveSpan( + { name: "Important Function" }, + (span) => { + // Can access the span to add data or set specific status + span?.setData("foo", "bar"); + return expensiveFunction(); + } +); ``` -The span named `Important Function` will become the active span for the duration of the callback, which means that any child spans will be attached to it. +The span named `Important Function` will become the active span for the duration of the callback. diff --git a/src/platform-includes/performance/add-active-span/node.mdx b/src/platform-includes/performance/add-active-span/node.mdx index 11f097c6ed730..9234d962b1021 100644 --- a/src/platform-includes/performance/add-active-span/node.mdx +++ b/src/platform-includes/performance/add-active-span/node.mdx @@ -4,6 +4,26 @@ You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to const result = Sentry.startActiveSpan({ name: "Important Function" }, () => { return expensiveFunction(); }); + +const result = await Sentry.startActiveSpan( + { name: "Important Function" }, + async () => { + const res = Sentry.startActiveSpan({ name: "Child Span" }, () => { + return expensiveFunction(); + }); + + return updateRes(res); + } +); + +const result = Sentry.startActiveSpan( + { name: "Important Function" }, + (span) => { + // Can access the span to add data or set specific status + span?.setData("foo", "bar"); + return expensiveFunction(); + } +); ``` -The span named `Important Function` will become the active span for the duration of the callback, which means that any child spans will be attached to it. +The span named `Important Function` will become the active span for the duration of the callback. diff --git a/src/platform-includes/performance/add-independent-span/javascript.mdx b/src/platform-includes/performance/add-independent-span/javascript.mdx index 83f7baec464d2..b0a9f1327762c 100644 --- a/src/platform-includes/performance/add-independent-span/javascript.mdx +++ b/src/platform-includes/performance/add-independent-span/javascript.mdx @@ -11,7 +11,7 @@ const span3 = Sentry.startSpan({ name: "third-step" }); thirdStep(); -span1.end(); -span2.end(); -span3.end(); +span1.finish(); +span2.finish(); +span3.finish(); ``` diff --git a/src/platform-includes/performance/add-independent-span/node.mdx b/src/platform-includes/performance/add-independent-span/node.mdx index 83f7baec464d2..b0a9f1327762c 100644 --- a/src/platform-includes/performance/add-independent-span/node.mdx +++ b/src/platform-includes/performance/add-independent-span/node.mdx @@ -11,7 +11,7 @@ const span3 = Sentry.startSpan({ name: "third-step" }); thirdStep(); -span1.end(); -span2.end(); -span3.end(); +span1.finish(); +span2.finish(); +span3.finish(); ``` diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index 1847b3c12b053..b04167c39e085 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -57,7 +57,7 @@ To start measuring timing data, you first need to import the SDK. ## Create Active Span -By default created spans are considered active, which means they are put on the Sentry scope. This allows automatic instrumentation to attach child spans to that active span. +By default created spans are considered active, which means they are put on the Sentry scope. This allows child spans and Sentry errors to be associated with that span. This is the recommended way to create spans. From ad641566e1644bb03f8cee09239eda6a56f4264d Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 30 Aug 2023 16:44:59 -0400 Subject: [PATCH 3/5] add note about span operations and other PR review --- .../performance/get-span/javascript.mdx | 16 +++++++--------- .../performance/get-span/node.mdx | 16 +++++++--------- .../performance/span-api-version/javascript.mdx | 2 +- .../performance/span-operations/javascript.mdx | 5 +++++ .../performance/span-operations/node.mdx | 5 +++++ .../instrumentation/custom-instrumentation.mdx | 8 ++++++++ 6 files changed, 33 insertions(+), 19 deletions(-) create mode 100644 src/platform-includes/performance/span-operations/javascript.mdx create mode 100644 src/platform-includes/performance/span-operations/node.mdx diff --git a/src/platform-includes/performance/get-span/javascript.mdx b/src/platform-includes/performance/get-span/javascript.mdx index 7726fe8bb67e7..6727f4ecb8792 100644 --- a/src/platform-includes/performance/get-span/javascript.mdx +++ b/src/platform-includes/performance/get-span/javascript.mdx @@ -1,15 +1,13 @@ -```javascript +```JavaScript const span = Sentry.getActiveSpan(); -if (span) { - span.setData("key", "value"); +span?.setData("key", "value"); - // Start a child span that will be a child of the current span. - // The child span will measure the time between span.startChild() and childSpan.finish(). - const childSpan = span.startChild({ name: "Child Span" }); +// Start a child span that will be a child of the current span. +// The child span will measure the time between span.startChild() and childSpan.finish(). +const childSpan = span?.startChild({ name: "Child Span" }); - expensiveCalculation(); +expensiveCalculation(); - childSpan.finish(); -} +childSpan?.finish(); ``` diff --git a/src/platform-includes/performance/get-span/node.mdx b/src/platform-includes/performance/get-span/node.mdx index 7726fe8bb67e7..6727f4ecb8792 100644 --- a/src/platform-includes/performance/get-span/node.mdx +++ b/src/platform-includes/performance/get-span/node.mdx @@ -1,15 +1,13 @@ -```javascript +```JavaScript const span = Sentry.getActiveSpan(); -if (span) { - span.setData("key", "value"); +span?.setData("key", "value"); - // Start a child span that will be a child of the current span. - // The child span will measure the time between span.startChild() and childSpan.finish(). - const childSpan = span.startChild({ name: "Child Span" }); +// Start a child span that will be a child of the current span. +// The child span will measure the time between span.startChild() and childSpan.finish(). +const childSpan = span?.startChild({ name: "Child Span" }); - expensiveCalculation(); +expensiveCalculation(); - childSpan.finish(); -} +childSpan?.finish(); ``` diff --git a/src/platform-includes/performance/span-api-version/javascript.mdx b/src/platform-includes/performance/span-api-version/javascript.mdx index a30cfbee06634..e37833a7826a6 100644 --- a/src/platform-includes/performance/span-api-version/javascript.mdx +++ b/src/platform-includes/performance/span-api-version/javascript.mdx @@ -1,5 +1,5 @@ -The span APIs require SDK version `7.65.0` or higher. If you are using an older version of the SDK, you can use the [explicit transaction APIs](#start-transaction) for custom instrumentation. +The below span APIs (`startActiveSpan`, `startSpan`, and `getActiveSpan`) require SDK version `7.65.0` or higher. If you are using an older version of the SDK, you can use the [explicit transaction APIs](#start-transaction) for custom instrumentation. diff --git a/src/platform-includes/performance/span-operations/javascript.mdx b/src/platform-includes/performance/span-operations/javascript.mdx new file mode 100644 index 0000000000000..35eb1a73ef85a --- /dev/null +++ b/src/platform-includes/performance/span-operations/javascript.mdx @@ -0,0 +1,5 @@ +```JavaScript +const result = Sentry.startActiveSpan({ name: 'GET /users', op: 'http.client' }, () => { + return fetchUsers(); +}) +``` diff --git a/src/platform-includes/performance/span-operations/node.mdx b/src/platform-includes/performance/span-operations/node.mdx new file mode 100644 index 0000000000000..4387ed0f042b3 --- /dev/null +++ b/src/platform-includes/performance/span-operations/node.mdx @@ -0,0 +1,5 @@ +```JavaScript +const result = Sentry.startActiveSpan({ name: 'SELECT * FROM TABLE', op: 'db.query' }, () => { + return execQuery(); +}) +``` diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index b04167c39e085..49311b7e8215d 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -81,6 +81,14 @@ The root span (the span that is the parent of all other spans) is known as a tra +## Adding Span operations + +Spans can have an operation associated with them, which help activate Sentry identify additional context about the span. For example database related spans have the `db` span operation associated with them. The Sentry product offers additional controls, visualizations and filters for spans with known operations. + +Sentry maintains a [list of well known span operations](https://develop.sentry.dev/sdk/performance/span-operations/#list-of-operations) and it is recommended that you use one of those operations if it is applicable to your span. + + + From eb4d124f08277f1316b7b7374a885c543d7f2cd8 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 31 Aug 2023 15:27:55 -0400 Subject: [PATCH 4/5] add note about span being disabled --- .../performance/add-active-span/javascript.mdx | 3 ++- src/platform-includes/performance/add-active-span/node.mdx | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/platform-includes/performance/add-active-span/javascript.mdx b/src/platform-includes/performance/add-active-span/javascript.mdx index 9234d962b1021..2cf1455884eb7 100644 --- a/src/platform-includes/performance/add-active-span/javascript.mdx +++ b/src/platform-includes/performance/add-active-span/javascript.mdx @@ -19,7 +19,8 @@ const result = await Sentry.startActiveSpan( const result = Sentry.startActiveSpan( { name: "Important Function" }, (span) => { - // Can access the span to add data or set specific status + // Can access the span to add data or set specific status. + // The span can be undefined if the span was not sampled or if performance monitoring is disabled. span?.setData("foo", "bar"); return expensiveFunction(); } diff --git a/src/platform-includes/performance/add-active-span/node.mdx b/src/platform-includes/performance/add-active-span/node.mdx index 9234d962b1021..2cf1455884eb7 100644 --- a/src/platform-includes/performance/add-active-span/node.mdx +++ b/src/platform-includes/performance/add-active-span/node.mdx @@ -19,7 +19,8 @@ const result = await Sentry.startActiveSpan( const result = Sentry.startActiveSpan( { name: "Important Function" }, (span) => { - // Can access the span to add data or set specific status + // Can access the span to add data or set specific status. + // The span can be undefined if the span was not sampled or if performance monitoring is disabled. span?.setData("foo", "bar"); return expensiveFunction(); } From cf55936cfc41be54a3aa90306167e3bb6cfc58c5 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Thu, 31 Aug 2023 15:29:08 -0400 Subject: [PATCH 5/5] add closing --- .../performance/instrumentation/custom-instrumentation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index 49311b7e8215d..0bb0ed89edb47 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -87,7 +87,7 @@ Spans can have an operation associated with them, which help activate Sentry ide Sentry maintains a [list of well known span operations](https://develop.sentry.dev/sdk/performance/span-operations/#list-of-operations) and it is recommended that you use one of those operations if it is applicable to your span. - +