From 9611d45b5f58b1e0fc0ea598ac6b186d6fc7aa86 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 21 Sep 2022 13:43:44 -0700 Subject: [PATCH 1/9] Add log semantic conventions for writing exceptions. --- semantic_conventions/trace/exception.yaml | 3 ++ .../logs/semantic_conventions/exceptions.md | 51 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 specification/logs/semantic_conventions/exceptions.md diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/exception.yaml index 61f0296e415..955492f1515 100644 --- a/semantic_conventions/trace/exception.yaml +++ b/semantic_conventions/trace/exception.yaml @@ -13,10 +13,12 @@ groups: The dynamic type of the exception should be preferred over the static type in languages that support it. examples: ["java.net.ConnectException", "OSError"] + tag: logs-and-traces - id: message type: string brief: The exception message. examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] + tag: logs-and-traces - id: stacktrace type: string brief: > @@ -26,6 +28,7 @@ groups: 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)' + tag: logs-and-traces - id: escaped type: boolean brief: > diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md new file mode 100644 index 00000000000..56d1ee1b70b --- /dev/null +++ b/specification/logs/semantic_conventions/exceptions.md @@ -0,0 +1,51 @@ +# Semantic Conventions for Exceptions + +**Status**: [Experimental](../../document-status.md) + +This document defines semantic conventions for recording application +exceptions. + + + +- [Recording an Exception](#recording-an-exception) +- [Attributes](#attributes) + * [Stacktrace Representation](#stacktrace-representation) + + + +## Recording an Exception + +Exceptions SHOULD be recorded as attributes on the +[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit +operations. Exceptions MAY be recorded on "logs" or "events" depending on the +context. + +To encapsulate proper handling of exceptions API authors MAY provide a +constructor, `RecordException` method/extension, or similar helper mechanism on +the `LogRecord` class/structure or wherever it makes the most sense depending on +the language runtime. + +## Attributes + +The table below indicates which attributes should be added to the +[LogRecord](../api.md#logrecord) and their types. + + +The event name MUST be `exception`. + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| [`exception.type`](../../trace/semantic_conventions/exceptions.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 | +| [`exception.message`](../../trace/semantic_conventions/exceptions.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | +| [`exception.stacktrace`](../../trace/semantic_conventions/exceptions.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 | + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* [`exception.type`](../../trace/semantic_conventions/exceptions.md) +* [`exception.message`](../../trace/semantic_conventions/exceptions.md) + + +### Stacktrace Representation + +See [Trace Semantic Conventions for Exceptions - Stacktrace +Representation](../../trace/semantic_conventions/exceptions.md#stacktrace-representation). From fe65c87ee48154d285f7c4fb04f5c460a0d3abff Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 21 Sep 2022 14:21:00 -0700 Subject: [PATCH 2/9] CHANGELOG update. --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a0fdd95c22..24d4683c4bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,8 @@ release. - Add `process.context_switches`, and `process.open_file_descriptors`, to the metrics semantic conventions ([#2706](https://github.com/open-telemetry/opentelemetry-specification/pull/2706)) +- Add exceptions to the logs semantic conventions + ([#2819](https://github.com/open-telemetry/opentelemetry-specification/pull/2819)) ### Compatibility From 8933a4133d8f28578d76be746dc145a954d95b6b Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 21 Sep 2022 15:04:00 -0700 Subject: [PATCH 3/9] Review. --- specification/logs/semantic_conventions/exceptions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index 56d1ee1b70b..bfb08149ab9 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -2,8 +2,7 @@ **Status**: [Experimental](../../document-status.md) -This document defines semantic conventions for recording application -exceptions. +This document defines semantic conventions for recording exceptions. From 347138e1950c27ca28575e242a4cdfa47a9de49f Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 21 Sep 2022 19:36:55 -0700 Subject: [PATCH 4/9] Tweak. --- specification/logs/semantic_conventions/exceptions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index bfb08149ab9..122cb90443d 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -2,7 +2,8 @@ **Status**: [Experimental](../../document-status.md) -This document defines semantic conventions for recording exceptions. +This document defines semantic conventions for recording exceptions on "logs" +and "events" emitted through the [Logger API](../api.md#logger). From 8884de6ca6bb30beea65a8c16e3eb9d3c1022f06 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 22 Sep 2022 11:55:49 -0700 Subject: [PATCH 5/9] Tweaks. --- semantic_conventions/logs/log-exception.yaml | 15 +++++++++++++++ semantic_conventions/trace/exception.yaml | 3 --- .../logs/semantic_conventions/exceptions.md | 6 ++---- 3 files changed, 17 insertions(+), 7 deletions(-) create mode 100644 semantic_conventions/logs/log-exception.yaml diff --git a/semantic_conventions/logs/log-exception.yaml b/semantic_conventions/logs/log-exception.yaml new file mode 100644 index 00000000000..285701d59cc --- /dev/null +++ b/semantic_conventions/logs/log-exception.yaml @@ -0,0 +1,15 @@ +groups: + - id: log-exception + prefix: exception + brief: > + This document defines attributes for exceptions represented using Log + Records. + attributes: + - ref: exception.type + - ref: exception.message + - ref: exception.stacktrace + + constraints: + - any_of: + - "exception.type" + - "exception.message" diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/exception.yaml index 955492f1515..61f0296e415 100644 --- a/semantic_conventions/trace/exception.yaml +++ b/semantic_conventions/trace/exception.yaml @@ -13,12 +13,10 @@ groups: The dynamic type of the exception should be preferred over the static type in languages that support it. examples: ["java.net.ConnectException", "OSError"] - tag: logs-and-traces - id: message type: string brief: The exception message. examples: ["Division by zero", "Can't convert 'int' object to str implicitly"] - tag: logs-and-traces - id: stacktrace type: string brief: > @@ -28,7 +26,6 @@ groups: 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)' - tag: logs-and-traces - id: escaped type: boolean brief: > diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index 122cb90443d..18caefc45fc 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -30,14 +30,12 @@ the language runtime. The table below indicates which attributes should be added to the [LogRecord](../api.md#logrecord) and their types. - -The event name MUST be `exception`. - + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`exception.type`](../../trace/semantic_conventions/exceptions.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 | | [`exception.message`](../../trace/semantic_conventions/exceptions.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | | [`exception.stacktrace`](../../trace/semantic_conventions/exceptions.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`](../../trace/semantic_conventions/exceptions.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: From 72dc04ba85127c771783d28742e2ffb67030233a Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 22 Sep 2022 14:23:44 -0700 Subject: [PATCH 6/9] Review. --- specification/logs/semantic_conventions/exceptions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index 18caefc45fc..c3ebd800eaf 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -2,8 +2,9 @@ **Status**: [Experimental](../../document-status.md) -This document defines semantic conventions for recording exceptions on "logs" -and "events" emitted through the [Logger API](../api.md#logger). +This document defines semantic conventions for recording exceptions on +[logs](../api.md#emit-logrecord) and [events](../api.md#emit-event) emitted +through the [Logger API](../api.md#logger). From a6f6a8995be6927a1f8cfee24b3eaadeadbf53f9 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Thu, 22 Sep 2022 14:42:29 -0700 Subject: [PATCH 7/9] Updates. --- specification/logs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 292eb7ced8e..1b20c0c77ac 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -470,7 +470,7 @@ Additional information about errors and/or exceptions that are associated with a log record MAY be included in the structured data in the `Attributes` section of the record. If included, they MUST follow the OpenTelemetry -[semantic conventions for exception-related attributes](../trace/semantic_conventions/exceptions.md#attributes). +[semantic conventions for exception-related attributes](./semantic_conventions/exceptions.md#attributes). ## Example Log Records From b05d2a11fa66015f9203b00f2dfdda9a813d9499 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 26 Sep 2022 16:14:28 -0700 Subject: [PATCH 8/9] Review. --- semantic_conventions/exception.yaml | 33 +++++++++++++++++++ .../{exception.yaml => trace-exception.yaml} | 25 +++----------- .../logs/semantic_conventions/exceptions.md | 12 +++---- .../trace/semantic_conventions/exceptions.md | 6 ++-- 4 files changed, 46 insertions(+), 30 deletions(-) create mode 100644 semantic_conventions/exception.yaml rename semantic_conventions/trace/{exception.yaml => trace-exception.yaml} (60%) diff --git a/semantic_conventions/exception.yaml b/semantic_conventions/exception.yaml new file mode 100644 index 00000000000..992d879e0c5 --- /dev/null +++ b/semantic_conventions/exception.yaml @@ -0,0 +1,33 @@ +groups: + - id: exception + prefix: exception + type: event + 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" diff --git a/semantic_conventions/trace/exception.yaml b/semantic_conventions/trace/trace-exception.yaml similarity index 60% rename from semantic_conventions/trace/exception.yaml rename to semantic_conventions/trace/trace-exception.yaml index 61f0296e415..a11082ebd95 100644 --- a/semantic_conventions/trace/exception.yaml +++ b/semantic_conventions/trace/trace-exception.yaml @@ -1,31 +1,14 @@ groups: - - id: exception + - id: trace-exception prefix: exception type: event brief: > This document defines the attributes used to report a single exception associated with a span. 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)' + - ref: exception.type + - ref: exception.message + - ref: exception.stacktrace - id: escaped type: boolean brief: > diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index c3ebd800eaf..06a382f8eb0 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -34,17 +34,17 @@ The table below indicates which attributes should be added to the | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`exception.message`](../../trace/semantic_conventions/exceptions.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | -| [`exception.stacktrace`](../../trace/semantic_conventions/exceptions.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`](../../trace/semantic_conventions/exceptions.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 | +| `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 | **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`exception.type`](../../trace/semantic_conventions/exceptions.md) -* [`exception.message`](../../trace/semantic_conventions/exceptions.md) +* `exception.type` +* `exception.message` ### Stacktrace Representation -See [Trace Semantic Conventions for Exceptions - Stacktrace +Same as [Trace Semantic Conventions for Exceptions - Stacktrace Representation](../../trace/semantic_conventions/exceptions.md#stacktrace-representation). diff --git a/specification/trace/semantic_conventions/exceptions.md b/specification/trace/semantic_conventions/exceptions.md index 25960ad2c5d..52fd108c60b 100644 --- a/specification/trace/semantic_conventions/exceptions.md +++ b/specification/trace/semantic_conventions/exceptions.md @@ -39,15 +39,15 @@ try { The table below indicates which attributes should be added to the `Event` and their types. - + The event name MUST be `exception`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `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` | 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.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.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 | **[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". From fd7c34c34b4b5d221cb67c7aa04f65aa6840772f Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 26 Sep 2022 16:19:09 -0700 Subject: [PATCH 9/9] Cleanup. --- semantic_conventions/exception.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/semantic_conventions/exception.yaml b/semantic_conventions/exception.yaml index 992d879e0c5..959aba51f8a 100644 --- a/semantic_conventions/exception.yaml +++ b/semantic_conventions/exception.yaml @@ -1,7 +1,6 @@ groups: - id: exception prefix: exception - type: event brief: > This document defines the shared attributes used to report a single exception associated with a span or log.