Skip to content

Commit fefb2fb

Browse files
tothmanotothmano
authored
Update OTel semconv (#305)
1 parent e519d50 commit fefb2fb

File tree

4 files changed

+180
-59
lines changed

4 files changed

+180
-59
lines changed

‎docs.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,9 @@
245245
"reference/introduction",
246246
"reference/cli",
247247
"reference/datasets",
248-
"reference/query-hours"
248+
"reference/query-hours",
249+
"reference/semantic-conventions",
250+
"reference/system-requirements"
249251
]
250252
},
251253
{

‎query-data/traces.mdx

Lines changed: 10 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -174,57 +174,9 @@ Top five errors per service and operation
174174
| limit 5
175175
```
176176

177-
## Semantic Conventions
177+
## Semantic conventions
178178

179-
OpenTelemetry defines [Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) which specify standard attribute names and values for different kinds of operations and data. Attributes that follow semantic conventions will be available as nested fields under the `attributes` field, such as `attributes.http.method`, `attributes.db.system`, etc.
180-
181-
For example, if a span represents an HTTP request, it may include the following attributes:
182-
183-
- `attributes.http.method`: The HTTP request method. For example, `GET`, `POST`, etc.
184-
- `attributes.http.url`: The full HTTP request URL.
185-
- `attributes.http.status_code`: The HTTP response status code.
186-
187-
Similarly, resource attributes that follow semantic conventions are available under the `resource` field, such as `resource.host.name`, `resource.host.id`, `resource.host.os`, etc.
188-
189-
Custom attributes that don’t match any semantic conventions are nested under the `attributes.custom` map field.
190-
191-
Axiom defaults to the version 1.25.0 of OTel semantic conventions. The supported versions are the following:
192-
- 1.21.0
193-
- 1.22.0
194-
- 1.23.0
195-
- 1.23.1
196-
- 1.24.0
197-
- 1.25.0
198-
- 1.26.0
199-
200-
## Querying custom attributes
201-
202-
Trace spans often include many custom attributes under the `attributes.custom` field. These custom attributes are stored as nested key-value pairs.
203-
204-
To access nested custom attributes, you can use Axiom Processing Language (APL) for example:
205-
206-
```kusto
207-
['otel-demo-traces']
208-
| where ['attributes.custom']['app.synthetic_request'] == true
209-
```
210-
211-
If you frequently need to query the same nested attribute, consider creating a virtual field for it:
212-
213-
1. Go to "Datasets" and click the f(x) button
214-
2. Define the new virtual field, for example:
215-
216-
```kusto
217-
['otel-demo-traces']
218-
| extend useragent = ['attributes.custom']['User-Agent']
219-
```
220-
221-
3. You can then query the virtual field like any other field in the UI or APL.
222-
223-
To create a typed virtual field, you can specify the type, e.g.:
224-
225-
```kusto
226-
| extend deployment_id = tostring(['attributes.custom']['deployment_id'])
227-
```
179+
[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) specify standard attribute names and values for different kinds of operations and data. For more information on Axiom’s support for OTel semantic conventions and what it means for your data, see [Semantic conventions](/reference/semantic-conventions).
228180

229181
## Span links
230182

@@ -240,13 +192,13 @@ Span links in Axiom are based on the [OpenTelemetry specification](https://opent
240192

241193
1. Run the following APL query to find traces with span links, for example:
242194

243-
```kusto
244-
['dataset']
245-
| where isnotempty(links)
246-
```
195+
```kusto
196+
['dataset']
197+
| where isnotempty(links)
198+
```
247199

248-
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%20%22%5B%27otel-demo-traces%27%5D%5Cn%7C%20where%20isnotempty%28links%29%22%7D)
200+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%20%22%5B%27otel-demo-traces%27%5D%5Cn%7C%20where%20isnotempty%28links%29%22%7D)
249201

250-
2. Click on a trace in the results and select the `trace_id`.
251-
3. In the trace details view, find the links section. This displays the `trace_id` and `span_id` associated with each linked span, as well as other attributes of the link.
252-
4. Click **View span** to navigate to a linked span, either in the same trace or a different trace.
202+
1. Click on a trace in the results and select the `trace_id`.
203+
1. In the trace details view, find the links section. This displays the `trace_id` and `span_id` associated with each linked span, as well as other attributes of the link.
204+
1. Click **View span** to navigate to a linked span, either in the same trace or a different trace.

‎reference/semantic-conventions.mdx

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Semantic conventions
3+
description: 'This page explains Axiom’s support for OTel semantic conventions and what it means for your data.'
4+
---
5+
6+
[OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) specify standard attribute names and values for different kinds of operations and data.
7+
8+
## Trace attributes in Axiom
9+
10+
The OTel trace attributes you send to Axiom are available under the following fields:
11+
12+
- Attributes that follow semantic conventions are nested fields under the `attributes` field. For example, `attributes.http.method` or `attributes.http.url`.
13+
- Resource attributes that follow semantic conventions are nested fields under the `resource` field. For example, `resource.host.name` or `resource.host.id`.
14+
- Custom attributes that don’t match any semantic conventions are nested fields under the `attributes.custom` map field.
15+
16+
For more information on map fields and querying nested fields, see [Map fields](/apl/data-types/map-fields).
17+
18+
## Supported versions
19+
20+
For the versions of OTel semantic conventions that Axiom supports, see [System requirements](/reference/system-requirements#opentelemetry).
21+
22+
(Recommended) When you send OTel data to Axiom, include the version of the OTel semantic conventions that your data follows. This ensures that your data is properly shaped in Axiom.
23+
24+
If you don’t define the version and Axiom can’t detect it, Axiom defaults to the version specified in [System requirements](/reference/system-requirements#opentelemetry). In this case, Axiom nests attributes that don’t match the semantic conventions of the default version under the `attributes.custom` map field.
25+
26+
## Semantic conventions upgrades
27+
28+
To guarantee the best logging experience with OTel, Axiom regularly updates the list of supported versions of semantic conventions and sometimes the default version. These updates can change the shape of your data. Axiom announces these changes in the [Changelog](https://axiom.co/changelog) and you might need to take action:
29+
30+
- If you send data to Axiom using an unsupported version of OTel semantic conventions, be aware that the shape of your data can change when Axiom adds support for new versions.
31+
- When you send OTel data to Axiom, include the version of the OTel semantic conventions that your data follows. This ensures that your data is properly shaped in Axiom and it won’t be affected when Axiom changes the default version.
32+
33+
In addition, the shape of your data can change when you choose to migrate to a newer version of OTel semantic conventions.
34+
35+
See the sections below for more details on how your data can change and the actions you need to take when this happens.
36+
37+
### Changes to list of supported versions
38+
39+
After Axiom adds support for new versions of OTel semantic conventions, the shape of your data can change when the following are all true:
40+
41+
- Before the update, you sent data to Axiom using an unsupported version of OTel semantic conventions.
42+
- After the update, the version of OTel semantic conventions that you used becomes supported.
43+
44+
In this case, the shape of your data can change:
45+
46+
- Before the update, attributes that Axiom couldn’t match to the previously supported semantic conventions were nested under the `attributes.custom` map field.
47+
- After the update, Axiom matches these attributes to the newly supported semantic conventions. The newly recognised attributes are nested under the `attributes` or `resource` fields, similarly to all other attributes that follow semantic conventions.
48+
49+
When the shape of your data changes, you need to [take action](#take-action-when-shape-of-data-changes).
50+
51+
### Changes to default version
52+
53+
If you don’t specify the version of the OTel semantic conventions that your data follows when you send OTel data to Axiom, Axiom interprets the data using the default version.
54+
55+
After Axiom changes the default version of OTel semantic conventions, the shape of your data can change when you don’t specify the version of the OTel semantic conventions in the data you send to Axiom. For this reason, to prevent changes to your data, include the version of the OTel semantic conventions that your data follows when you send OTel data to Axiom. This ensures that your data is properly shaped in Axiom and it won’t be affected when Axiom changes the default version.
56+
57+
When Axiom updates the default version of OTel semantic conventions, the shape of your data can change:
58+
59+
- Before the update, attributes that become supported between the old and the new default versions are nested under the `attributes.custom` field. After the update, these attributes are nested under the `attributes` or `resource` fields.
60+
- Before the update, attributes that became deprecated between the old and the new default versions are nested under the `attributes` or `resource` fields. After the update, these attributes are nested under the `attributes.custom` field.
61+
62+
When the shape of your data changes, you need to [take action](#take-action-when-shape-of-data-changes).
63+
64+
### Migrate to new version
65+
66+
When you choose to migrate to a newer version of OTel semantic conventions, the shape of your data can change. Some attributes can become supported, deprecated, renamed, or relocated.
67+
68+
When the shape of your data changes, you need to [take action](#take-action-when-shape-of-data-changes).
69+
70+
### Determine changes between versions
71+
72+
To determine the changes between different versions of OTel semantic conventions, compare the [schema files](https://github.com/open-telemetry/semantic-conventions/tree/main/schemas) or the [changelog](https://github.com/open-telemetry/semantic-conventions/releases) in the OTel documentation. This informs you about how the shape of your data can change as a result of semantic conventions upgrades.
73+
74+
## Take action when shape of data changes
75+
76+
When some attributes are relocated or renamed, the shape of your data changes and you need to take action.
77+
78+
For example, assume that Axiom supports OTel semantic conventions up to version 1.25. You send data to Axiom that follows version 1.32 and you don’t specify the version. On June 12th 2025, Axiom adds support for versions up to 1.32 and makes version 1.32 the default. The following happens with the attribute `db.system.name`:
79+
80+
- You send the attribute `db.system.name` to Axiom because your data follows version 1.32. The shape of the data you send to Axiom doesn’t change during the update.
81+
- Before the update, Axiom interpreted your data using the old default version 1.25. It didn’t recognize `db.system.name` and nested it under `attributes.custom`.
82+
- After the update, Axiom interprets your data using the new default version 1.32. It recognizes `db.system.name` properly and nests it under `attributes`.
83+
84+
As a result, the attribute is relocated from `['attributes.custom']['db.system.name']` to `['attributes.db.system.name']`. You need to update all saved queries, dashboards, or monitors that reference the attribute. You have the following options:
85+
86+
- [Update queries to reference the new location](#reference-new-location)
87+
- [Update queries to reference both locations](#reference-both-locations)
88+
89+
### Reference new location
90+
91+
When you update affected queries to reference the new location, the query results only include data you send after the semantic conventions upgrade.
92+
93+
For example, a saved query references the old location before the update:
94+
95+
```kusto
96+
['otel-demo-traces']
97+
| where ['service.name'] == "frontend"
98+
| project ['attributes.custom']['db.system.name']
99+
```
100+
101+
After the update, change the query to the following:
102+
103+
```kusto
104+
['otel-demo-traces']
105+
| where ['service.name'] == "frontend"
106+
| project ['attributes.db.system.name']
107+
```
108+
109+
### Reference both locations
110+
111+
To ensure that affected queries include data from the attribute that you send before and after the semantic conventions upgrade, use [coalesce](/apl/scalar-functions/string-functions#coalesce) in your query. This function evaluates a list of expressions and returns the first non-null value. In this case, pass the old and the new locations of the attribute to the `coalesce` function.
112+
113+
For example, a saved query references the old location before the update:
114+
115+
```kusto
116+
['otel-demo-traces']
117+
| where ['service.name'] == "frontend"
118+
| project ['attributes.custom']['db.system.name']
119+
```
120+
121+
After the update, change the query to the following:
122+
123+
```kusto
124+
['otel-demo-traces']
125+
| where ['service.name'] == "frontend"
126+
| project coalesce(['attributes.custom']['db.system.name'], ['attributes.db.system.name'])
127+
```

‎reference/system-requirements.mdx

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: 'System requirements'
3+
description: 'This page explains what versions of third-party applications Axiom supports.'
4+
---
5+
6+
## Browsers and platforms
7+
8+
The Axiom web app supports the latest versions of the following browsers and platforms:
9+
10+
| Browser / platform | Android | iOS | macOS | Linux | Windows |
11+
|--------------------|---------|-------|-------|-------|------------|
12+
| Chrome | ✅ | ✅ | ✅ | ✅ | ✅ |
13+
| Edge | ✅ | ✅ | ✅ | ✅ | ✅ |
14+
| Firefox | ✅ | ✅ | ✅ | ✅ | ✅ |
15+
| Safari | | ✅ | ✅ | | |
16+
17+
Some actions in the Dashboards tab, such as moving dashboard elements, aren’t supported in mobile view.
18+
19+
## OpenTelemetry
20+
21+
Axiom supports the following versions of OTel semantic conventions:
22+
23+
| Version | Date when supported added | Schema in OTel docs |
24+
| --- | --- | --- |
25+
| 1.32.0 (default) | 12-06-2025 | [1.32.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.32.0) |
26+
| 1.31.0 | 12-06-2025 | [1.31.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.31.0) |
27+
| 1.30.0 | 12-06-2025 | [1.30.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.30.0) |
28+
| 1.28.0 | 12-06-2025 | [1.28.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.28.0) |
29+
| 1.27.0 | 12-06-2025 | [1.27.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.27.0) |
30+
| 1.26.0 | 03-07-2024 | [1.26.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.26.0) |
31+
| 1.25.0 | 26-04-2024 | [1.25.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.25.0) |
32+
| 1.24.0 | 19-01-2024| [1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.24.0) |
33+
| 1.23.1 | 26-03-2024 | [1.23.1](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.23.1) |
34+
| 1.23.0 | 26-03-2024 | [1.23.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.23.0) |
35+
| 1.22.0 | 26-03-2024 | [1.22.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.22.0) |
36+
| 1.21.0 | 26-03-2024 | [1.21.0](https://github.com/open-telemetry/semantic-conventions/blob/main/schemas/1.21.0) |
37+
38+
Version 1.29.0 of OTel semantic conventions isn’t supported.
39+
40+
For more information, see [Semantic conventions](/reference/semantic-conventions).

0 commit comments

Comments
 (0)