diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index bb5ede00e1..c78207d5fe 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -48,6 +48,7 @@ body: - area:http - area:ios - area:k8s + - area:log - area:messaging - area:network - area:oci diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 53520602e3..355217d372 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -41,6 +41,7 @@ body: - area:http - area:ios - area:k8s + - area:log - area:messaging - area:network - area:oci diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 0e79351f21..c4dd0faedb 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -50,6 +50,7 @@ body: - area:http - area:ios - area:k8s + - area:log - area:messaging - area:network - area:oci diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 4669206415..a0f1684213 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -55,6 +55,7 @@ Currently, the following namespaces exist: * [HTTP](http.md) * [iOS](ios.md) * [K8s](k8s.md) +* [Log](log.md) * [Network](network.md) * [OCI](oci.md) * [OpenTelemetry](otel.md) diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md new file mode 100644 index 0000000000..89c5145c1b --- /dev/null +++ b/docs/attributes-registry/log.md @@ -0,0 +1,52 @@ + + +# Log + + + +- [Log Attributes](#log-attributes) + - [Generic log attributes](#generic-log-attributes) + - [File log attributes](#file-log-attributes) + - [Record log attributes](#record-log-attributes) + + + +## Log Attributes + +### Generic log attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`log.iostream` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `stdout` | Logs from stdout stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `stderr` | Events from stderr stream | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### File log attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `log.file.name` | string | The basename of the file. | `audit.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +### Record log attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[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. + \ No newline at end of file diff --git a/docs/general/logs.md b/docs/general/logs.md index 748c2e61fc..cd443a3b2d 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -38,7 +38,7 @@ These attributes may be used for identifying a Log Record. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `log.record.uid` | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.record.uid`](../attributes-registry/log.md) | string | A unique identifier for the Log Record. [1] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[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. @@ -59,22 +59,22 @@ As such, these should be recorded as Log Record attributes when applicable. They | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `log.file.name` | string | The basename of the file. | `audit.log` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.file.name_resolved` | string | The basename of the file, with symlinks resolved. | `uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.file.path` | string | The full path to the file. | `/var/log/mysql/audit.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.file.path_resolved` | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.name`](../attributes-registry/log.md) | string | The basename of the file. | `audit.log` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.name_resolved`](../attributes-registry/log.md) | string | The basename of the file, with symlinks resolved. | `uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.path`](../attributes-registry/log.md) | string | The full path to the file. | `/var/log/mysql/audit.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.file.path_resolved`](../attributes-registry/log.md) | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | ### I/O Stream **Description:** The I/O stream to which the log was emitted. - + | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| `log.iostream` | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.iostream`](../attributes-registry/log.md) | string | The stream associated with the log. See below for a list of well-known values. | `stdout` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -`log.iostream` MUST be one of the following: +`log.iostream` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | |---|---|---| diff --git a/model/logs/general.yaml b/model/logs/general.yaml index e8f9ea5853..b4afe2c16c 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -1,20 +1,8 @@ groups: - id: log.record - prefix: log.record type: attribute_group 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 - stability: experimental + - ref: log.record.uid 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/model/logs/media.yaml b/model/logs/media.yaml index b6bfea89d4..34c7631d5c 100644 --- a/model/logs/media.yaml +++ b/model/logs/media.yaml @@ -1,56 +1,21 @@ groups: - id: attributes.log - prefix: log type: attribute_group brief: "Describes Log attributes" attributes: - - id: iostream + - ref: log.iostream requirement_level: opt_in - stability: experimental - brief: > - The stream associated with the log. See below for a list of well-known values. - type: - allow_custom_values: false - members: - - id: stdout - value: 'stdout' - brief: 'Logs from stdout stream' - stability: experimental - - id: stderr - value: 'stderr' - brief: 'Events from stderr stream' - stability: experimental + - id: attributes.log.file - prefix: log.file type: attribute_group brief: > A file to which log was emitted. attributes: - - id: name - type: string - stability: experimental + - ref: log.file.name requirement_level: recommended - brief: > - The basename of the file. - examples: ["audit.log"] - - id: path - type: string - stability: experimental + - ref: log.file.path requirement_level: opt_in - brief: > - The full path to the file. - examples: [ "/var/log/mysql/audit.log" ] - - id: name_resolved - type: string - stability: experimental + - ref: log.file.name_resolved requirement_level: opt_in - brief: > - The basename of the file, with symlinks resolved. - examples: [ "uuid.log" ] - - id: path_resolved - type: string - stability: experimental + - ref: log.file.path_resolved requirement_level: opt_in - brief: > - The full path to the file, with symlinks resolved. - examples: [ "/var/lib/docker/uuid.log" ] diff --git a/model/registry/log.yaml b/model/registry/log.yaml new file mode 100644 index 0000000000..b26870a696 --- /dev/null +++ b/model/registry/log.yaml @@ -0,0 +1,72 @@ +groups: + - id: registry.log + type: attribute_group + prefix: log + brief: > + This document defines log attributes + attributes: + - id: iostream + stability: experimental + brief: > + The stream associated with the log. See below for a list of well-known values. + type: + allow_custom_values: true + members: + - id: stdout + value: 'stdout' + brief: 'Logs from stdout stream' + stability: experimental + - id: stderr + value: 'stderr' + brief: 'Events from stderr stream' + stability: experimental + + - id: registry.log.file # TODO: should we move it to the file model? + type: attribute_group + prefix: log.file + brief: > + Attributes for a file to which log was emitted. + attributes: + - id: name + type: string + stability: experimental + brief: > + The basename of the file. + examples: [ "audit.log" ] + - id: path + type: string + stability: experimental + brief: > + The full path to the file. + examples: [ "/var/log/mysql/audit.log" ] + - id: name_resolved + type: string + stability: experimental + brief: > + The basename of the file, with symlinks resolved. + examples: [ "uuid.log" ] + - id: path_resolved + type: string + stability: experimental + brief: > + The full path to the file, with symlinks resolved. + examples: [ "/var/lib/docker/uuid.log" ] + + - id: registry.log.record + type: attribute_group + prefix: log.record + brief: > + This document defines the generic attributes that may be used in any Log Record. + attributes: + - id: uid + type: string + stability: experimental + 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"]