Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change event.name attribute into top-level event name field #4320

Merged
merged 11 commits into from
Dec 6, 2024
+19 −4
Merged

Change event.name attribute into top-level event name field #4320

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e994c1b
Change event.name attribute into top-level event name field
trask Dec 4, 2024
723c416
Add change log entry
trask Dec 4, 2024
e9a8087
Add event name as optional parameter to Emit a LogRecord
trask Dec 4, 2024
d8311a7
Add Event Name to ReadWriteLogRecord
trask Dec 4, 2024
98b0960
toc
trask Dec 4, 2024
a1da7c1
toc
trask Dec 4, 2024
3e3eff3
Inline some of the development status sections to simplify
trask Dec 5, 2024
c7cc693
Move change log entry to logs section and delete events section
trask Dec 5, 2024
78b21da
feedback
trask Dec 5, 2024
49a001b
Merge remote-tracking branch 'upstream/main' into add-event-name-field
trask Dec 6, 2024
85fdf71
Merge branch 'main' into add-event-name-field
reyang Dec 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ release.

- Add in-development support for `otlp/stdout` exporter via `OTEL_LOGS_EXPORTER`.
([#4183](https://github.com/open-telemetry/opentelemetry-specification/pull/4183))

### Events
- Change `event.name` attribute into top-level event name field.
trask marked this conversation as resolved.
Show resolved Hide resolved
([#4320](https://github.com/open-telemetry/opentelemetry-specification/pull/4320))

### Baggage

Expand Down
4 changes: 2 additions & 2 deletions specification/logs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ The API MUST accept the following parameters:
- [Severity Text](./data-model.md#field-severitytext) (optional)
- [Body](./data-model.md#field-body) (optional)
- [Attributes](./data-model.md#field-attributes) (optional)
- **Status**: [Development](../document-status.md) - [Event Name](./data-model.md#event-name) (optional)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like I'm late to the game, but here's some thoughts...

  • In .NET ILogger API we have CategoryName always and optional EventId structure (which contains Name & Id). So what goes here? EventId.Name may not be present and if it is, presumably, it is only unique the context of a CategoryName. So should this be prefixed? EventName = $"{CategoryName}.{EventName}" or do we also need something like EventNamespace defined?

  • Seems odd to introduce "Event" into the Log API given there is an "Event" API defined right below. Seems to invite confusion 😄 Why not just "Name" here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems odd to introduce "Event" into the Log API given there is an "Event" API defined right below

check out discussions at https://cloud-native.slack.com/archives/C062HUREGUV/p1733358994263159

since it's low level API it should support all logs features (including events), so it should take a name

and https://cloud-native.slack.com/archives/C062HUREGUV/p1733398117155609

The whole reason why the Go SIG was asking that the "Emit an Event" should be optional in the OTEP (see: open-telemetry/oteps#265 (comment)) is that after spending about a year designing the Logs API and SDK we felt that adding a separate method is a wrong decision.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not just "Name" here?

it's going to map to new proto field event_name (open-telemetry/opentelemetry-proto#600)

Copy link
Contributor

@chalin chalin Dec 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that #event-name is an invalid hash, see the website build failures in https://github.com/open-telemetry/opentelemetry.io/actions/runs/12313997571/job/34369378422?pr=5782

The hash should be #field-eventname.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, might it be better to present this as:


#### Enabled

Expand Down Expand Up @@ -173,8 +174,7 @@ formatted as an [event](./data-model.md#events).

**Parameters:**

* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md)
of the Event.
* [Event Name](./data-model.md#event-name) (required)
trask marked this conversation as resolved.
Show resolved Hide resolved
* [Timestamp](./data-model.md#field-timestamp) (optional)
* [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified
the implementation SHOULD set it equal to the current time.
Expand Down
13 changes: 12 additions & 1 deletion specification/logs/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Logs Data Model

**Status**: [Stable](../document-status.md)
**Status**: [Stable](../document-status.md), except where otherwise specified
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that this should be reported as:

Status: Mixed


<details>
<summary>Table of Contents</summary>
Expand Down Expand Up @@ -34,6 +34,7 @@
* [Field: `InstrumentationScope`](#field-instrumentationscope)
* [Field: `Attributes`](#field-attributes)
+ [Errors and Exceptions](#errors-and-exceptions)
* [Field: `EventName`](#field-eventname)
- [Example Log Records](#example-log-records)
- [Example Mappings](#example-mappings)
- [References](#references)
Expand Down Expand Up @@ -208,6 +209,7 @@ Body |The body of the log record.
Resource |Describes the source of the log.
InstrumentationScope|Describes the scope that emitted the log.
Attributes |Additional information about the event.
**Status**: [Development](../document-status.md) - EventName | Name that identifies the class / type of event.

Below is the detailed description of each field.

Expand Down Expand Up @@ -477,6 +479,15 @@ of the record.
If included, they MUST follow the OpenTelemetry
[semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md).

### Field: `EventName`

**Status**: [Development](../document-status.md)

Type: string.

Description: Name that identifies the class / type of event.
This name SHOULD uniquely identify the event structure (both attributes and body).
trask marked this conversation as resolved.
Show resolved Hide resolved

## Example Log Records

For example log records see
Expand Down
1 change: 1 addition & 0 deletions specification/logs/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,7 @@ the following information added to the [LogRecord](data-model.md#log-and-event-r
* [`TraceId`](./data-model.md#field-traceid)
* [`SpanId`](./data-model.md#field-spanid)
* [`TraceFlags`](./data-model.md#field-traceflags)
* **Status**: [Development](../document-status.md) - [`EventName`](./data-model.md#event-name)

The SDK MAY provide an operation that makes a deep clone of a `ReadWriteLogRecord`.
The operation can be used to implement the [isolating processor](#isolating-processor)
Expand Down
2 changes: 1 addition & 1 deletion specification/versioning-and-stability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ Semantic Conventions defines the set of fields in the OTLP data model:
of well-known values.
- For log records that are [Log Events](logs/event-api.md)
- The following data provided to [emit event](logs/event-api.md#emit-event):
- The event name (the value of the `event.name` attribute)
- The event name

Things not listed in the above are not expected to remain stable via semantic
convention and are allowed (or expected) to change. A few examples:
Expand Down
Loading