[Logs] Add semantic conventions for writing exceptions (open-telemetr…

…y#2819)
carlosalberto · Sep 30, 2022 · b2c2432 · b2c2432
1 parent 475b3dd
commit b2c2432
Show file tree

Hide file tree

Showing 7 changed files with 107 additions and 25 deletions.
diff --git 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
@@ -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
@@ -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 → ...ic_conventions/trace/trace-exception.yaml b/semantic_conventions/trace/exception.yaml → ...ic_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
@@ -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
@@ -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).
+
+<!-- toc -->
+
+- [Recording an Exception](#recording-an-exception)
+- [Attributes](#attributes)
+  * [Stacktrace Representation](#stacktrace-representation)
+
+<!-- tocstop -->
+
+## 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.
+
+<!-- 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 |
+
+**Additional attribute requirements:** At least one of the following sets of attributes is required:
+
+* `exception.type`
+* `exception.message`
+<!-- endsemconv -->
+
+### 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
@@ -39,15 +39,15 @@ try {
 The table below indicates which attributes should be added to the `Event` and
 their types.
 
-<!-- semconv exception -->
+<!-- semconv trace-exception -->
 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".