Skip to content

feat(js): Add docs for creating a child span #10729

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.

Sign up for GitHub

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
Jul 16, 2024
Merged

feat(js): Add docs for creating a child span #10729

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
41 changes: 33 additions & 8 deletions ...orms/javascript/common/tracing/instrumentation/custom-instrumentation/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,14 +72,15 @@ This will revert to use the full hierarchy behavior, where spans are children of

The following options can be used for all span starting functions:

| Option | Type | Description |
| ------------------ | --------------------------- | ------------------------------------------------------------------- |
| `name` | `string` | The name of the span. |
| `op` | `string` | The operation of the span. |
| `startTime` | `number` | The start time of the span. |
| `attributes` | `Record<string, Primitive>` | Attributes to attach to the span. |
| `onlyIfParent` | `boolean` | If true, ignore the span if there is no active parent span. |
| `forceTransaction` | `boolean` | If true, ensure this span shows up as transaction in the Sentry UI. |
| Option | Type | Description |
| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | The name of the span. |
| `op` | `string` | The operation of the span. |
| `startTime` | `number` | The start time of the span. |
| `attributes` | `Record<string, Primitive>` | Attributes to attach to the span. |
| `parentSpan` | `Span` | If set, make the span a child of the specified span. Otherwise, the span will be a child of the currently active span. |
| `onlyIfParent` | `boolean` | If true, ignore the span if there is no active parent span. |
| `forceTransaction` | `boolean` | If true, ensure this span shows up as transaction in the Sentry UI. |

Only `name` is required, all other options are optional.

Expand All @@ -101,6 +102,20 @@ To add spans that aren't active, you can create independent spans. This is usefu

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

## Starting Spans as Children of a Specific Span
Copy link
Member

@Lms24 Lms24 Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we guarding this paragraph for node guides? AFAIK this won't work in browser SDK where we have a flat span hierarchy, right?

Copy link
Member Author

@mydea mydea Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm, good point, I mean it will kind of work, if the span is a root span for example. I would leave this as is for now, we can maybe clarify this even further if needed!

Copy link
Member

@Lms24 Lms24 Jul 16, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok sounds good to me!


By default, any span that is started will be the child of the currently active span. If you want to have a different behavior, you can force spans to be the children of a specific span with the `parentSpan` option:

```js
const parentSpan = Sentry.startInactiveSpan({ name: "Parent Span" });
const childSpan = Sentry.startInactiveSpan({ name: "Child Span", parentSpan });

childSpan.end();
parentSpan.end();
```

This option is also available for `startSpan` and `startSpanManual`.

## Utilities to work with Spans

We expose some helpful utilities that can help you with custom instrumentation.
Expand Down Expand Up @@ -148,6 +163,16 @@ Sentry.withActiveSpan(null, () => {
});
```

Alternatively you can also use the `parentSpan` option to achieve the same:

```javascript
const span = Sentry.startInactiveSpan({ name: "Parent Span" });
const childSpan = Sentry.startInactiveSpan({
name: "Child Span",
parentSpan: span,
});
```

### `suppressTracing`

Suppress the creation of sampled spans for the duration of the callback. This is useful when you want to prevent certain spans from being captured. For example, if you do not want to create spans for a given fetch request, you can do:
Expand Down