diff --git a/docs/exceptions/exceptions-logs.md b/docs/exceptions/exceptions-logs.md index e50ba4f761..88d585d4c7 100644 --- a/docs/exceptions/exceptions-logs.md +++ b/docs/exceptions/exceptions-logs.md @@ -35,7 +35,7 @@ the language runtime. The table below indicates which attributes should be added to the [LogRecord](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.46.0/specification/logs/data-model.md#log-and-event-record-definition) and their types. - + diff --git a/docs/general/logs.md b/docs/general/logs.md index a2d3827fea..1355d2cb6f 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -33,7 +33,7 @@ OpenTelemetry also defines the concept of overarching [Resources](https://github These attributes may be used for identifying a Log Record. - + diff --git a/docs/registry/namespaces/exception/bundle-exception.md b/docs/registry/namespaces/exception/bundle-exception.md new file mode 100644 index 0000000000..846c7df542 --- /dev/null +++ b/docs/registry/namespaces/exception/bundle-exception.md @@ -0,0 +1,26 @@ + + + + + +# Bundle Exception + +## Exception Attributes + +**Status:** Unknown stability. + +**Summary:** This document defines attributes for exceptions represented using Log Records. + +### Attributes + +| 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] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`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` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise. + +**[2] `exception.type`:** Required if `exception.message` is not set, recommended otherwise. + + diff --git a/docs/registry/namespaces/feature-flag/bundle-feature-flag-evaluation.md b/docs/registry/namespaces/feature-flag/bundle-feature-flag-evaluation.md new file mode 100644 index 0000000000..efb9d9feaf --- /dev/null +++ b/docs/registry/namespaces/feature-flag/bundle-feature-flag-evaluation.md @@ -0,0 +1,87 @@ + + + + + +# Bundle Feature Flag Evaluation + +## Feature Flag Attributes + +**Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) + +**Summary:** Defines attributes to be added to log records on feature flag evaluation. + +### Attributes + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`feature_flag.key`](/docs/registry/attributes/feature-flag.md) | string | The lookup key of the feature flag. | `logo-color` | `Required` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.type`](/docs/registry/attributes/error.md) | string | Describes a class of error the operation ended with. [1] | `provider_not_ready`; `targeting_key_missing`; `provider_fatal`; `general` | `Conditionally Required` [2] | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`feature_flag.result.value`](/docs/registry/attributes/feature-flag.md) | any | The evaluated value of the feature flag. [3] | `#ff0000`; `true`; `3` | `Conditionally Required` [4] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.result.variant`](/docs/registry/attributes/feature-flag.md) | string | A semantic identifier for an evaluated flag value. [5] | `red`; `true`; `on` | `Conditionally Required` [6] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`error.message`](/docs/registry/attributes/error.md) | string | A message providing more detail about an error in human-readable form. [7] | `Unexpected input type: string`; `The user has exceeded their storage quota` | `Recommended` [8] | ![Development](https://img.shields.io/badge/-development-blue) | +| [`feature_flag.context.id`](/docs/registry/attributes/feature-flag.md) | string | The unique identifier for the flag evaluation context. For example, the targeting key. | `5157782b-2203-4c80-a857-dbbd5e7761db` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.provider.name`](/docs/registry/attributes/feature-flag.md) | string | Identifies the feature flag provider. | `Flag Manager` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.result.reason`](/docs/registry/attributes/feature-flag.md) | string | The reason code which shows how a feature flag value was determined. | `static`; `targeting_match`; `error`; `default` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.set.id`](/docs/registry/attributes/feature-flag.md) | string | The identifier of the [flag set](https://openfeature.dev/specification/glossary/#flag-set) to which the feature flag belongs. | `proj-1`; `ab98sgs`; `service1/dev` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| [`feature_flag.version`](/docs/registry/attributes/feature-flag.md) | string | The version of the ruleset used during the evaluation. This may be any stable value which uniquely identifies the ruleset. | `1`; `01ABCDEF` | `Recommended` | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[1] `error.type`:** If one of these values applies, then it MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `flag_not_found` | The flag could not be found. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `invalid_context` | The evaluation context does not meet provider requirements. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `parse_error` | An error was encountered parsing data, such as a flag configuration. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `provider_fatal` | The provider has entered an irrecoverable error state. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `provider_not_ready` | The value was resolved before the provider was initialized. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `targeting_key_missing` | The provider requires a targeting key and one was not provided in the evaluation context. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `type_mismatch` | The type of the flag value does not match the expected type. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `general` | The error was for a reason not enumerated above. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + +**[2] `error.type`:** If and only if an error occurred during flag evaluation. + +**[3] `feature_flag.result.value`:** With some feature flag providers, feature flag results can be quite large or contain private or sensitive details. +Because of this, `feature_flag.result.variant` is often the preferred attribute if it is available. + +It may be desirable to redact or otherwise limit the size and scope of `feature_flag.result.value` if possible. +Because the evaluated flag value is unstructured and may be any type, it is left to the instrumentation author to determine how best to achieve this. + +**[4] `feature_flag.result.value`:** If and only if feature flag provider does not supply variant or equivalent concept. Otherwise, `feature_flag.result.value` should be treated as opt-in. + +**[5] `feature_flag.result.variant`:** A semantic identifier, commonly referred to as a variant, provides a means +for referring to a value without including the value itself. This can +provide additional context for understanding the meaning behind a value. +For example, the variant `red` maybe be used for the value `#c05543`. + +**[6] `feature_flag.result.variant`:** If feature flag provider supplies a variant or equivalent concept. + +**[7] `error.message`:** Should not simply duplicate the value of `error.type`, but should provide more context. For example, if `error.type` is `invalid_context` the `error.message` may enumerate which context keys are missing or invalid. + +**[8] `error.message`:** If and only if an error occurred during flag evaluation and `error.type` does not sufficiently describe the error. + +--- + +`error.type` 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 | +|---|---|---| +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`feature_flag.result.reason` 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 | +|---|---|---| +| `cached` | The resolved value was retrieved from cache. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `default` | The resolved value fell back to a pre-configured value (no dynamic evaluation occurred or dynamic evaluation yielded no result). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `disabled` | The resolved value was the result of the flag being disabled in the management system. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `error` | The resolved value was the result of an error. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `split` | The resolved value was the result of pseudorandom assignment. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `stale` | The resolved value is non-authoritative or possibly out of date | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `static` | The resolved value is static (no dynamic evaluation). | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `targeting_match` | The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | +| `unknown` | The reason for the resolved value could not be determined. | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | + + diff --git a/docs/registry/namespaces/log/bundle-log-file.md b/docs/registry/namespaces/log/bundle-log-file.md new file mode 100644 index 0000000000..50bf62ea5e --- /dev/null +++ b/docs/registry/namespaces/log/bundle-log-file.md @@ -0,0 +1,32 @@ + + + + + +# Bundle Log File + +## Log File Attributes + +**Status:** Unknown stability. + +**Summary:** Attributes for a file to which log was emitted. + +**Description:** The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. + +### Attributes + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.file.name`](/docs/registry/attributes/log.md) | string | The basename of the file. | `audit.log` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.file.name_resolved`](/docs/registry/attributes/log.md) | string | The basename of the file, with symlinks resolved. | `uuid.log` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.file.path`](/docs/registry/attributes/log.md) | string | The full path to the file. | `/var/log/mysql/audit.log` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.file.path_resolved`](/docs/registry/attributes/log.md) | string | The full path to the file, with symlinks resolved. | `/var/lib/docker/uuid.log` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.record.original`](/docs/registry/attributes/log.md) | string | The complete original Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.record.uid`](/docs/registry/attributes/log.md) | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `log.record.original`:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2] `log.record.uid`:** 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. + + diff --git a/docs/registry/namespaces/log/bundle-log-record.md b/docs/registry/namespaces/log/bundle-log-record.md new file mode 100644 index 0000000000..a7e2683f5d --- /dev/null +++ b/docs/registry/namespaces/log/bundle-log-record.md @@ -0,0 +1,28 @@ + + + + + +# Bundle Log Record + +## General Log Record Attributes + +**Status:** Unknown stability. + +**Summary:** This document defines the generic attributes that may be used in any Log Record. + +**Description:** The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. + +### Attributes + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.record.original`](/docs/registry/attributes/log.md) | string | The complete original Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.record.uid`](/docs/registry/attributes/log.md) | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `log.record.original`:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2] `log.record.uid`:** 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. + + diff --git a/docs/registry/namespaces/log/bundle-log-stream.md b/docs/registry/namespaces/log/bundle-log-stream.md new file mode 100644 index 0000000000..1809c9ec7d --- /dev/null +++ b/docs/registry/namespaces/log/bundle-log-stream.md @@ -0,0 +1,38 @@ + + + + + +# Bundle Log Stream + +## Log I/O Stream Attributes + +**Status:** Unknown stability. + +**Summary:** This document defines log attributes + +**Description:** The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. + +### Attributes + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`log.iostream`](/docs/registry/attributes/log.md) | string | The stream associated with the log. See below for a list of well-known values. | `stdout`; `stderr` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.record.original`](/docs/registry/attributes/log.md) | string | The complete original Log Record. [1] | `77 <86>1 2015-08-06T21:58:59.694Z 192.168.2.133 inactive - - - Something happened`; `[INFO] 8/3/24 12:34:56 Something happened` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`log.record.uid`](/docs/registry/attributes/log.md) | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + +**[1] `log.record.original`:** This value MAY be added when processing a Log Record which was originally transmitted as a string or equivalent data type AND the Body field of the Log Record does not contain the same value. (e.g. a syslog or a log record read from a file.) + +**[2] `log.record.uid`:** 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. + +--- + +`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 | +|---|---|---| +| `stderr` | Events from stderr stream | ![Development](https://img.shields.io/badge/-development-blue) | +| `stdout` | Logs from stdout stream | ![Development](https://img.shields.io/badge/-development-blue) | + + diff --git a/model/exceptions/logs.yaml b/model/exceptions/bundles.yaml similarity index 88% rename from model/exceptions/logs.yaml rename to model/exceptions/bundles.yaml index c8b664c0bf..598ab1fede 100644 --- a/model/exceptions/logs.yaml +++ b/model/exceptions/bundles.yaml @@ -1,6 +1,7 @@ groups: - - id: log-exception + - id: bundle.exception type: attribute_group + display_name: Exception Attributes brief: > This document defines attributes for exceptions represented using Log Records. diff --git a/model/feature-flags/bundles.yaml b/model/feature-flags/bundles.yaml new file mode 100644 index 0000000000..67d345ca76 --- /dev/null +++ b/model/feature-flags/bundles.yaml @@ -0,0 +1,8 @@ +groups: + - id: bundle.feature_flag.evaluation + type: attribute_group + display_name: Feature Flag Attributes + stability: release_candidate + extends: event.feature_flag.evaluation + brief: > + Defines attributes to be added to log records on feature flag evaluation. diff --git a/model/log/bundles.yaml b/model/log/bundles.yaml new file mode 100644 index 0000000000..500b5c6789 --- /dev/null +++ b/model/log/bundles.yaml @@ -0,0 +1,33 @@ +groups: + - id: bundle.log.stream + type: attribute_group + display_name: Log I/O Stream Attributes + extends: registry.log + brief: > + This document defines log attributes + note: > + The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. + attributes: + - ref: log.record.original + - ref: log.record.uid + + - id: bundle.log.file # TODO: should we move it to the file model? + type: attribute_group + display_name: Log File Attributes + extends: registry.log.file + brief: > + Attributes for a file to which log was emitted. + note: > + The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. + attributes: + - ref: log.record.original + - ref: log.record.uid + + - id: bundle.log.record + type: attribute_group + display_name: General Log Record Attributes + extends: registry.log.record + brief: > + This document defines the generic attributes that may be used in any Log Record. + note: > + The following attributes do not describe entities that produce telemetry but rather, they describe mechanisms of log transmission. diff --git a/model/log/common.yaml b/model/log/common.yaml index 47b7af71f5..01665e33f2 100644 --- a/model/log/common.yaml +++ b/model/log/common.yaml @@ -1,5 +1,5 @@ groups: - - id: log.record + - id: attributes.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. diff --git a/templates/registry/markdown/bundle_details.md.j2 b/templates/registry/markdown/bundle_details.md.j2 new file mode 100644 index 0000000000..ff6fc082c8 --- /dev/null +++ b/templates/registry/markdown/bundle_details.md.j2 @@ -0,0 +1,50 @@ +{#- This template is rendered per top-level registry namespace. -#} +{#- It consists of two variables: -#} +{#- - id: The top-level namespace id. -#} +{#- - groups: A sequence of all attribute groups under this namespace. -#} +{#- This includes deprecated groups. -#} +{%- import 'stability.j2' as stability -%} +{%- import 'requirement.j2' as requirement %} +{%- import 'attribute_table.j2' as at %} +{%- import 'attribute_macros.j2' as attrs -%} + + + + + + +# {{ ctx.id | title_case | acronym }} + +{%- if ctx.groups | length > 1 %} +{% for group in ctx.groups | sort(attribute='id') %} +- [{{ attrs.display_name(group) }}](#{{ attrs.heading_link_fragments(attrs.display_name(group)) }}) +{%- endfor -%} +{%- endif %}{% for group in ctx.groups | sort(attribute='id') %} + +## {{ attrs.display_name(group) }} + +**Status:** {{ stability.badge(group.stability, group.deprecated) }} + +**Summary:** {{ group.brief | trim }} + +{%- if group.note %} + +**Description:** {{ group.note | trim }}{% endif %} + +{%- if group.entity_associations is sequence %} + +**Entity Associations** SHOULD be associated with one of the following entities: + +{% for a in group.entity_associations %} +- `{{ a }}` +{% endfor %} +{% endif %} +{%- if group.attributes | length > 0 %} + +### Attributes + +{{ at.generate(group.attributes, "", "/docs/registry/attributes", group.lineage.attributes) | trim }} +{%- endif %}{%- endfor -%} +{{ "\n" }} + + diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index ec0c76351e..c99b81afae 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -7,6 +7,10 @@ templates: filter: '.groups | map(select(.type == "attribute_group")) | map(select(.id | startswith("registry"))) | group_by(.id | split(".") | .[1]) | map({id: .[0].id | split(".") | .[1], groups: .})' application_mode: each file_name: attributes/{{ ctx.id | lower | kebab_case }}.md + - pattern: bundle_details.md.j2 + filter: '.groups | map(select(.id | startswith("bundle"))) | group_by(.id) | map({id: .[0].id, groups: ., namespace: .[0].id | split(".") | .[1]})' + application_mode: each + file_name: 'namespaces/{{ ctx.namespace | kebab_case }}/{{ ctx.id | kebab_case }}.md' - pattern: registry_readme.md.j2 filter: '.' application_mode: single