From b5495700f10eece442571329ef30b444c4895b8c Mon Sep 17 00:00:00 2001 From: Dan Jaglowski Date: Thu, 14 Oct 2021 14:38:22 -0400 Subject: [PATCH] Add semantic conventions for log media attributes Logs are transmitted via several common media, such as files and iostreams. This PR establishes semantic conventions for describing the file or iostream from which a log was read. Notably, these attributes are not resource attributes, as the medium used to tranmit a log is not considered to be the originator of the log. --- CHANGELOG.md | 2 + specification/logs/data-model.md | 4 +- .../logs/semantic_conventions/README.md | 11 +++++ .../logs/semantic_conventions/media.md | 40 +++++++++++++++++++ 4 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 specification/logs/semantic_conventions/README.md create mode 100644 specification/logs/semantic_conventions/media.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1476ffe6a44..a3f9a509412 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ release. - Fix Syslog severity number mapping in the example. ([#2091](https://github.com/open-telemetry/opentelemetry-specification/pull/2091)) +- Add log.* attributes. + ([#2022](https://github.com/open-telemetry/opentelemetry-specification/pull/2022)) ### Resource diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index cfde3cb306a..3dab3de1996 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -426,8 +426,8 @@ Description: Additional information about the specific event occurrence. Unlike the `Resource` field, which is fixed for a particular source, `Attributes` can vary for each occurrence of the event coming from the same source. Can contain information about the request context (other than TraceId/SpanId). SHOULD follow -OpenTelemetry -[semantic conventions for Attributes](../trace/semantic_conventions/README.md). +OpenTelemetry [semantic conventions for Log Attributes](./semantic_conventions/README.md) or +[semantic conventions for Span Attributes](../trace/semantic_conventions/README.md). This field is optional. #### Errors and Exceptions diff --git a/specification/logs/semantic_conventions/README.md b/specification/logs/semantic_conventions/README.md new file mode 100644 index 00000000000..a4c866cc19b --- /dev/null +++ b/specification/logs/semantic_conventions/README.md @@ -0,0 +1,11 @@ +# Log Attribute Semantic Conventions + +**Status**: [Experimental](../../document-status.md) + +The following semantic conventions for logs are defined: + +* [Log Media](media.md): Semantic attributes that may be used in describing the source of a log. + +Apart from semantic conventions for logs, [traces](../../trace/semantic_conventions/README.md), and [metrics](../../metrics/semantic_conventions/README.md), +OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own +[Resource Semantic Conventions](../../resource/semantic_conventions/README.md). diff --git a/specification/logs/semantic_conventions/media.md b/specification/logs/semantic_conventions/media.md new file mode 100644 index 00000000000..67b700d7eba --- /dev/null +++ b/specification/logs/semantic_conventions/media.md @@ -0,0 +1,40 @@ +# Semantic Conventions for Log Media + +**Status**: [Experimental](../../document-status.md) + +This document describes attributes for log media in OpenTelemetry. Log media are mechanisms by which logs are transmitted. Types of media include files, streams, network protocols, and os-specific logging services such as journald and Windows Event Log. + + + + + +- [Log Media](#log-media) + * [Log File](#log-file) + * [I/O Stream](#io-stream) + + + +## Log Media + +**Note:** The OpenTelemetry specification defines a [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md#resource-sdk) as `an immutable representation of the entity producing telemetry`. +The following attributes do not describe entities that produce telemetry. Rather, they describe mechanisms of log transmission. +As such, these should be recorded as Log Record attributes when applicable. They should not be recorded as Resource attributes. + +### Log File + +**Description:** A file to which log was emitted. + +| Name | Notes and examples | +| ------------------------------- | ---------------------------------------------------------------------------------------- | +| `log.file.name` | The basename of the file. Example: `audit.log` | +| `log.file.path` | The full path to the file. Example: `/var/log/mysql/audit.log` | +| `log.file.name_resolved` | The basename of the file, with symlinks resolved. Example: `uuid.log` | +| `log.file.path_resolved` | The full path to the file, with symlinks resolved. Example: `/var/lib/docker/uuid.log` | + +### I/O Stream + +**Description:** The I/O stream to which the log was emitted. + +| Name | Notes and examples | +| ------------------------------- | ---------------------------------------------------------------------------------------- | +| `log.iostream` | The stream associated with the log. SHOULD be one of: `stdout`, `stderr` |