From 74d9e314ac945e6dd6b8202fd78fdb7b605a71bf Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Mon, 19 Aug 2024 12:34:58 -0700 Subject: [PATCH] Code review. --- docs/attributes-registry/log.md | 44 ++++++++++--------- docs/general/logs.md | 37 +++++++++------- model/logs/general.yaml | 4 ++ model/registry/log.yaml | 76 ++++++++++++++++++++++++++++++++- 4 files changed, 122 insertions(+), 39 deletions(-) diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md index bc8429180f..160b1b8c8f 100644 --- a/docs/attributes-registry/log.md +++ b/docs/attributes-registry/log.md @@ -40,21 +40,22 @@ Attributes for a file to which log was emitted. This document defines the generic attributes that may be used in any Log Record. -| Attribute | Type | Description | Examples | Stability | -| --------------------- | ------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `log.record.id` | string | A durable identifier for the Log Record. [1] | `1`; `0x100F` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.record.name` | string | A durable name for the Log Record. [2] | `RequestProcessed`; `InvalidResponse` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.record.original` | string | The complete orignal Log Record. [3] | `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.record.uid` | string | A unique identifier for the Log Record. [4] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------------- | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `log.record.id` | int | A durable identifier for the Log Record. [1] | `1`; `10018` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.record.name` | string | A durable name for the Log Record. [2] | `RequestProcessed`; `InvalidResponse` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.record.original` | string | The complete orignal Log Record. [3] | `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `log.record.uid` | string | A unique identifier for the Log Record. [4] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** This value MAY be added when processing a Log Record which has the concept of a durable identifier. -A durable identifier is a unique value assigned to a well-known Log Record -inside a given instrumentation scope. A durable identifier SHOULD be traceable -back to a specific piece of code where the log is defined. Durable identifiers -MAY be used by backends to safely and efficiently filter Log Records which -produce high volume and yield low value (spammy logs). +A durable identifier is a unique value assigned to a well-known Log +Record inside a given instrumentation scope. A durable identifier +SHOULD be traceable back to a specific piece of code where the log is +defined. Durable identifiers MAY be used to safely and efficiently +filter Log Records which produce high volume and yield low value +(spammy logs). Consider this psuedo-code example: @@ -86,20 +87,21 @@ internal static partial class LoggerExtensions } ``` -Two log helpers are defined inside the `MyLogic` instrumentation scope: -`LogFoodPriceChanged` (with the durable identifier `1`) and -`LogFoodRecallNotice` (with the durable identifier `2`). All Log Records emitted -using `LogFoodPriceChanged` will have `log.record.id=1` and all Log Records -emitted using `LogFoodRecallNotice` will have `log.record.id=2`. +Two log helpers are defined inside the `MyLogic` instrumentation +scope: `LogFoodPriceChanged` (with the durable identifier `1`) and +`LogFoodRecallNotice` (with the durable identifier `2`). All Log +Records emitted using `LogFoodPriceChanged` will have +`log.record.id=1` and all Log Records emitted using +`LogFoodRecallNotice` will have `log.record.id=2`. **[2]:** This value MAY be added when processing a Log Record which has the concept of a durable name. -A durable name is similar to a durable identifier except it is more friendly -(human-readable). In the above example all Log Records emitted using -`LogFoodPriceChanged` will have `log.record.name=FoodPriceChanged` and all Log -Records emitted using `LogFoodRecallNotice` will have -`log.record.name=FoodRecallNotice`. +A durable name is similar to a durable identifier except it is more +friendly (human-readable). In the above example all Log Records +emitted using `LogFoodPriceChanged` will have +`log.record.name=FoodPriceChanged` and all Log Records emitted using +`LogFoodRecallNotice` will have `log.record.name=FoodRecallNotice`. **[3]:** 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.) diff --git a/docs/general/logs.md b/docs/general/logs.md index abe4e4f158..99c4f2b495 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -44,7 +44,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.id`](/docs/attributes-registry/log.md) | string | A durable identifier for the Log Record. [1] | `1`; `0x100F` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`log.record.id`](/docs/attributes-registry/log.md) | int | A durable identifier for the Log Record. [1] | `1`; `10018` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`log.record.name`](/docs/attributes-registry/log.md) | string | A durable name for the Log Record. [2] | `RequestProcessed`; `InvalidResponse` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`log.record.original`](/docs/attributes-registry/log.md) | string | The complete orignal Log Record. [3] | `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` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`log.record.uid`](/docs/attributes-registry/log.md) | string | A unique identifier for the Log Record. [4] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -52,11 +52,12 @@ These attributes may be used for identifying a Log Record. **[1]:** This value MAY be added when processing a Log Record which has the concept of a durable identifier. -A durable identifier is a unique value assigned to a well-known Log Record -inside a given instrumentation scope. A durable identifier SHOULD be traceable -back to a specific piece of code where the log is defined. Durable identifiers -MAY be used by backends to safely and efficiently filter Log Records which -produce high volume and yield low value (spammy logs). +A durable identifier is a unique value assigned to a well-known Log +Record inside a given instrumentation scope. A durable identifier +SHOULD be traceable back to a specific piece of code where the log is +defined. Durable identifiers MAY be used to safely and efficiently +filter Log Records which produce high volume and yield low value +(spammy logs). Consider this psuedo-code example: @@ -88,26 +89,30 @@ internal static partial class LoggerExtensions } ``` -Two log helpers are defined inside the `MyLogic` instrumentation scope: -`LogFoodPriceChanged` (with the durable identifier `1`) and -`LogFoodRecallNotice` (with the durable identifier `2`). All Log Records emitted -using `LogFoodPriceChanged` will have `log.record.id=1` and all Log Records -emitted using `LogFoodRecallNotice` will have `log.record.id=2`. +Two log helpers are defined inside the `MyLogic` instrumentation +scope: `LogFoodPriceChanged` (with the durable identifier `1`) and +`LogFoodRecallNotice` (with the durable identifier `2`). All Log +Records emitted using `LogFoodPriceChanged` will have +`log.record.id=1` and all Log Records emitted using +`LogFoodRecallNotice` will have `log.record.id=2`. **[2]:** This value MAY be added when processing a Log Record which has the concept of a durable name. -A durable name is similar to a durable identifier except it is more friendly -(human-readable). In the above example all Log Records emitted using -`LogFoodPriceChanged` will have `log.record.name=FoodPriceChanged` and all Log -Records emitted using `LogFoodRecallNotice` will have -`log.record.name=FoodRecallNotice`. +A durable name is similar to a durable identifier except it is more +friendly (human-readable). In the above example all Log Records +emitted using `LogFoodPriceChanged` will have +`log.record.name=FoodPriceChanged` and all Log Records emitted using +`LogFoodRecallNotice` will have `log.record.name=FoodRecallNotice`. **[3]:** 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.) **[4]:** If an uid is provided, other log records with the same uid will be considered duplicates and can be removed safely. This means, that two distinguishable log records MUST have different values. The uid 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/model/logs/general.yaml b/model/logs/general.yaml index d4835d6982..1cabd41768 100644 --- a/model/logs/general.yaml +++ b/model/logs/general.yaml @@ -8,3 +8,7 @@ groups: requirement_level: opt_in - ref: log.record.original requirement_level: opt_in + - ref: log.record.id + requirement_level: recommended + - ref: log.record.name + requirement_level: recommended diff --git a/model/registry/log.yaml b/model/registry/log.yaml index 01d592329e..e7f7e2fbec 100644 --- a/model/registry/log.yaml +++ b/model/registry/log.yaml @@ -63,10 +63,10 @@ groups: 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. + If an uid is provided, other log records with the same uid 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), + The uid 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"] - id: log.record.original @@ -80,3 +80,75 @@ groups: examples: - "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" + - id: log.record.id + type: int + stability: experimental + brief: > + A durable identifier for the Log Record. + note: | + This value MAY be added when processing a Log Record which has the + concept of a durable identifier. + + A durable identifier is a unique value assigned to a well-known Log + Record inside a given instrumentation scope. A durable identifier + SHOULD be traceable back to a specific piece of code where the log is + defined. Durable identifiers MAY be used to safely and efficiently + filter Log Records which produce high volume and yield low value + (spammy logs). + + Consider this psuedo-code example: + + ```csharp + internal static partial class LoggerExtensions + { + [LogMessage( + 1, // Durable identifier + "FoodPriceChanged", // Durable name + LogLevel.Information, // Severity + "Food `{name}` price changed to `{price}`.")] // Body + public static partial void LogFoodPriceChanged( + this ILogger logger, // Instrumentation scope + string name, // Attribute + double price); // Attribute + + [LogMessage( + 2, // Durable identifier + "FoodRecallNotice", // Durable name + LogLevel.Critical, // Severity + "A `{productType}` recall notice was published for `{brandName} {productDescription}` produced by `{companyName}` ({recallReasonDescription}).")] // Body + public static partial void LogFoodRecallNotice( + this ILogger logger, // Instrumentation scope + string brandName, // Attribute + string productDescription, // Attribute + string productType, // Attribute + string recallReasonDescription, // Attribute + string companyName); // Attribute + } + ``` + + Two log helpers are defined inside the `MyLogic` instrumentation + scope: `LogFoodPriceChanged` (with the durable identifier `1`) and + `LogFoodRecallNotice` (with the durable identifier `2`). All Log + Records emitted using `LogFoodPriceChanged` will have + `log.record.id=1` and all Log Records emitted using + `LogFoodRecallNotice` will have `log.record.id=2`. + examples: + - "1" + - "10018" + - id: log.record.name + type: string + stability: experimental + brief: > + A durable name for the Log Record. + note: | + This value MAY be added when processing a Log Record which has the + concept of a durable name. + + A durable name is similar to a durable identifier except it is more + friendly (human-readable). In the above example all Log Records + emitted using `LogFoodPriceChanged` will have + `log.record.name=FoodPriceChanged` and all Log Records emitted using + `LogFoodRecallNotice` will have `log.record.name=FoodRecallNotice`. + examples: + - "RequestProcessed" + - "InvalidResponse"