From 0902d5f42988f11ad6903c307992034857908f61 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Thu, 6 Apr 2023 19:14:26 +0200 Subject: [PATCH] Add semantic conventions for log record ID (#3047) Fixes #597 ## Changes - Add a section for "generic attributes" to the log semconv - Add an attribute `log_record.id` making use of ULID as discussed in #597 Some additional notes: - I kept the PR small, so I left out some other potential attributes, e.g. something for pre-existing ID (like windows event logs) or for storing the used logging/eventing system or even something like a "signature" that might be worth discussing, etc. - I followed the structure of "generic attributes" from the spans semconv - I took some of the existing wording from #597 & https://github.com/open-telemetry/oteps/pull/97#discussion_r421865344 to describe the field --------- Signed-off-by: svrnm Co-authored-by: Joao Grassi Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> --- semantic_conventions/logs/general.yaml | 18 +++++++++++++ .../logs/semantic_conventions/README.md | 1 + .../logs/semantic_conventions/general.md | 27 +++++++++++++++++++ 3 files changed, 46 insertions(+) create mode 100644 semantic_conventions/logs/general.yaml create mode 100644 specification/logs/semantic_conventions/general.md diff --git a/semantic_conventions/logs/general.yaml b/semantic_conventions/logs/general.yaml new file mode 100644 index 000000000..fc4af3567 --- /dev/null +++ b/semantic_conventions/logs/general.yaml @@ -0,0 +1,18 @@ +groups: + - id: log.record + prefix: log.record + brief: > + The attributes described in this section are rather generic. They may be used in any Log Record they apply to. + attributes: + - id: uid + type: string + requirement_level: opt_in + brief: > + A unique identifier for the Log Record. + note: > + If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. + This means, that two distinguishable log records MUST have different values. + + The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), + but other identifiers (e.g. UUID) may be used as needed. + examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"] diff --git a/specification/logs/semantic_conventions/README.md b/specification/logs/semantic_conventions/README.md index 931e1a7af..4df36b933 100644 --- a/specification/logs/semantic_conventions/README.md +++ b/specification/logs/semantic_conventions/README.md @@ -4,6 +4,7 @@ The following semantic conventions for logs are defined: +* [General](general.md): General semantic attributes that may be used in describing Log Records. * [Log Media](media.md): Semantic attributes that may be used in describing the source of a log. The following semantic conventions for events are defined: diff --git a/specification/logs/semantic_conventions/general.md b/specification/logs/semantic_conventions/general.md new file mode 100644 index 000000000..80b679a0b --- /dev/null +++ b/specification/logs/semantic_conventions/general.md @@ -0,0 +1,27 @@ +# General attributes + +**Status**: [Experimental](../../document-status.md) + +The attributes described in this section are rather generic. +They may be used in any Log Record they apply to. + + + + + +- [General log identification attributes](#general-log-identification-attributes) + + + +## General log identification attributes + +These attributes may be used for identifying a Log Record. + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | Opt-In | + +**[1]:** If an id is provided, other log records with the same id will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. +The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec), but other identifiers (e.g. UUID) may be used as needed. +