Skip to content

Commit

Permalink
Code review.
Browse files Browse the repository at this point in the history
  • Loading branch information
@CodeBlanch
CodeBlanch committed Aug 19, 2024
1 parent 1f3c200 commit 74d9e31
Show file tree
Hide file tree
Showing 4 changed files with 122 additions and 39 deletions.
44 changes: 23 additions & 21 deletions docs/attributes-registry/log.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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.)

Expand Down
37 changes: 21 additions & 16 deletions docs/general/logs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,19 +44,20 @@ 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) |

**[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:

Expand Down Expand Up @@ -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.




<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
Expand Down
4 changes: 4 additions & 0 deletions model/logs/general.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
76 changes: 74 additions & 2 deletions model/registry/log.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<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`.
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"

0 comments on commit 74d9e31

Please sign in to comment.