Skip to content

Commit 1c3f7a4

Browse files
mydeamydea
authored
Merge pull request #10884 from getsentry/master
Gitflow: Merge master into develop
2 parents af6f4d6 + 076f392 commit 1c3f7a4

File tree

2 files changed

+92
-68
lines changed

2 files changed

+92
-68
lines changed

‎docs/v8-new-performance-apis.md

Lines changed: 89 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# New Performance APIs in v8
22

3-
> [!WARNING] This document is WIP. We are working on this while we are preparing v8.
4-
53
In v8.0.0, we moved to new performance APIs. These APIs have been introduced in v7, so they can already be used there.
64
However, in v8 we have removed the old performance APIs, so you have to update your manual instrumentation usage to the
75
new APIs before updating to v8 of the JavaScript SDKs.
@@ -36,72 +34,6 @@ In the new model, transactions are conceptually gone. Instead, you will _always_
3634
the tree you are. Note that in the background, spans _may_ still be grouped into a transaction for the Sentry UI.
3735
However, this happens transparently, and from an SDK perspective, all you have to think about are spans.
3836

39-
## The Span schema
40-
41-
Previously, spans & transactions had a bunch of properties and methods to be used. Most of these have been removed in
42-
favor of a slimmer, more straightforward API, which is also aligned with OpenTelemetry Spans. You can refer to the table
43-
below to see which things used to exist, and how they can/should be mapped going forward:
44-
45-
| Old name | Replace with |
46-
| --------------------- | ---------------------------------------------------- |
47-
| `traceId` | `spanContext().traceId` |
48-
| `spanId` | `spanContext().spanId` |
49-
| `parentSpanId` | `spanToJSON(span).parent_span_id` |
50-
| `status` | use utility method TODO |
51-
| `sampled` | `spanIsSampled(span)` |
52-
| `startTimestamp` | `startTime` - note that this has a different format! |
53-
| `tags` | use attributes, or set tags on the scope |
54-
| `data` | `spanToJSON(span).data` |
55-
| `transaction` | ??? Removed |
56-
| `instrumenter` | Removed |
57-
| `finish()` | `end()` |
58-
| `end()` | Same |
59-
| `setTag()` | `setAttribute()`, or set tags on the scope |
60-
| `setData()` | `setAttribute()` |
61-
| `setStatus()` | TODO: new signature |
62-
| `setHttpStatus()` | ??? TODO |
63-
| `setName()` | `updateName()` |
64-
| `startChild()` | Call `Sentry.startSpan()` independently |
65-
| `isSuccess()` | `spanToJSON(span).status === 'ok'` |
66-
| `toTraceparent()` | `spanToTraceHeader(span)` |
67-
| `toContext()` | Removed |
68-
| `updateWithContext()` | Removed |
69-
| `getTraceContext()` | `spanToTraceContext(span)` |
70-
71-
In addition, a transaction has this API:
72-
73-
| Old name | Replace with |
74-
| --------------------------- | ------------------------------------------------ |
75-
| `name` | `spanToJSON(span).description` |
76-
| `trimEnd` | Removed |
77-
| `parentSampled` | `spanIsSampled(span)` & `spanContext().isRemote` |
78-
| `metadata` | Use attributes instead or set on scope |
79-
| `setContext()` | Set context on scope instead |
80-
| `setMeasurement()` | ??? TODO |
81-
| `setMetadata()` | Use attributes instead or set on scope |
82-
| `getDynamicSamplingContext` | ??? TODO |
83-
84-
### Attributes vs. Data vs. Tags vs. Context
85-
86-
In the old model, you had the concepts of **Data**, **Tags** and **Context** which could be used for different things.
87-
However, this has two main downsides: One, it is not always clear which of these should be used when. And two, not all
88-
of these are displayed the same way for transactions or spans.
89-
90-
Because of this, in the new model, there are only **Attributes** to be set on spans anymore. Broadly speaking, they map
91-
to what Data used to be.
92-
93-
If you still really _need_ to set tags or context, you can do so on the scope before starting a span:
94-
95-
```js
96-
Sentry.withScope(scope => {
97-
scope.setTag('my-tag', 'tag-value');
98-
Sentry.startSpan({ name: 'my-span' }, span => {
99-
// do something here
100-
// span will have the tags from the containing scope
101-
});
102-
});
103-
```
104-
10537
## Creating Spans
10638

10739
Instead of manually starting & ending transactions and spans, the new model does not differentiate between these two.
@@ -220,6 +152,95 @@ Sentry.startSpan({ name: 'outer' }, () => {
220152

221153
No span will ever be created as a child span of an inactive span.
222154

155+
### Creating a child span of a specific span
156+
157+
You can use the `withActiveSpan` helper to create a span as a child of a specific span:
158+
159+
```js
160+
Sentry.withActiveSpan(parentSpan, () => {
161+
Sentry.startSpan({ name: 'my-span' }, span => {
162+
// span will be a direct child of parentSpan
163+
});
164+
});
165+
```
166+
167+
### Creating a transaction
168+
169+
While in most cases, you shouldn't have to think about creating a span vs. a transaction (just call `startSpan()` and
170+
we'll do the appropriate thing under the hood), there may still be times where you _need_ to ensure you create a
171+
transaction (for example, if you need to see it as a transaction in the Sentry UI). For these cases, you can pass
172+
`forceTransaction: true` to the start-span APIs, e.g.:
173+
174+
```js
175+
const transaction = Sentry.startInactiveSpan({ name: 'transaction', forceTransaction: true });
176+
```
177+
178+
## The Span schema
179+
180+
Previously, spans & transactions had a bunch of properties and methods to be used. Most of these have been removed in
181+
favor of a slimmer, more straightforward API, which is also aligned with OpenTelemetry Spans. You can refer to the table
182+
below to see which things used to exist, and how they can/should be mapped going forward:
183+
184+
| Old name | Replace with |
185+
| --------------------- | ----------------------------------------------------------- |
186+
| `traceId` | `spanContext().traceId` |
187+
| `spanId` | `spanContext().spanId` |
188+
| `parentSpanId` | `spanToJSON(span).parent_span_id` |
189+
| `status` | `spanToJSON(span).status` |
190+
| `sampled` | `spanIsSampled(span)` |
191+
| `startTimestamp` | `startTime` - note that this has a different format! |
192+
| `tags` | use attributes, or set tags on the scope |
193+
| `data` | `spanToJSON(span).data` |
194+
| `transaction` | `getRootSpan(span)` |
195+
| `instrumenter` | Removed |
196+
| `finish()` | `end()` |
197+
| `end()` | Same |
198+
| `setTag()` | `setAttribute()`, or set tags on the scope |
199+
| `setData()` | `setAttribute()` |
200+
| `setStatus()` | The signature of this will change in a coming alpha release |
201+
| `setHttpStatus()` | `setHttpStatus(span, status)` |
202+
| `setName()` | `updateName()` |
203+
| `startChild()` | Call `Sentry.startSpan()` independently |
204+
| `isSuccess()` | `spanToJSON(span).status === 'ok'` |
205+
| `toTraceparent()` | `spanToTraceHeader(span)` |
206+
| `toContext()` | Removed |
207+
| `updateWithContext()` | Removed |
208+
| `getTraceContext()` | `spanToTraceContext(span)` |
209+
210+
In addition, a transaction has this API:
211+
212+
| Old name | Replace with |
213+
| --------------------------- | ------------------------------------------------ |
214+
| `name` | `spanToJSON(span).description` |
215+
| `trimEnd` | Removed |
216+
| `parentSampled` | `spanIsSampled(span)` & `spanContext().isRemote` |
217+
| `metadata` | Use attributes instead or set on scope |
218+
| `setContext()` | Set context on scope instead |
219+
| `setMeasurement()` | `Sentry.setMeasurement()` |
220+
| `setMetadata()` | Use attributes instead or set on scope |
221+
| `getDynamicSamplingContext` | `getDynamicSamplingContextFromSpan(span)` |
222+
223+
### Attributes vs. Data vs. Tags vs. Context
224+
225+
In the old model, you had the concepts of **Data**, **Tags** and **Context** which could be used for different things.
226+
However, this has two main downsides: One, it is not always clear which of these should be used when. And two, not all
227+
of these are displayed the same way for transactions or spans.
228+
229+
Because of this, in the new model, there are only **Attributes** to be set on spans anymore. Broadly speaking, they map
230+
to what Data used to be.
231+
232+
If you still really _need_ to set tags or context, you can do so on the scope before starting a span:
233+
234+
```js
235+
Sentry.withScope(scope => {
236+
scope.setTag('my-tag', 'tag-value');
237+
Sentry.startSpan({ name: 'my-span' }, span => {
238+
// do something here
239+
// span will have the tags from the containing scope
240+
});
241+
});
242+
```
243+
223244
## Other Notable Changes
224245

225246
In addition to generally changing the performance APIs, there are also some smaller changes that this brings with it.

‎packages/node-experimental/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,12 @@ There is experimental support for running OpenTelemetry with ESM (`"type": "modu
109109
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs ./app.js
110110
```
111111

112+
You'll need to install `@opentelemetry/instrumentation` in your app to ensure this works.
113+
112114
See [OpenTelemetry Instrumentation Docs](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation#instrumentation-for-es-modules-in-nodejs-experimental) for details on this -
113115
but note that this is a) experimental, and b) does not work with all integrations.
114116

117+
115118
## Available (Performance) Integrations
116119

117120
* Http

0 commit comments

Comments
 (0)