Skip to content

Commit 9bf81e0

Browse files
cleptriccleptric
authored
docs(sdks): New Span Protocol (#11941)
Refs https://linear.app/getsentry/project/new-span-schema-d9b4479f28ed/overview
1 parent 8909490 commit 9bf81e0

File tree

1 file changed

+194
-0
lines changed

1 file changed

+194
-0
lines changed

‎develop-docs/sdk/telemetry/spans/span-protocol.mdx‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Span Protocol
3+
---
4+
5+
<Alert level="info">
6+
This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
7+
</Alert>
8+
9+
The SDK must implement a new "span v2" envelope item, which is used to emit spans to Sentry.
10+
11+
## Span v2 Envelope Item Header
12+
13+
The envelope item header must contain the following properties:
14+
15+
```json
16+
{
17+
"type": "span",
18+
"item_count": 2,
19+
"content_type": "application/vnd.sentry.items.span.v2+json"
20+
}
21+
```
22+
23+
## Span v2 Envelope Item Payload
24+
25+
The envelope item payload must contain an `items` array with span one and up to 1000 span objects:
26+
27+
```json
28+
{
29+
"items": [
30+
{
31+
"trace_id": "6cf173d587eb48568a9b2e12dcfbea52",
32+
"parent_span_id": null,
33+
"span_id": "438f40bd3b4a41ee",
34+
"name": "GET /users",
35+
"status": "ok",
36+
"is_remote": true,
37+
"kind": "server",
38+
"start_timestamp": 1742921669.158209,
39+
"end_timestamp": 1742921669.180536,
40+
"attributes": {
41+
"sentry.release": {
42+
"type": "string",
43+
"value": "1.0.0"
44+
},
45+
"sentry.environment": {
46+
"type": "string",
47+
"value": "local"
48+
},
49+
"sentry.platform": {
50+
"type": "string",
51+
"value": "php"
52+
},
53+
"sentry.sdk.name": {
54+
"type": "string",
55+
"value": "sentry.php"
56+
},
57+
"sentry.sdk.version": {
58+
"type": "string",
59+
"value": "4.10.0"
60+
},
61+
"sentry.transaction_info.source": {
62+
"type": "string",
63+
"value": "route"
64+
},
65+
"sentry.origin": {
66+
"type": "string",
67+
"value": "auto"
68+
},
69+
"server.address": {
70+
"type": "string",
71+
"value": "127.0.0.1"
72+
},
73+
"http.response.status_code": {
74+
"type": "integer",
75+
"value": 200
76+
},
77+
"links": [
78+
{
79+
"span_id": "6c71fc6b09b8b716",
80+
"trace_id": "627a2885119dcc8184fae7eef09438cb",
81+
"sampled": true,
82+
"attributes": {
83+
"sentry.link.type": {
84+
"type": "string",
85+
"value": "previous_trace"
86+
}
87+
}
88+
}
89+
]
90+
},
91+
},
92+
{
93+
"trace_id": "6cf173d587eb48568a9b2e12dcfbea52",
94+
"parent_span_id": "438f40bd3b4a41ee",
95+
"span_id": "f1196292f76e45c0",
96+
"name": "app.handle",
97+
"status": "ok",
98+
"is_remote": false,
99+
"kind": "server",
100+
"start_timestamp": 1742921669.178306,
101+
"end_timestamp": 1742921669.180484,
102+
"attributes": {
103+
"sentry.origin": {
104+
"type": "string",
105+
"value": "auto"
106+
}
107+
}
108+
}
109+
]
110+
}
111+
```
112+
113+
## Span v2 Protocol Properties
114+
115+
### Envelope Item Header Properties
116+
117+
| Property | Type | Required | Description |
118+
|----------|------|----------|-------------|
119+
| `type` | string | Yes | Must be set to `"span"` to identify this as a span envelope item |
120+
| `item_count` | integer | Yes | Number of span items in the payload |
121+
| `content_type` | string | Yes | Must be set to `"application/vnd.sentry.items.span.v2+json"` |
122+
123+
### Span Properties
124+
125+
| Property | Type | Required | Description |
126+
|----------|------|----------|-------------|
127+
| `trace_id` | string | Yes | 32-character hexadecimal string (a valid uuid4 without dashes) |
128+
| `span_id` | string | Yes | 16-character hexadecimal string (a valid uuid4 without dashes) |
129+
| `parent_span_id` | string | No | 16-character hexadecimal string (a valid uuid4 without dashes) |
130+
| `name` | string | Yes | A low cardinality description of what the span represents (e.g., "GET /users", "database.query") |
131+
| `status` | string | Yes | Status of the span operation. Either `"ok"` or `"error"` |
132+
| `is_remote` | boolean | Yes | Whether the SpanContext creating the span was received from somewhere else or locally generated |
133+
| `kind` | string | Yes | The kind of span. Values: `"server"`, `"client"`, `"producer"`, `"consumer"`, `"internal"` |
134+
| `start_timestamp` | number | Yes | Unix timestamp (with fractional microseconds) when the span was started |
135+
| `end_timestamp` | number | Yes | Unix timestamp (with fractional microseconds) when the span was ended |
136+
| `attributes` | object | No | Key-value pairs containing additional metadata about the span |
137+
| `links` | array | No | Array of links connecting this span to other spans or traces |
138+
139+
### Attribute Object Properties
140+
141+
Attributes are stored as key-value pairs where each value is an object with type information:
142+
143+
| Property | Type | Required | Description |
144+
|----------|------|----------|-------------|
145+
| `type` | string | Yes | The data type of the attribute value. Values: `"string"`, `"integer"`, `"float"`, `"boolean"` |
146+
| `value` | any | Yes | The actual attribute value, must match the specified type |
147+
| `unit` | string | No | The unit of the attribute value. Example values: `"ms"`, `"s"`, `"bytes"`, `"count"`, `"percent"` |
148+
149+
#### Common Attribute Keys
150+
151+
| Attribute Key | Type | Description |
152+
|---------------|------|-------------|
153+
| `sentry.release` | string | The release version of the application |
154+
| `sentry.environment` | string | The environment name (e.g., "production", "staging", "development") |
155+
| `sentry.platform` | string | The platform/language (e.g., "php", "javascript", "python") |
156+
| `sentry.sdk.name` | string | Name of the Sentry SDK (e.g., "sentry.php", "sentry.javascript") |
157+
| `sentry.sdk.version` | string | Version of the Sentry SDK |
158+
159+
See [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) for a full list of supported attributes.
160+
161+
### Link Object Properties
162+
163+
Links connect spans to other spans or traces, enabling distributed tracing:
164+
165+
| Property | Type | Required | Description |
166+
|----------|------|----------|-------------|
167+
| `span_id` | string | Yes | 16-character hexadecimal string (a valid uuid4 without dashes) |
168+
| `trace_id` | string | Yes | 32-character hexadecimal string (a valid uuid4 without dashes) |
169+
| `sampled` | boolean | No | Whether the linked trace was sampled |
170+
| `attributes` | object | No | Additional metadata about the link relationship |
171+
172+
#### Link Attribute Keys
173+
174+
| Attribute Key | Type | Description |
175+
|---------------|------|-------------|
176+
| `sentry.link.type` | string | Type of link relationship (e.g., "previous_trace", "child_of", "follows_from") |
177+
178+
## Data Types and Formats
179+
180+
### Timestamp Format
181+
Timestamps use Unix time with fractional microseconds as a floating-point number:
182+
```
183+
1742921669.158209
184+
```
185+
186+
### ID Formats
187+
- **Trace ID**: 32-character (128 bits) lowercase hexadecimal string (a valid uuid4 without dashes)
188+
- **Span ID**: 16-character (64 bits) lowercase hexadecimal string (a valid uuid4 without dashes)
189+
190+
Example:
191+
```
192+
trace_id: "6cf173d587eb48568a9b2e12dcfbea52"
193+
span_id: "438f40bd3b4a41ee"
194+
```

0 commit comments

Comments
 (0)