feat(core/spans): Add span v2 and envelope type definitions #19100
Conversation
Add type definitions for the new v2 span format: - `SpanV2JSON`: JSON representation of a v2 span - `SpanV2JSONWithSegmentRef`: SpanV2JSON with segment span reference for DSC - `SerializedSpanContainer`: Container for serialized spans - `SpanContainerItem`: Envelope item for span containers - `SpanV2Envelope`: Envelope type for v2 spans - Make `SpanLinkJSON` generic to support different attribute types - Export `AttributeUnit` type for serialized attributes - Add `SerializedAttribute` types for typed attribute serialization These types form the foundation for the upcoming span streaming feature.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Codecov Results 📊Generated by Codecov Action |
size-limit report 📦
|
node-overhead report 🧳Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.
|
Lms24
changed the title
Lms24
changed the title
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| * The final, serialized span is a {@link SerializedSpan}. | ||
| * Main reason: Make it easier and safer for users to work with attributes. | ||
| */ | ||
| export interface SpanV2JSON { |
There was a problem hiding this comment.
l/q: Before we merge it as SpanV2JSON. Is SpanV2 the official term? Not sure how other SDKs will handle this, but maybe we could verify that before we get into future confusion what the difference between "span v2" and "span streaming" is
There was a problem hiding this comment.
Yeah I agree that SpanV2JSON is not the ideal name here 😅 SpanJSON would be ideal but that's already taken. Reusing this is IMHO not really possible because it still features properties like description, measurements, data, etc. All those properties and concepts have no place in the new v2 span protocol.
There's no official term for this intermediate step, as most SDKs besides JS never had a reason to surface serialized spans before. They just expose the regular span class instance to users. But we can't do that because OTel span instances are no longer writable at the point where they reach beforeSendSpan.
The old transaction based pattern basically was:
Span -> SpanJSON -> sent as Transaction event envelope
Now we need some other kind of intermediate name. Something like
Span -> StreamedSpanJSON -> sent as SerializedSpan array envelope
The alternative here would be to directly convert the Span to a SerializedSpan and let users deal with the complicated attribute type. This has however the consequence that they could set a type that doesn't conform with the value property of the attribute. Which is why I figured I'd prefer keeping the intermediate step.
There was a problem hiding this comment.
The good news here is, as long as we merge against the epic branch, we can break as much as we want with the names 😅
This PR introduces span v2 types as defined in our develop spec:
SpanV2Envelope,SpanV2EnvelopeHeaders,SpanContainerItem,SpanContainerItemHeadersSpanV2JSONthe equivalent to today'sSpanJSON. Users will interact with spans in this format inbeforeSendSpan. SDK integrations will use this format inprocessSpan(and related) hooks.SerializedSpanthe final, serialized format for v2 spans, sent in the envelope container item.Why the intermediate step?
SerializedSpanis annoying to deal with for users, because attributes will be converted to the{type: string, value: Value}format. So it's not ideal that users have to work with this in e.g.beforeSendSpan. We have the same problem in logs and metrics and solved it by exposing the raw attribute values to the beforeSendX callbacks and only afterwards converting them to the expected typed format.So here's a rough overview how this will work in the upcoming
captureSpanpipeline:SpaninstancecaptureSpanconvertsSpaninstance toSpanV2JSONSpanV2JSONis used to process the span, invokebeforeSendSpan, etc.SpanV2JSONtoSerializedSpanSerializedSpaninto bufferCloses #19101 (added automatically)
ref #17836