diff --git a/CHANGELOG.md b/CHANGELOG.md index f842d326bed..ffa5f21d36d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,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 diff --git a/semantic_conventions/exception.yaml b/semantic_conventions/exception.yaml new file mode 100644 index 00000000000..959aba51f8a --- /dev/null +++ b/semantic_conventions/exception.yaml @@ -0,0 +1,32 @@ +groups: + - id: exception + 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" 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/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/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 diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md new file mode 100644 index 00000000000..06a382f8eb0 --- /dev/null +++ b/specification/logs/semantic_conventions/exceptions.md @@ -0,0 +1,50 @@ +# Semantic Conventions for Exceptions + +**Status**: [Experimental](../../document-status.md) + +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). + + + +- [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. + + +| 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 | + +**Additional attribute requirements:** At least one of the following sets of attributes is required: + +* `exception.type` +* `exception.message` + + +### Stacktrace Representation + +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".