66 lines
3.8 KiB
Markdown
66 lines
3.8 KiB
Markdown
<!--- Hugo front matter used to generate the website version of this page:
|
|
linkTitle: Logs
|
|
--->
|
|
|
|
# Semantic conventions for exceptions in logs
|
|
|
|
**Status**: [Stable][DocumentStatus]
|
|
|
|
This document defines semantic conventions for recording exceptions on
|
|
[logs](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.45.0/specification/logs/api.md#emit-a-logrecord)
|
|
emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.45.0/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.45.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.45.0/specification/logs/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](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.45.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.
|
|
|
|
<!-- semconv log-exception -->
|
|
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/snippet.md.j2 -->
|
|
<!-- prettier-ignore-start -->
|
|
<!-- markdownlint-capture -->
|
|
<!-- markdownlint-disable -->
|
|
|
|
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|
|
|---|---|---|---|---|---|
|
|
| [`exception.message`](/docs/registry/attributes/exception.md) | string | The exception message. | `Division by zero`; `Can't convert 'int' object to str implicitly` | `Conditionally Required` [1] |  |
|
|
| [`exception.type`](/docs/registry/attributes/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` | `Conditionally Required` [2] |  |
|
|
| [`exception.stacktrace`](/docs/registry/attributes/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` |  |
|
|
|
|
**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
|
|
|
|
**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
|
|
|
|
<!-- markdownlint-restore -->
|
|
<!-- prettier-ignore-end -->
|
|
<!-- END AUTOGENERATED TEXT -->
|
|
<!-- endsemconv -->
|
|
|
|
### Stacktrace representation
|
|
|
|
Same as [Trace Semantic Conventions for Exceptions - Stacktrace
|
|
Representation](exceptions-spans.md#stacktrace-representation).
|
|
|
|
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|