Skip to content

feat(js): Add back new JS performance API docs #7796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 13, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 0 additions & 30 deletions src/platform-includes/performance/add-active-span/javascript.mdx

This file was deleted.

30 changes: 0 additions & 30 deletions src/platform-includes/performance/add-active-span/node.mdx

This file was deleted.

This file was deleted.

17 changes: 0 additions & 17 deletions src/platform-includes/performance/add-independent-span/node.mdx

This file was deleted.

13 changes: 0 additions & 13 deletions src/platform-includes/performance/get-span/javascript.mdx

This file was deleted.

13 changes: 0 additions & 13 deletions src/platform-includes/performance/get-span/node.mdx

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<Note>

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.

</Note>
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<Note>

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.

</Note>
Original file line number Diff line number Diff line change
@@ -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();
})
```
2 changes: 1 addition & 1 deletion src/platform-includes/performance/span-operations/node.mdx
Original file line number Diff line number Diff line change
@@ -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();
})
```
Original file line number Diff line number Diff line change
@@ -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();
```
17 changes: 17 additions & 0 deletions src/platform-includes/performance/start-inactive-span/node.mdx
Original file line number Diff line number Diff line change
@@ -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();
```
42 changes: 42 additions & 0 deletions src/platform-includes/performance/start-span/javascript.mdx
Original file line number Diff line number Diff line change
@@ -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();
});
}
```
42 changes: 42 additions & 0 deletions src/platform-includes/performance/start-span/node.mdx
Original file line number Diff line number Diff line change
@@ -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();
});
}
```
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ To capture transactions and spans customized to your organization's needs, you m

</Note>

<PlatformSection notSupported={[" "]}>
<PlatformSection notSupported={["javascript", "node"]}>

<PlatformContent includePath="performance/enable-manual-instrumentation" />

<PlatformContent includePath="performance/add-spans-example" />

</PlatformSection>

<PlatformSection supported={[" "]}>
<PlatformSection supported={["javascript", "node"]}>

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.

Expand All @@ -55,23 +55,25 @@ To get started, import the SDK.

<PlatformContent includePath="performance/span-api-version" />

## 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.

<PlatformContent includePath="performance/add-active-span" />
<PlatformContent includePath="performance/start-span" />

## 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.

<PlatformContent includePath="performance/get-span" />
<PlatformContent includePath="performance/start-inactive-span" />

## 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.

<PlatformContent includePath="performance/add-independent-span" />
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.

<PlatformContent includePath="performance/span-operations" />

## Start Transaction

Expand All @@ -81,14 +83,6 @@ The root span (the span that is the parent of all other spans) is known as a **t

<PlatformContent includePath="performance/add-spans-example" />

## 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.

<PlatformContent includePath="performance/span-operations" />

</PlatformSection>

<PlatformSection supported={["java", "apple"]}>
Expand All @@ -97,7 +91,7 @@ Sentry maintains a [list of well known span operations](https://develop.sentry.d

</PlatformSection>

<PlatformSection notSupported={["java", "native", "apple"]}>
<PlatformSection notSupported={["java", "native", "apple", "javascript", "node"]}>

<PlatformContent includePath="performance/retrieve-transaction" />

Expand Down