Skip to content

Commit 82865fa

Browse files
tigrannajaryantigrannajaryan
authored
Declare freeze of Trace API Specification 1.0 (#1121)
* Declare freeze of Trace Specification 1.0 We want to freeze Trace specification 1.0 so that we no longer accept substantial changes (unless a fundamental problem is found in the spec). Resolves #1120
1 parent 1ebb9e0 commit 82865fa

File tree

6 files changed

+150
-123
lines changed

6 files changed

+150
-123
lines changed

‎specification/baggage/api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Baggage API
22

3+
**Status**: [Feature-freeze](../document-status.md).
4+
35
<details>
46
<summary>
57
Table of Contents

‎specification/common/attribute-and-label-naming.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Attribute and Label Naming
2+
3+
<details>
4+
<summary>
5+
Table of Contents
6+
</summary>
7+
8+
- [Name Pluralization Guidelines](#name-pluralization-guidelines)
9+
- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
10+
- [Recommendations for Application Developers](#recommendations-for-application-developers)
11+
12+
</details>
13+
14+
_This section applies to Resource, Span and Log attribute names (also known as
15+
the "attribute keys") and to keys of Metric labels. For brevity within this
16+
section when we use the term "name" without an adjective it is implied to mean
17+
"attribute name or metric label key"._
18+
19+
Every name MUST be a valid Unicode sequence.
20+
21+
_Note: we merely require that the names are represented as Unicode sequences.
22+
This specification does not define how exactly the Unicode sequences are
23+
encoded. The encoding can vary from one programming language to another and from
24+
one wire format to another. Use the idiomatic way to represent Unicode in the
25+
particular programming language or wire format._
26+
27+
Names SHOULD follow these rules:
28+
29+
- Use namespacing to avoid name clashes. Delimit the namespaces using a dot
30+
character. For example `service.version` denotes the service version where
31+
`service` is the namespace and `version` is an attribute in that namespace.
32+
33+
- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside
34+
top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute
35+
inside `telemetry.sdk` namespace.
36+
Note: the fact that an entity is located within another entity is typically
37+
not a sufficient reason for forming nested namespaces. The purpose of a
38+
namespace is to avoid name clashes, not to indicate entity hierarchies. This
39+
purpose should primarily drive the decision about forming nested namespaces.
40+
41+
- For each multi-word dot-delimited component of the attribute name separate the
42+
words by underscores (i.e. use snake_case). For example `http.status_code`
43+
denotes the status code in the http namespace.
44+
45+
- Names SHOULD NOT coincide with namespaces. For example if
46+
`service.instance.id` is an attribute name then it is no longer valid to have
47+
an attribute named `service.instance` because `service.instance` is already a
48+
namespace. Because of this rule be careful when choosing names: every existing
49+
name prohibits existence of an equally named namespace in the future, and vice
50+
versa: any existing namespace prohibits existence of an equally named
51+
attribute or label key in the future.
52+
53+
## Name Pluralization guidelines
54+
55+
- When an attribute represents a single entity, the attribute name SHOULD be singular.
56+
Examples: `host.name`, `db.user`, `container.id`.
57+
58+
- When attribute can represent multiple entities, the attribute name SHOULD be pluralized
59+
and the value type SHOULD be an array. E.g. `process.command_args` might include multiple
60+
values: the executable name and command arguments.
61+
62+
- When an attribute represents a measurement,
63+
[Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization)
64+
SHOULD be followed for the attribute name.
65+
66+
## Recommendations for OpenTelemetry Authors
67+
68+
- All names that are part of OpenTelemetry semantic conventions SHOULD be part
69+
of a namespace.
70+
71+
- When coming up with a new semantic convention make sure to check existing
72+
namespaces for
73+
[Resources](../resource/semantic_conventions/README.md),
74+
[Spans](../trace/semantic_conventions/README.md),
75+
and
76+
[Metrics](../metrics/semantic_conventions/README.md)
77+
to see if the new name fits.
78+
79+
- When a new namespace is necessary consider whether it should be a top-level
80+
namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).
81+
82+
- Semantic conventions exist for four areas: for Resource, Span and Log
83+
attribute names as well as Metric label keys. In addition, for spans we have
84+
two more areas: Event and Link attribute names. Identical namespaces or names
85+
in all these areas MUST have identical meanings. For example the `http.method`
86+
span attribute name denotes exactly the same concept as the `http.method`
87+
metric label, has the same data type and the same set of possible values (in
88+
both cases it records the value of the HTTP protocol's request method as a
89+
string).
90+
91+
- Semantic conventions MUST limit names to printable Basic Latin characters
92+
(more precisely to
93+
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
94+
subset of Unicode code points). It is recommended to further limit names to
95+
the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
96+
(as namespace delimiter).
97+
98+
## Recommendations for Application Developers
99+
100+
As an application developer when you need to record an attribute or a label
101+
first consult existing semantic conventions for
102+
[Resources](../resource/semantic_conventions/README.md),
103+
[Spans](../trace/semantic_conventions/README.md),
104+
and
105+
[Metrics](../metrics/semantic_conventions/README.md).
106+
If an appropriate name does not exists you will need to come up with a new name.
107+
To do that consider a few options:
108+
109+
- The name is specific to your company and may be possibly used outside the
110+
company as well. To avoid clashes with names introduced by other companies (in
111+
a distributed system that uses applications from multiple vendors) it is
112+
recommended to prefix the new name by your company's reverse domain name, e.g.
113+
`com.acme.shopname`.
114+
115+
- The name is specific to your application that will be used internally only. If
116+
you already have an internal company process that helps you to ensure no name
117+
clashes happen then feel free to follow it. Otherwise it is recommended to
118+
prefix the attribute name or label key by your application name, provided that
119+
the application name is reasonably unique within your organization (e.g.
120+
`myuniquemapapp.longitude` is likely fine). Make sure the application name
121+
does not clash with an existing semantic convention namespace.
122+
123+
- The name may be generally applicable to applications in the industry. In that
124+
case consider submitting a proposal to this specification to add a new name to
125+
the semantic conventions, and if necessary also to add a new namespace.
126+
127+
It is recommended to limit names to printable Basic Latin characters
128+
(more precisely to
129+
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
130+
subset of Unicode code points).

‎specification/common/common.md‎

Lines changed: 3 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
# Common specification concepts
22

3+
**Status**: [Feature-freeze](../document-status.md).
4+
35
<details>
46
<summary>
57
Table of Contents
68
</summary>
79

810
- [Attributes](#attributes)
9-
- [Attribute and Label Naming](#attribute-and-label-naming)
10-
- [Name Pluralization Guidelines](#name-pluralization-guidelines)
11-
- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors)
12-
- [Recommendations for Application Developers](#recommendations-for-application-developers)
1311

1412
</details>
1513

@@ -42,122 +40,4 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va
4240
both containing an array of strings to represent a mapping
4341
`header_keys[i] -> header_values[i]`).
4442

45-
## Attribute and Label Naming
46-
47-
_This section applies to Resource, Span and Log attribute names (also known as
48-
the "attribute keys") and to keys of Metric labels. For brevity within this
49-
section when we use the term "name" without an adjective it is implied to mean
50-
"attribute name or metric label key"._
51-
52-
Every name MUST be a valid Unicode sequence.
53-
54-
_Note: we merely require that the names are represented as Unicode sequences.
55-
This specification does not define how exactly the Unicode sequences are
56-
encoded. The encoding can vary from one programming language to another and from
57-
one wire format to another. Use the idiomatic way to represent Unicode in the
58-
particular programming language or wire format._
59-
60-
Names SHOULD follow these rules:
61-
62-
- Use namespacing to avoid name clashes. Delimit the namespaces using a dot
63-
character. For example `service.version` denotes the service version where
64-
`service` is the namespace and `version` is an attribute in that namespace.
65-
66-
- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside
67-
top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute
68-
inside `telemetry.sdk` namespace.
69-
Note: the fact that an entity is located within another entity is typically
70-
not a sufficient reason for forming nested namespaces. The purpose of a
71-
namespace is to avoid name clashes, not to indicate entity hierarchies. This
72-
purpose should primarily drive the decision about forming nested namespaces.
73-
74-
- For each multi-word dot-delimited component of the attribute name separate the
75-
words by underscores (i.e. use snake_case). For example `http.status_code`
76-
denotes the status code in the http namespace.
77-
78-
- Names SHOULD NOT coincide with namespaces. For example if
79-
`service.instance.id` is an attribute name then it is no longer valid to have
80-
an attribute named `service.instance` because `service.instance` is already a
81-
namespace. Because of this rule be careful when choosing names: every existing
82-
name prohibits existence of an equally named namespace in the future, and vice
83-
versa: any existing namespace prohibits existence of an equally named
84-
attribute or label key in the future.
85-
86-
### Name Pluralization guidelines
87-
88-
- When an attribute represents a single entity, the attribute name SHOULD be singular.
89-
Examples: `host.name`, `db.user`, `container.id`.
90-
91-
- When attribute can represent multiple entities, the attribute name SHOULD be pluralized
92-
and the value type SHOULD be an array. E.g. `process.command_args` might include multiple
93-
values: the executable name and command arguments.
94-
95-
- When an attribute represents a measurement,
96-
[Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization)
97-
SHOULD be followed for the attribute name.
98-
99-
### Recommendations for OpenTelemetry Authors
100-
101-
- All names that are part of OpenTelemetry semantic conventions SHOULD be part
102-
of a namespace.
103-
104-
- When coming up with a new semantic convention make sure to check existing
105-
namespaces for
106-
[Resources](../resource/semantic_conventions/README.md),
107-
[Spans](../trace/semantic_conventions/README.md),
108-
and
109-
[Metrics](../metrics/semantic_conventions/README.md)
110-
to see if the new name fits.
111-
112-
- When a new namespace is necessary consider whether it should be a top-level
113-
namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).
114-
115-
- Semantic conventions exist for four areas: for Resource, Span and Log
116-
attribute names as well as Metric label keys. In addition, for spans we have
117-
two more areas: Event and Link attribute names. Identical namespaces or names
118-
in all these areas MUST have identical meanings. For example the `http.method`
119-
span attribute name denotes exactly the same concept as the `http.method`
120-
metric label, has the same data type and the same set of possible values (in
121-
both cases it records the value of the HTTP protocol's request method as a
122-
string).
123-
124-
- Semantic conventions MUST limit names to printable Basic Latin characters
125-
(more precisely to
126-
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
127-
subset of Unicode code points). It is recommended to further limit names to
128-
the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
129-
(as namespace delimiter).
130-
131-
### Recommendations for Application Developers
132-
133-
As an application developer when you need to record an attribute or a label
134-
first consult existing semantic conventions for
135-
[Resources](../resource/semantic_conventions/README.md),
136-
[Spans](../trace/semantic_conventions/README.md),
137-
and
138-
[Metrics](../metrics/semantic_conventions/README.md).
139-
If an appropriate name does not exists you will need to come up with a new name.
140-
To do that consider a few options:
141-
142-
- The name is specific to your company and may be possibly used outside the
143-
company as well. To avoid clashes with names introduced by other companies (in
144-
a distributed system that uses applications from multiple vendors) it is
145-
recommended to prefix the new name by your company's reverse domain name, e.g.
146-
`com.acme.shopname`.
147-
148-
- The name is specific to your application that will be used internally only. If
149-
you already have an internal company process that helps you to ensure no name
150-
clashes happen then feel free to follow it. Otherwise it is recommended to
151-
prefix the attribute name or label key by your application name, provided that
152-
the application name is reasonably unique within your organization (e.g.
153-
`myuniquemapapp.longitude` is likely fine). Make sure the application name
154-
does not clash with an existing semantic convention namespace.
155-
156-
- The name may be generally applicable to applications in the industry. In that
157-
case consider submitting a proposal to this specification to add a new name to
158-
the semantic conventions, and if necessary also to add a new namespace.
159-
160-
It is recommended to limit names to printable Basic Latin characters
161-
(more precisely to
162-
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
163-
subset of Unicode code points).
43+
See [Attribute and Label Naming](attribute-and-label-naming.md) for naming guidelines.

‎specification/context/context.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Context
22

3+
**Status**: [Feature-freeze](../document-status.md).
4+
35
<details>
46
<summary>
57
Table of Contents

‎specification/document-status.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Definitions of Document Statuses
2+
3+
Specification documents (files) may explicitly define a "Status", typically
4+
shown immediately after the document title. When present, the "Status" applies
5+
to the individual document only and not to the entire specification or any other
6+
documents. The following table describes what the statuses mean.
7+
8+
|Status |Explanation|
9+
|--------------------|-----------|
10+
|No explicit "Status"|Working draft, can change any time.|
11+
|Feature-freeze |Document is no longer accepting new substantial changes, except when such changes are necessary to resolve a fundamental problem or inconsistency in the specification. Editorial changes are accepted. The document and the area it describes are considered feature-complete for the version of the specification the document targets. The document in this status is ready for implementation.|

‎specification/trace/api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Tracing API
22

3+
**Status**: [Feature-freeze](../document-status.md).
4+
35
<details>
46
<summary>
57
Table of Contents

0 commit comments

Comments
 (0)