Skip to content

Commit

Permalink
Add durable identifier log record attributes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@CodeBlanch
CodeBlanch committed Aug 16, 2024
1 parent b6793e2 commit 1f3c200
Show file tree
Hide file tree
Showing 2 changed files with 128 additions and 19 deletions.
74 changes: 65 additions & 9 deletions docs/attributes-registry/log.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<MyLogic> 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<MyLogic> 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.
73 changes: 63 additions & 10 deletions docs/general/logs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<MyLogic> 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<MyLogic> 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.

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
Expand Down

0 comments on commit 1f3c200

Please sign in to comment.