Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide clear guidance on what semconv actually enforces #3225

Merged
merged 46 commits into from
Apr 3, 2023
Merged
Changes from 38 commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
f037c83
Fix #2864 with more clear guidance on what is enforced by semconv tha…
jsuereth Feb 17, 2023
f1890e8
Update specification/versioning-and-stability.md
jsuereth Feb 17, 2023
a4f8505
Update specification/versioning-and-stability.md
jsuereth Feb 17, 2023
453e8a5
Update specification/versioning-and-stability.md
jsuereth Feb 17, 2023
7594646
Add span kind to enforced span conventions.
jsuereth Feb 17, 2023
5a66d17
Clarify semantic convention stability.
jsuereth Feb 21, 2023
cb088de
Update specification/versioning-and-stability.md
jsuereth Feb 21, 2023
e67cdb1
[editorial] Fix Tencent Cloud link (#3231)
chalin Feb 20, 2023
bfc0709
Remove SergeyKanzhelev from auto-assignment (#3229)
SergeyKanzhelev Feb 20, 2023
4911aca
Update supplementary-guidelines.md (#3230)
chalin Feb 20, 2023
403a298
[editorial] normalize link to prometheus docs (#3232)
chalin Feb 20, 2023
77137f0
Rename `faas.execution` to `faas.invocation_id` and change units for …
tylerbenson Feb 20, 2023
831a045
Add Connect RPC to semantic conventions (#3116)
joshcarp Feb 21, 2023
87ddbcd
Update data-model.md (#3233)
chalin Feb 21, 2023
5316e5f
Add unit to Instrument selection criteria (#3184)
asafm Feb 21, 2023
75d40a6
Fix typos and grammar in the OTLP spec (#3121)
moonbox3 Feb 22, 2023
fed1172
Update logs spec overview to use Logs Bridge API (#3248)
arminru Feb 22, 2023
98c689b
Metric requirement levels (#3237)
trask Feb 23, 2023
e97813c
Mark Attribute naming conventions as stable. (#3220)
jsuereth Feb 23, 2023
212ae98
Mark telemetry schema readme stable. (#3221)
jsuereth Feb 24, 2023
2416a26
Add jack-berg to auto assignment for issues and PRs (#3255)
arminru Feb 24, 2023
7675781
Rename nonheap to non_heap (#3250)
trask Feb 24, 2023
8b86484
Move event language from log README to event-api (#3252)
jack-berg Feb 24, 2023
ab0db31
add semantic conventions for heroku (#3075)
atoulme Feb 27, 2023
5874bbb
Expand scope of `faas.id` to `cloud.resource_id` (#3188)
tylerbenson Feb 27, 2023
a32984f
Update build-tools to 1.16.0 (#3259)
tigrannajaryan Feb 27, 2023
3c028dd
Add logging to enforced fields. Also fix verbage around API.
jsuereth Feb 28, 2023
c5c85e5
Added span attribute 'time' concerns.
jsuereth Feb 28, 2023
cfeb784
Reworded 'enforce' section.
jsuereth Feb 28, 2023
845c452
Merge branch 'main' into pr-metric-stability
jsuereth Feb 28, 2023
e2b9fe0
Put rationale for enum stability in the specification.
jsuereth Feb 28, 2023
e4082df
Update specification/versioning-and-stability.md
jsuereth Mar 1, 2023
7e7e626
Update specification/versioning-and-stability.md
jsuereth Mar 2, 2023
871c103
Update specification/versioning-and-stability.md
jsuereth Mar 2, 2023
2723805
Update specification/versioning-and-stability.md
jsuereth Mar 2, 2023
43e083a
Update specification/versioning-and-stability.md
jsuereth Mar 2, 2023
f27bb26
Update specification/versioning-and-stability.md
jsuereth Mar 6, 2023
af69829
Update specification/versioning-and-stability.md
jsuereth Mar 7, 2023
5b31117
Merge branch 'main' into pr-metric-stability
jsuereth Mar 13, 2023
d496b51
Another crack at wording improvements.
jsuereth Mar 13, 2023
7bc998d
Merge branch 'main' into pr-metric-stability
reyang Mar 20, 2023
edc7efb
Merge branch 'main' into pr-metric-stability
jsuereth Mar 23, 2023
a9536de
Merge branch 'main' into pr-metric-stability
jmacd Mar 27, 2023
2df7d15
Merge branch 'main' into pr-metric-stability
jsuereth Apr 3, 2023
1418d33
Fixes from review and add changelog.
jsuereth Apr 3, 2023
26d1813
Fix markdownlint.
jsuereth Apr 3, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 54 additions & 2 deletions specification/versioning-and-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,58 @@ allowing the evolution of telemetry and semantic conventions, OpenTelemetry
relies on the concept of
[Telemetry Schemas](schemas/README.md).

Semantic Conventions defines breaking changes as those that would break the
"API" of tooling written against the telemetry it produces. That is, the portions
of telemetry where specialized tooling (alerts, dashboards, e.g.) interact are
expected to remain stable for that tooling after schema transformations are applied. Semantic Conventions defines the
set of fields to which stability concerns apply as follows:

- [Resource](resource/sdk.md)
- attribute keys provided to Create resource detectors
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
- [Trace](trace/api.md)
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- Attribute keys provided to [get a tracer](trace/api.md#get-a-tracer)
- The following data provided to [span](trace/api.md#span) by available APIs:
- The span name
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- The span kind
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- The attribute keys provided to the span
- Whether these attributes must be provided at span start time, due to
sampling concerns.
- The following data provided when [adding an event](trace/api.md#add-events)
- The event name
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- The attribute keys provided for the event
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- [Metrics](metrics/api.md)
- Attribute keys provided to [get a meter](metrics/api.md#get-a-meter)
- The following arguments when constructing [an instrument](metrics/api.md#instrument):
- The name of the instrument
- The kind of instrument
- For `Counter` and `UpDownCounter` instruments, it is
acceptable to change between asynchronous and synchronous instruments.
- the unit of the instrument.
- The attribute keys provided when recording a measurement, for
both synchronous and asynchronous instruments.
- [Log Records](logs/bridge-api.md#logrecord)
- The attribute keys provided on the LogRecord
- [Log Events](logs/event-api.md)
- The following data provided to [emit event](logs/event-api.md#emit-event):
- The event name
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- The event domain
- The components of [LogRecord](logs/bridge-api.md#logrecord) also
listed here.

Things not listed in the above are not enforced via semantic convention and are allowed (or expected) to change. A few examples:
pyohannes marked this conversation as resolved.
Show resolved Hide resolved

- The values of attributes
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- Specifically for `enums` the list of allowed values is expected to change
overtime.
- Even for `enums` that limit allowed values to semconv, some may need to
updated values in the future.
- The links attached to a span
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
- The recorded measurement type (float or integer) of a metric is not enforced and allowed to change.
- The description of a metric instrument.
- The values being recorded by an instrument.

The list of telemetry fields which are covered by stability guarantees MAY be extended.

Changes to semantic conventions in this specification are allowed, provided that
the changes can be described by schema files. The following changes can be
currently described and are allowed:
Expand All @@ -181,8 +233,8 @@ that are always allowed. Such changes do not need to be described (and are not
described) by schema files. Here is the list of such changes:

- Adding new attributes to the existing semantic conventions for resources,
spans, span events or log records. Note that adding attributes to existing metrics is
considered to be a breaking change.
spans, span events or log records.
- Adding new attributes to existing metrics that do not create new timeseries.
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
- Adding semantic conventions for new types of resources, spans, span events,
metrics or log records.

Expand Down