reword

open-telemetry · Dec 12, 2024 · 75746bc · 75746bc
1 parent 5533be6
commit 75746bc
Show file tree

Hide file tree

Showing 10 changed files with 23 additions and 40 deletions.
diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md
diff --git a/docs/azure/events.md b/docs/azure/events.md
@@ -16,7 +16,7 @@ Resource Log events.
 
 **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-The [EventName](TODO link to new spec model) MUST be `az.resource.log`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `az.resource.log`.
 
 Describes Azure Resource Log event, see [Azure Resource Log Top-level Schema](https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema) for more details.
 

diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md
@@ -49,7 +49,7 @@ try {
 
 **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)
 
-The [EventName](TODO link to new spec model) MUST be `exception`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `exception`.
 
 This event describes a single exception.
 

diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md
@@ -50,7 +50,7 @@ The table below indicates which attributes should be added to the
 
 **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-The [EventName](TODO link to new spec model) MUST be `feature_flag.evaluation`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `feature_flag.evaluation`.
 
 Defines feature flag evaluation as an event.
 

diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
@@ -27,10 +27,10 @@ linkTitle: Generative AI events
 
 <!-- tocstop -->
 
-GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/event-api.md).
+GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event).
 
 > Note:
-> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language.
+> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language.
 
 Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data.
 This is for three primary reasons:

diff --git a/docs/general/events.md b/docs/general/events.md
@@ -5,7 +5,7 @@ aliases: [events-general]
 
 # Semantic Conventions for Events
 
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Development][DocumentStatus]
 
 This document describes the characteristics of standalone Events that are represented
 in the data model by `LogRecord`s.
@@ -15,11 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t
 Examples of Events might include things like uncaught exceptions, button clicks, user logout,
 network connection severed, etc.
 
-In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to
-the conventions included here, and Events
-[have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md).
-The API abstracts away knowledge of `LogRecord` so that users only deal with Event
-semantics.
+In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here.
 
 In addition to a required name, an Event may contain a _payload_ (body) of any type permitted
 by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body).
@@ -34,7 +30,8 @@ structure and semantics will also be defined.
 
 ## General event semantics
 
-* An event MUST have an [Event name property](TODO link to new spec model) that uniquely identifies the event.
+* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)
+  that uniquely identifies the event.
 * It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
   attributes that provide additional context about the event.
 * It MAY contain a _payload_ (body) that describes the specific details of the
@@ -53,29 +50,30 @@ Recommendations for defining events:
   collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
   attributes.
 * Events SHOULD be generated / produced / recorded using the
-    [Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md)
+    [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/tree/v1.40.0/specification/logs/api.md#emit-an-event)
     to ensure that the event is created using the configured SDK instance.
-  * The Event API is not yet available in all OpenTelemetry SDKs.
-  * TODO: Add deep link to the [compliance matrix of the Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md)
-    when it exists.
-* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `event.name` to
+  * The Emit Event API is not yet available in all OpenTelemetry SDKs. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language.
+* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `EventName` to
   avoid redundancy and to keep the event definition clean.
 * The events SHOULD document their semantic conventions including event name,
   attributes, and the payload.
 
 Recommendations on using attributes vs. body fields:
 
-* If the field should be comparable across every type of record, it should be an attribute.
+* If the field should be comparable across events with different `EventName` (or between an event and other telemetry items),
+  it should be an attribute.
 * If the field is specific to the event itself, then it should be a body field.
-* Unless two events share the same `EventName` property value, anything in two event bodies is not comparable to each other.
+* Body fields that belong to events with different event names are not comparable.
+  For example, body field `id` on event `my_company.order_submitted` is semantically different from
+  field `id` on an event with name `session.start`.
 
 ### Event payload (body)
 
 * Common attribute naming conventions and [registry](../attributes-registry/README.md)
   requirements don't apply to event payload fields.
 * The definition for OpenTelemetry defined events supports describing
   individual _fields_ (Body Fields)
-  * The _fields_ are unique to the named event ([EventName](TODO link to new spec model)) and different events
+  * The _fields_ are unique to the named event ([EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)) and different events
     may use the same _field_ name to represent different data, due to the unique
     nature of the event.
 

diff --git a/docs/general/session.md b/docs/general/session.md
@@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve
 
 ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-[EventName](TODO link to new spec model) MUST be`session.start`
+[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be`session.start`
 
 For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted
 every time a session is created. When a new session is created as a continuation of a prior session,
@@ -61,7 +61,7 @@ that the previous session has ended. If the session ID in `session.previous_id`
 
 ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-[EventName](TODO link to new spec model) MUST be `session.end`
+[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `session.end`
 
 For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted
 every time a session ends. When a session ends and continues as a new session, this event SHOULD be

diff --git a/docs/mobile/events.md b/docs/mobile/events.md
@@ -29,7 +29,7 @@ application lifecycle.
 
 **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-The [EventName](TODO link to new spec model) MUST be `device.app.lifecycle`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `device.app.lifecycle`.
 
 This event represents an occurrence of a lifecycle transition on Android or iOS platform.
 

diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md
@@ -266,7 +266,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345.
 
 **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue)
 
-The [EventName](TODO link to new spec model) MUST be `rpc.message`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `rpc.message`.
 
 Describes a message sent or received within the context of an RPC call.
 

diff --git a/templates/registry/markdown/event_macros.j2 b/templates/registry/markdown/event_macros.j2
@@ -3,7 +3,7 @@
 {% import 'body_field_table.j2' as body_table %}
 {% macro header(event) %}**Status:** {{ stability.badge(event.stability, event.deprecated) }}
 
-The [EventName](TODO link to new spec model) MUST be `{{ event.name }}`.
+The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `{{ event.name }}`.
 
 {{ event.brief | trim }}
 {%if event.note %}