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..2cf1455884eb7 --- /dev/null +++ b/src/platform-includes/performance/add-active-span/javascript.mdx @@ -0,0 +1,30 @@ +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(); +}); + +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. + // The span can 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-active-span/node.mdx b/src/platform-includes/performance/add-active-span/node.mdx new file mode 100644 index 0000000000000..2cf1455884eb7 --- /dev/null +++ b/src/platform-includes/performance/add-active-span/node.mdx @@ -0,0 +1,30 @@ +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(); +}); + +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. + // The span can 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 new file mode 100644 index 0000000000000..b0a9f1327762c --- /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.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 new file mode 100644 index 0000000000000..b0a9f1327762c --- /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.finish(); +span2.finish(); +span3.finish(); +``` 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..6727f4ecb8792 --- /dev/null +++ b/src/platform-includes/performance/get-span/javascript.mdx @@ -0,0 +1,13 @@ +```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 new file mode 100644 index 0000000000000..6727f4ecb8792 --- /dev/null +++ b/src/platform-includes/performance/get-span/node.mdx @@ -0,0 +1,13 @@ +```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 new file mode 100644 index 0000000000000..e37833a7826a6 --- /dev/null +++ b/src/platform-includes/performance/span-api-version/javascript.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/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/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 f2465c3729b91..0bb0ed89edb47 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -33,23 +33,71 @@ 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 child spans and Sentry errors to be associated with that span. This is the recommended way to create spans. + + + +## 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. + + + + + +## 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. + + + + + - +