Merge branch 'main' into pod-annotations

CHANGELOG.md

@@ -18,6 +18,8 @@ release.
 - Rename metrics `jvm.memory.usage` to `jvm.memory.used` and `jvm.memory.usage_after_last_gc`
   to `jvm.memory.used_after_last_gc`
   ([#536](https://github.com/open-telemetry/semantic-conventions/pull/536))
+- BREAKING: Change `event.name` definition to include `namespace` and remove `event.domain` from log event attributes.
+  ([#473](https://github.com/open-telemetry/semantic-conventions/pull/473))
 
 ### Features
 
@@ -36,6 +38,8 @@ release.
 
 - Remove misleading pluralization wording related to count metrics
   ([#488](https://github.com/open-telemetry/semantic-conventions/pull/488))
+- Remove no longer relevant Oct 1 mention from `OTEL_SEMCONV_STABILITY_OPT_IN`
+  ([#541](https://github.com/open-telemetry/semantic-conventions/pull/541))
 
 ## v1.23.0 (2023-11-03)
 

CONTRIBUTING.md

@@ -30,6 +30,8 @@ key, but non-obvious, aspects:
   defined in a schema file. As part of any contribution, you should
   include attribute changes defined in the `schema-next.yaml` file.
   For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
+- Links to the specification repository MUST point to a tag and **not** to the `main` branch.
+  The tag version MUST match with the one defined in [README](README.md).
 - After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
   a description of your changes.
 

README.md

@@ -1,15 +1,16 @@
-# OpenTelemetry Semantic Conventions
+# <img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OpenTelemetry Icon" width="45" height=""> OpenTelemetry Semantic Conventions
 
-Welcome to the new repository!
+[![Checks](https://github.com/open-telemetry/semantic-conventions/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/semantic-conventions/actions?query=workflow%3A%22Checks%22+branch%3Amain)
+[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/semantic-conventions.svg?logo=opentelemetry&&color=f5a800&label=Latest%20release)](https://github.com/open-telemetry/semantic-conventions/releases/latest)
+[![Specification Version](https://img.shields.io/badge/OTel_specification_version-v1.26.0-blue?logo=opentelemetry&color=f5a800)](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.26.0)
 
-This is currently a direct copy/filter-branch of the Specification repository
-with only semantic conventions included.
-
-This repository is currently using [this specification version][SpecificationVersion].
+Semantic Conventions define a common set of (semantic) attributes which
+provide meaning to data when collecting, producing and consuming it.
 
 ## Read the docs
 
-The documentation currently resides in the [docs](docs/README.md) folder.
+The human-readable version of the semantic conventions resides in the [docs](docs/README.md) folder.
+Major parts of these Markdown documents are generated from the YAML definitions located in the [model](model/README.md) folder.
 
 ## Contributing
 
@@ -34,6 +35,4 @@ Maintainers ([@open-telemetry/specs-semconv-maintainers](https://github.com/orgs
 - [Josh Suereth](https://github.com/jsuereth), Google
 - [Reiley Yang](https://github.com/reyang), Microsoft
 
-_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._
-
-[SpecificationVersion]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0
+_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).

docs/attributes-registry/README.md

@@ -34,6 +34,7 @@ Currently, the following namespaces exist:
 * [DB](db.md) (database)
 * [Destination](destination.md)
 * [Device](device.md)
+* [Disk](disk.md)
 * [Error](error.md)
 * [Host](host.md)
 * [HTTP](http.md)

docs/attributes-registry/disk.md

@@ -0,0 +1,19 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Disk
+
+## Disk Attributes
+
+<!-- semconv registry.disk(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `disk.io.direction` | string | The disk IO operation direction. | `read` |
+
+`disk.io.direction` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `read` | read |
+| `write` | write |
+<!-- endsemconv -->

docs/attributes-registry/network.md

@@ -16,6 +16,7 @@ These attributes may be used for any network related operation.
 | `network.carrier.name` | string | The name of the mobile carrier. | `sprint` |
 | `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` |
 | `network.connection.type` | string | The internet connection type. | `wifi` |
+| `network.io.direction` | string | The network IO operation direction. | `transmit` |
 | `network.local.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` |
 | `network.local.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Local port number of the network connection. | `65123` |
 | `network.peer.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` |
@@ -73,6 +74,13 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 | `unavailable` | unavailable |
 | `unknown` | unknown |
 
+`network.io.direction` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `transmit` | transmit |
+| `receive` | receive |
+
 `network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 
 | Value  | Description |

docs/database/database-spans.md

@@ -41,8 +41,7 @@ linkTitle: Client Calls
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 **Span kind:** MUST always be `CLIENT`.
 

docs/faas/aws-lambda.md

@@ -66,7 +66,7 @@ contain an incomplete trace context which indicates X-Ray isn’t enabled. The e
 `Context` will be valid and sampled only if AWS X-Ray has been enabled for the Lambda function. A user can
 disable AWS X-Ray for the function if the X-Ray Span Link is not desired.
 
-**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above.
+**Note**: When instrumenting a Java AWS Lambda, instrumentation SHOULD first try to parse an OpenTelemetry `Context` out of the system property `com.amazonaws.xray.traceHeader` using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/context/api-propagators.md) before checking and attempting to parse the environment variable above.
 
 [Span Link]: https://opentelemetry.io/docs/concepts/signals/traces/#span-links
 

docs/general/events.md

@@ -17,20 +17,10 @@ The following semantic conventions for events are defined:
 
 ## General event attributes
 
-Events are recorded as LogRecords that are shaped
-in a special way: Event LogRecords have the attributes `event.domain`
-and `event.name` (and possibly other LogRecord attributes).
-
-The `event.domain` attribute is used to logically separate events from different
-systems. For example, to record Events from browser apps, mobile apps and
-Kubernetes, we could use `browser`, `device` and `k8s` as the domain for their
-Events. This provides a clean separation of semantics for events in each of the
-domains.
-
-Within a particular domain, the `event.name` attribute identifies the event.
-Events with same domain and name are structurally similar to one another. For
-example, some domains could have well-defined schema for their events based on
-event names.
+Events are recorded as LogRecords that are shaped in a special way: Event
+LogRecords have the attribute `event.name` that uniquely identifies the event.
+Events with same `event.name` are structurally similar to one another. Events
+may also have other LogRecord attributes.
 
 When recording events from an existing system as OpenTelemetry Events, it is
 possible that the existing system does not have the equivalent of a name or
@@ -43,18 +33,9 @@ that identify the class of Events but not the instance of the Event.
 <!-- semconv event -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required |
-| `event.name` | string | The name identifies the event. | `click`; `exception` | Required |
-
-**[1]:** Events across different domains may have same `event.name`, yet be unrelated events.
-
-`event.domain` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | Required |
 
-| Value  | Description |
-|---|---|
-| `browser` | Events from browser apps |
-| `device` | Events from mobile apps |
-| `k8s` | Events from Kubernetes |
+**[1]:** Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md

docs/http/README.md

@@ -37,8 +37,7 @@ and various HTTP versions like 1.1, 2 and SPDY.
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 Semantic conventions for HTTP are defined for the following signals:
 

docs/http/http-metrics.md

@@ -50,8 +50,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 ## HTTP Server
 

docs/http/http-spans.md

@@ -61,8 +61,7 @@ and various HTTP versions like 1.1, 2 and SPDY.
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 ## Name
 

docs/messaging/messaging-spans.md

@@ -59,8 +59,7 @@
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 ## Definitions
 
@@ -211,7 +210,7 @@ The following operations related to messages are defined for these semantic conv
 
 ### Span kind
 
-[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind)
+[Span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#spankind)
 SHOULD be set according to the following table, based on the operation a span describes.
 
 | Operation name | Span kind|
@@ -222,7 +221,7 @@ SHOULD be set according to the following table, based on the operation a span de
 | `deliver`      | `CONSUMER` |
 
 For cases not covered by the table above, the span kind should be set according
-to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#spankind),
+to the [generic specification about span kinds](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/trace/api.md#spankind),
 e. g. it should be set to CLIENT for the "Publish" span if its context is not
 used as creation context and if the "Publish" span models a synchronous call to
 the intermediary.

docs/mobile/events.md

@@ -2,8 +2,9 @@
 
 **Status**: [Experimental][DocumentStatus]
 
-This document defines semantic conventions for instrumentations that emit events on mobile platforms.
-All mobile events MUST set `event.domain` as `device`.
+This document defines semantic conventions for instrumentations that emit
+events on mobile platforms. All mobile events MUST use a namespace of
+`device` in the `event.name` property.
 
 <!-- toc -->
 
@@ -15,13 +16,15 @@ All mobile events MUST set `event.domain` as `device`.
 
 ## Lifecycle instrumentation
 
-This section defines how to apply semantic conventions when instrumenting application lifecycle.
-This event is meant to be used in conjunction with `os.name` [resource semantic convention](/docs/resource/os.md) to identify the mobile operating system (e.g. Android, iOS).
+This section defines how to apply semantic conventions when instrumenting
+application lifecycle. This event is meant to be used in conjunction with
+`os.name` [resource semantic convention](/docs/resource/os.md) to identify the
+mobile operating system (e.g. Android, iOS).
 
 ### iOS
 
 <!-- semconv ios.lifecycle.events -->
-The event name MUST be `app.lifecycle`.
+The event name MUST be `device.app.lifecycle`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
@@ -43,7 +46,7 @@ The event name MUST be `app.lifecycle`.
 ### Android
 
 <!-- semconv android.lifecycle.events -->
-The event name MUST be `app.lifecycle`.
+The event name MUST be `device.app.lifecycle`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|

docs/rpc/rpc-metrics.md

@@ -59,8 +59,7 @@ metrics can be filtered for finer grain analysis.
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 ## Metric instruments
 

docs/rpc/rpc-spans.md

@@ -49,8 +49,7 @@ This document defines how to describe remote procedure calls
 >   * Note: `http/dup` has higher precedence than `http` in case both values are present
 > * SHOULD maintain (security patching at a minimum) the existing major version
 >   for at least six months after it starts emitting both sets of conventions.
-> * SHOULD drop the environment variable in the next major version (stable
->   next major version SHOULD NOT be released prior to October 1, 2023).
+> * SHOULD drop the environment variable in the next major version.
 
 ## Common remote procedure call conventions