diff --git a/docs/attributes-registry/log.md b/docs/attributes-registry/log.md index c24c22b1ac..bc8429180f 100644 --- a/docs/attributes-registry/log.md +++ b/docs/attributes-registry/log.md @@ -40,12 +40,68 @@ 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.original` | string | The complete orignal 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `log.record.uid` | string | A unique identifier for the Log Record. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** 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]:** 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. +| 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) | + +**[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). + +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`. + +**[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`. + +**[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/docs/general/logs.md b/docs/general/logs.md index b43357fdaf..abe4e4f158 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -44,16 +44,69 @@ 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.original`](/docs/attributes-registry/log.md) | string | The complete orignal 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` | `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. [2] | `01ARZ3NDEKTSV4RRFFQ69G5FAV` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1]:** 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]:** 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.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.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) | + +**[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). + +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`. + +**[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`. + +**[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.