From 9b40b2a5c9536f4d745c283c6b5b16fb41388e56 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 13 Sep 2023 09:59:25 -0400 Subject: [PATCH] feat(js): Add back node performance API docs --- .../add-active-span/javascript.mdx | 30 ------------- .../performance/add-active-span/node.mdx | 30 ------------- .../add-independent-span/javascript.mdx | 17 -------- .../performance/add-independent-span/node.mdx | 17 -------- .../performance/get-span/javascript.mdx | 13 ------ .../performance/get-span/node.mdx | 13 ------ .../span-api-version/javascript.mdx | 2 +- .../performance/span-api-version/node.mdx | 2 +- .../span-operations/javascript.mdx | 2 +- .../performance/span-operations/node.mdx | 2 +- .../start-inactive-span/javascript.mdx | 17 ++++++++ .../performance/start-inactive-span/node.mdx | 17 ++++++++ .../performance/start-span/javascript.mdx | 42 +++++++++++++++++++ .../performance/start-span/node.mdx | 42 +++++++++++++++++++ .../custom-instrumentation.mdx | 32 ++++++-------- 15 files changed, 135 insertions(+), 143 deletions(-) delete mode 100644 src/platform-includes/performance/add-active-span/javascript.mdx delete mode 100644 src/platform-includes/performance/add-active-span/node.mdx delete mode 100644 src/platform-includes/performance/add-independent-span/javascript.mdx delete mode 100644 src/platform-includes/performance/add-independent-span/node.mdx delete mode 100644 src/platform-includes/performance/get-span/javascript.mdx delete mode 100644 src/platform-includes/performance/get-span/node.mdx create mode 100644 src/platform-includes/performance/start-inactive-span/javascript.mdx create mode 100644 src/platform-includes/performance/start-inactive-span/node.mdx create mode 100644 src/platform-includes/performance/start-span/javascript.mdx create mode 100644 src/platform-includes/performance/start-span/node.mdx diff --git a/src/platform-includes/performance/add-active-span/javascript.mdx b/src/platform-includes/performance/add-active-span/javascript.mdx deleted file mode 100644 index fc06b19b12650..0000000000000 --- a/src/platform-includes/performance/add-active-span/javascript.mdx +++ /dev/null @@ -1,30 +0,0 @@ -You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to measure how long it will take. The span will automatically be finished when the callback finishes. This works with both synchronous and async callbacks. - -```javascript -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) => { - // You can access the span to add data or set specific status. - // The span may be undefined if the span was not sampled or if performance monitoring is disabled. - span?.setData("foo", "bar"); - return expensiveFunction(); - } -); -``` - -In this example, 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 deleted file mode 100644 index f79c2ee2e0ed1..0000000000000 --- a/src/platform-includes/performance/add-active-span/node.mdx +++ /dev/null @@ -1,30 +0,0 @@ -You can use the `Sentry.startActiveSpan` method to wrap a callback in a span to measure how long it will take. The span will automatically be finished when the callback finishes. This works with both synchronous and async callbacks. - -```javascript -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) => { - // You can access the span to add data or set specific status. - // The span may be undefined if the span was not sampled or if performance monitoring is disabled. - span?.setData("foo", "bar"); - return expensiveFunction(); - } -); -``` - -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 deleted file mode 100644 index b0a9f1327762c..0000000000000 --- a/src/platform-includes/performance/add-independent-span/javascript.mdx +++ /dev/null @@ -1,17 +0,0 @@ -```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.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 deleted file mode 100644 index b0a9f1327762c..0000000000000 --- a/src/platform-includes/performance/add-independent-span/node.mdx +++ /dev/null @@ -1,17 +0,0 @@ -```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.finish(); -span2.finish(); -span3.finish(); -``` diff --git a/src/platform-includes/performance/get-span/javascript.mdx b/src/platform-includes/performance/get-span/javascript.mdx deleted file mode 100644 index 6727f4ecb8792..0000000000000 --- a/src/platform-includes/performance/get-span/javascript.mdx +++ /dev/null @@ -1,13 +0,0 @@ -```JavaScript -const span = Sentry.getActiveSpan(); - -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 deleted file mode 100644 index 6727f4ecb8792..0000000000000 --- a/src/platform-includes/performance/get-span/node.mdx +++ /dev/null @@ -1,13 +0,0 @@ -```JavaScript -const span = Sentry.getActiveSpan(); - -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 index e37833a7826a6..e0850dec5503a 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 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. +The below span APIs (`startSpan`, `startInactiveSpan`, and `startSpanManual`) require SDK version `7.69.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 index e37833a7826a6..e0850dec5503a 100644 --- a/src/platform-includes/performance/span-api-version/node.mdx +++ b/src/platform-includes/performance/span-api-version/node.mdx @@ -1,5 +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. +The below span APIs (`startSpan`, `startInactiveSpan`, and `startSpanManual`) require SDK version `7.69.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 index 35eb1a73ef85a..95470cc1183ef 100644 --- a/src/platform-includes/performance/span-operations/javascript.mdx +++ b/src/platform-includes/performance/span-operations/javascript.mdx @@ -1,5 +1,5 @@ ```JavaScript -const result = Sentry.startActiveSpan({ name: 'GET /users', op: 'http.client' }, () => { +const result = Sentry.startSpan({ 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 index 4387ed0f042b3..3957a9abf36eb 100644 --- a/src/platform-includes/performance/span-operations/node.mdx +++ b/src/platform-includes/performance/span-operations/node.mdx @@ -1,5 +1,5 @@ ```JavaScript -const result = Sentry.startActiveSpan({ name: 'SELECT * FROM TABLE', op: 'db.query' }, () => { +const result = Sentry.startSpan({ name: 'SELECT * FROM TABLE', op: 'db.query' }, () => { return execQuery(); }) ``` diff --git a/src/platform-includes/performance/start-inactive-span/javascript.mdx b/src/platform-includes/performance/start-inactive-span/javascript.mdx new file mode 100644 index 0000000000000..314351db032d5 --- /dev/null +++ b/src/platform-includes/performance/start-inactive-span/javascript.mdx @@ -0,0 +1,17 @@ +```javascript +const span1 = Sentry.startInactiveSpan({ name: "span1" }); + +someWork(); + +const span2 = Sentry.startInactiveSpan({ name: "span2" }); + +moreWork(); + +const span3 = Sentry.startInactiveSpan({ name: "span3" }); + +evenMoreWork(); + +span1?.finish(); +span2?.finish(); +span3?.finish(); +``` diff --git a/src/platform-includes/performance/start-inactive-span/node.mdx b/src/platform-includes/performance/start-inactive-span/node.mdx new file mode 100644 index 0000000000000..314351db032d5 --- /dev/null +++ b/src/platform-includes/performance/start-inactive-span/node.mdx @@ -0,0 +1,17 @@ +```javascript +const span1 = Sentry.startInactiveSpan({ name: "span1" }); + +someWork(); + +const span2 = Sentry.startInactiveSpan({ name: "span2" }); + +moreWork(); + +const span3 = Sentry.startInactiveSpan({ name: "span3" }); + +evenMoreWork(); + +span1?.finish(); +span2?.finish(); +span3?.finish(); +``` diff --git a/src/platform-includes/performance/start-span/javascript.mdx b/src/platform-includes/performance/start-span/javascript.mdx new file mode 100644 index 0000000000000..3c9a05f7ec92b --- /dev/null +++ b/src/platform-includes/performance/start-span/javascript.mdx @@ -0,0 +1,42 @@ +You can use the `Sentry.startSpan` method to wrap a callback in a span to measure how long it will take. The span will automatically be finished when the callback finishes. This works with both synchronous and async callbacks. + +```javascript +const result = Sentry.startSpan({ name: "Important Function" }, () => { + return expensiveFunction(); +}); + +const result = await Sentry.startSpan( + { name: "Important Function" }, + async () => { + const res = Sentry.startSpan({ name: "Child Span" }, () => { + return expensiveFunction(); + }); + + return updateRes(res); + } +); + +const result = Sentry.startSpan({ name: "Important Function" }, (span) => { + // You can access the span to add data or set specific status. + // The span may be undefined if the span was not sampled or if performance monitoring is disabled. + span?.setData("foo", "bar"); + return expensiveFunction(); +}); +``` + +In this example, the span named `Important Function` will become the active span for the duration of the callback. + +If you need to override when the span finishes, you can use `Sentry.startSpanManual`. This is useful for creating parallel spans that are not related to each other. + +```javascript +// Start a span that tracks the duration of middleware +function middleware(_req, res, next) { + return Sentry.startSpanManual({ name: "middleware" }, (span, finish) => { + res.once("finish", () => { + span?.setHttpStatus(res.status); + finish(); + }); + return next(); + }); +} +``` diff --git a/src/platform-includes/performance/start-span/node.mdx b/src/platform-includes/performance/start-span/node.mdx new file mode 100644 index 0000000000000..3c9a05f7ec92b --- /dev/null +++ b/src/platform-includes/performance/start-span/node.mdx @@ -0,0 +1,42 @@ +You can use the `Sentry.startSpan` method to wrap a callback in a span to measure how long it will take. The span will automatically be finished when the callback finishes. This works with both synchronous and async callbacks. + +```javascript +const result = Sentry.startSpan({ name: "Important Function" }, () => { + return expensiveFunction(); +}); + +const result = await Sentry.startSpan( + { name: "Important Function" }, + async () => { + const res = Sentry.startSpan({ name: "Child Span" }, () => { + return expensiveFunction(); + }); + + return updateRes(res); + } +); + +const result = Sentry.startSpan({ name: "Important Function" }, (span) => { + // You can access the span to add data or set specific status. + // The span may be undefined if the span was not sampled or if performance monitoring is disabled. + span?.setData("foo", "bar"); + return expensiveFunction(); +}); +``` + +In this example, the span named `Important Function` will become the active span for the duration of the callback. + +If you need to override when the span finishes, you can use `Sentry.startSpanManual`. This is useful for creating parallel spans that are not related to each other. + +```javascript +// Start a span that tracks the duration of middleware +function middleware(_req, res, next) { + return Sentry.startSpanManual({ name: "middleware" }, (span, finish) => { + res.once("finish", () => { + span?.setHttpStatus(res.status); + finish(); + }); + return next(); + }); +} +``` diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index 7544be2dea609..88e4b0ebba75b 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -37,7 +37,7 @@ To capture transactions and spans customized to your organization's needs, you m - + @@ -45,7 +45,7 @@ To capture transactions and spans customized to your organization's needs, you m - + To add custom performance data to your application, you need to add custom instrumentation in the form of 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. @@ -55,23 +55,25 @@ To get started, import the SDK. -## Create Active Span +## Start Span By default, spans you create 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. - + -## Get Active Span +## Start Inactive Spans -You can also get the current active span, which is useful to add new child spans. +To add spans that aren't active, you can create 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. However, in most cases you'll want to create and use the start span API from above. - + -## Start Independent Spans +## Adding Span operations -To add spans that aren't active, you can create 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. However, in most cases you'll want to create and use active spans instead. +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. + + ## Start Transaction @@ -81,14 +83,6 @@ The root span (the span that is the parent of all other spans) is known as a **t -## 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. - - - @@ -97,7 +91,7 @@ Sentry maintains a [list of well known span operations](https://develop.sentry.d - +