Migrate exception attributes to registry (#574)
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
This commit is contained in:
Josh Suereth
GitHub
parent
176db0d281
commit
165dae5c29
|
|
@ -9,6 +9,8 @@ release.
|
|||
|
||||
- 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,33 +0,0 @@
|
|||
groups:
|
||||
- id: exception
|
||||
type: span
|
||||
prefix: exception
|
||||
brief: >
|
||||
This document defines the shared attributes used to
|
||||
report a single exception associated with a span or log.
|
||||
attributes:
|
||||
- id: type
|
||||
type: string
|
||||
brief: >
|
||||
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.
|
||||
examples: ["java.net.ConnectException", "OSError"]
|
||||
- id: message
|
||||
type: string
|
||||
brief: The exception message.
|
||||
examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
|
||||
- id: stacktrace
|
||||
type: string
|
||||
brief: >
|
||||
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.
|
||||
examples: '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)'
|
||||
|
||||
constraints:
|
||||
- any_of:
|
||||
- "exception.type"
|
||||
- "exception.message"
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
groups:
|
||||
- id: registry.exception
|
||||
type: attribute_group
|
||||
prefix: exception
|
||||
brief: >
|
||||
This document defines the shared attributes used to
|
||||
report a single exception associated with a span or log.
|
||||
attributes:
|
||||
- id: type
|
||||
type: string
|
||||
brief: >
|
||||
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.
|
||||
examples: ["java.net.ConnectException", "OSError"]
|
||||
- id: message
|
||||
type: string
|
||||
brief: The exception message.
|
||||
examples: ["Division by zero", "Can't convert 'int' object to str implicitly"]
|
||||
- id: stacktrace
|
||||
type: string
|
||||
brief: >
|
||||
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.
|
||||
examples: '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)'
|
||||
- id: escaped
|
||||
type: boolean
|
||||
brief: >
|
||||
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.
|
||||
note: |-
|
||||
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.
|
||||
|
|
@ -9,29 +9,7 @@ groups:
|
|||
- ref: exception.type
|
||||
- ref: exception.message
|
||||
- ref: exception.stacktrace
|
||||
- id: escaped
|
||||
type: boolean
|
||||
brief: >
|
||||
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.
|
||||
note: |-
|
||||
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 above](#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.
|
||||
|
||||
- ref: exception.escaped
|
||||
constraints:
|
||||
- any_of:
|
||||
- "exception.type"
|
||||
|
|
|
|||
Loading…
Reference in New Issue