Merge branch 'main' into mx-psi/ecs-conventions

CHANGELOG.md

@@ -7,6 +7,11 @@ release.
 
 ## Unreleased
 
+- Replace AWS X-Ray Environment Span Link section with AWS X-Ray Active Tracing Considerations
+  ([#354](https://github.com/open-telemetry/semantic-conventions/pull/354))
+- Move Exceptions to attribute registry
+  ([#574](https://github.com/open-telemetry/semantic-conventions/pull/574))
+
 ### Breaking
 
 - Update `jvm.gc.duration` histogram buckets to `[ 0.01, 0.1, 1, 10 ]`
@@ -28,6 +33,8 @@ release.
 
 - Adds `labels` attribute to `k8s.pod` resource
   ([#494](https://github.com/open-telemetry/semantic-conventions/pull/494))
+- Adds `annotation` attribute to `k8s.pod` resource
+  ([#494](https://github.com/open-telemetry/semantic-conventions/pull/573))
 - Add `code.stacktrace` attribute
   ([#435](https://github.com/open-telemetry/semantic-conventions/pull/435))
 - Add `http.flavor` and `http.user_agent` to list of deprecated attributes

docs/attributes-registry/README.md

@@ -36,6 +36,7 @@ Currently, the following namespaces exist:
 * [Device](device.md)
 * [Disk](disk.md)
 * [Error](error.md)
+* [Exception](exception.md)
 * [Host](host.md)
 * [HTTP](http.md)
 * [K8s](k8s.md)

docs/attributes-registry/exception.md

@@ -0,0 +1,37 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Exceptions
+
+## Exception Attributes
+
+<!-- semconv registry.exception(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  |
+| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` |
+| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
+| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |
+
+**[1]:** An exception is considered to have escaped (or left) the scope of a span,
+if that span is ended while the exception is still logically "in flight".
+This may be actually "in flight" in some languages (e.g. if the exception
+is passed to a Context manager's `__exit__` method in Python) but will
+usually be caught at the point of recording the exception in most languages.
+
+It is usually not possible to determine at the point where an exception is thrown
+whether it will escape the scope of a span.
+However, it is trivial to know that an exception
+will escape, if one checks for an active exception just before ending the span,
+as done in the [example for recording span exceptions](#recording-an-exception).
+
+It follows that an exception may still escape the scope of the span
+even if the `exception.escaped` attribute was not set or set to false,
+since the event might have been recorded at a time where it was not
+clear whether the exception will escape.
+<!-- endsemconv -->
+
+### Recording An Exception
+
+The `exception.escaped` attribute has special semantics in the context of
+a span. Please read the [details here](../exceptions/exceptions-spans.md#recording-an-exception).

docs/attributes-registry/k8s.md

@@ -2,31 +2,32 @@
 
 ## Kubernetes Resource Attributes
 
-<!-- semconv registry.k8s -->
-| Attribute  | Type | Description  | Examples  | Requirement Level |
-|---|---|---|---|---|
-| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended |
-| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended |
-| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | Recommended |
-| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` | Recommended |
-| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | Recommended |
-| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` | Recommended |
-| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` | Recommended |
-| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.job.name` | string | The name of the Job. | `opentelemetry` | Recommended |
-| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` | Recommended |
-| `k8s.node.name` | string | The name of the Node. | `node-1` | Recommended |
-| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | Recommended |
-| `k8s.pod.labels.<key>` | string | The labels placed on the Pod, the `<key>` being the label name, the value being the label value. | `k8s.pod.labels.app=my-app`; `k8s.pod.labels.mycompany.io/arch=x64`; `k8s.pod.labels.data=` | Recommended |
-| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` | Recommended |
-| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` | Recommended |
-| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
-| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` | Recommended |
-| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | Recommended |
+<!-- semconv registry.k8s(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` |
+| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` |
+| `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` |
+| `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | `0`; `2` |
+| `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` |
+| `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.daemonset.name` | string | The name of the DaemonSet. | `opentelemetry` |
+| `k8s.daemonset.uid` | string | The UID of the DaemonSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.deployment.name` | string | The name of the Deployment. | `opentelemetry` |
+| `k8s.deployment.uid` | string | The UID of the Deployment. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.job.name` | string | The name of the Job. | `opentelemetry` |
+| `k8s.job.uid` | string | The UID of the Job. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.namespace.name` | string | The name of the namespace that the pod is running in. | `default` |
+| `k8s.node.name` | string | The name of the Node. | `node-1` |
+| `k8s.node.uid` | string | The UID of the Node. | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` |
+| `k8s.pod.annotation.<key>` | string | The annotation key-value pairs placed on the Pod, the `<key>` being the annotation name, the value being the annotation value. | `k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets=true`; `k8s.pod.annotation.mycompany.io/arch=x64`; `k8s.pod.annotation.data=` |
+| `k8s.pod.labels.<key>` | string | The labels placed on the Pod, the `<key>` being the label name, the value being the label value. | `k8s.pod.labels.app=my-app`; `k8s.pod.labels.mycompany.io/arch=x64`; `k8s.pod.labels.data=` |
+| `k8s.pod.name` | string | The name of the Pod. | `opentelemetry-pod-autoconf` |
+| `k8s.pod.uid` | string | The UID of the Pod. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.replicaset.name` | string | The name of the ReplicaSet. | `opentelemetry` |
+| `k8s.replicaset.uid` | string | The UID of the ReplicaSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
+| `k8s.statefulset.name` | string | The name of the StatefulSet. | `opentelemetry` |
+| `k8s.statefulset.uid` | string | The UID of the StatefulSet. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` |
 
 **[1]:** K8s doesn't have support for obtaining a cluster ID. If this is ever
 added, we will recommend collecting the `k8s.cluster.uid` through the

docs/exceptions/exceptions-logs.md

@@ -38,14 +38,14 @@ The table below indicates which attributes should be added to the
 <!-- semconv log-exception -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
-| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
-| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
+| [`exception.stacktrace`](../attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
+| [`exception.type`](../attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
-* `exception.type`
-* `exception.message`
+* [`exception.type`](../attributes-registry/exception.md)
+* [`exception.message`](../attributes-registry/exception.md)
 <!-- endsemconv -->
 
 ### Stacktrace Representation

docs/exceptions/exceptions-spans.md

@@ -48,10 +48,10 @@ The event name MUST be `exception`.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `exception.escaped` | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  | Recommended |
-| `exception.message` | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
-| `exception.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
-| `exception.type` | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
+| [`exception.escaped`](../attributes-registry/exception.md) | boolean | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. [1] |  | Recommended |
+| [`exception.message`](../attributes-registry/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below |
+| [`exception.stacktrace`](../attributes-registry/exception.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Recommended |
+| [`exception.type`](../attributes-registry/exception.md) | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` | See below |
 
 **[1]:** An exception is considered to have escaped (or left) the scope of a span,
 if that span is ended while the exception is still logically "in flight".
@@ -63,7 +63,7 @@ It is usually not possible to determine at the point where an exception is throw
 whether it will escape the scope of a span.
 However, it is trivial to know that an exception
 will escape, if one checks for an active exception just before ending the span,
-as done in the [example above](#recording-an-exception).
+as done in the [example for recording span exceptions](#recording-an-exception).
 
 It follows that an exception may still escape the scope of the span
 even if the `exception.escaped` attribute was not set or set to false,
@@ -72,8 +72,8 @@ clear whether the exception will escape.
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
-* `exception.type`
-* `exception.message`
+* [`exception.type`](../attributes-registry/exception.md)
+* [`exception.message`](../attributes-registry/exception.md)
 <!-- endsemconv -->
 
 ### Stacktrace Representation