Add EventName to Log and Event Record in data model

[pellared]

This is a proposal to add EventName of type string as a field in the data model instead of having it just a event.name string attribute defined in semantic conventions.

Related to:

• https://github.com/open-telemetry/opentelemetry-specification/issues/4220
• https://github.com/open-telemetry/opentelemetry-specification/issues/4263
• https://github.com/open-telemetry/opentelemetry-specification/pull/4259

Consequences

• Currently, we have no control what type of value would be set to event.name (e.g. by log bridges). Promoting it to a field with a concrete type would make the design more type-safe. So far my understanding is that most people would like to have it as string. On the other hand, there are some cases where users would like to have something different or more lightweight. Personally, I think settling on a concrete "type" is better than having something very generic and abstract. I think that having EventId of any type is nothing better than having event.name defined in semantic conventions. I would consider having EventId of an integer type (instead of EventName as string) for performance reasons; yet this can be tracked separate issue.

It is very important (actually the EventId, the numerical, machine friendly version of EventName that is most important to do ultra fast checks!) for scenarios we are working on in OTel Rust, C++. I don't know if it is something every language/implementation cares about. Given spec does not prohibit an implementation from allowing more parameters, I am totally okay if spec does not mention it, as OTel C++/Rust can offer this as extras.

Originally posted by @cijothomas in https://github.com/open-telemetry/opentelemetry-specification/pull/4203#discussion_r1768896732

• Having event name as a field would make adding some events processing functionalities to the Logs SDK easier (e.g. filtering based on event name)

I am against this proposal as I do not think that handling event.name for Enabled is more important than for other attributes. Passing all attributes "destroys" the idea of Enabled which is supposed to be used by the user to check whether it makes sense to build and emit a log records (performance tuning). The parameters accepted by Logger.Enabled should be "cheap" to construct.

The SDK's Enabled implementation would get the context, severity level, instrumentation scope that should be enough.

Side note: I think that instrumentation libraries emitting events could add a event.namespace instrumentation scope attribute instead of putting the namespace to each event.name value as a prefix. EDIT: I created #4239

If "event.name" is an attribute, then I totally agree! (Which is why OTel .NET, C++, Rust all decided to put EventName as a top-level field in LogRecord, and not inside Attributes)

Originally posted by @cijothomas in https://github.com/open-telemetry/opentelemetry-specification/issues/4220#issuecomment-2391858416

• Bridges for logging libraries that do not have a concept of log record identifier would need to have some convention to map event.name attribute into EventName field. This mapping could be configurable. Therefore, people who do not want to emit events using logging libraries may disable this mapping behavior.

• Emitting events would need to be done by calling Emit Event on Logger (see https://github.com/open-telemetry/opentelemetry-specification/pull/4259) (unless optional parameter EventName is added to Logger.Emit). Log bridges would have to call Emit Event when they would want to produce events

Remark

The main question is whether we want to promote the event.name attribute to a LogRecord EventName string field. The decision on the desired field's name and type can be tracked as a separate issue.

[pellared]

I think this change is important from design perspective, if we want to make sure that we have separate APIs for emitting log records and events.

It allows as to make it impossible to emit an event using Emit a LogRecord - assuming we will not add an optional EventName parameter.

The events would have to be emitted using Emit an Event by both instrumentation code (applications, instrumentation libraries) and bridges (it should be possible as marked in OTEP - maybe it could an opt-in functionality of a bridge) and the parameters could be more constraint than the one for Emit a Record e.g.:

• SeverityNumber is required
• Attributes as "standard attributes" type (instead of log attributes)

[tedsuo]

I would be in favor of this!

I have concerns around supporting 3rd party loggers wanting to create events. Those loggers would not have a name field, so they would need to use something like an event.name attribute. As long as we think these events can be caught and transformed properly before entering into any Otel pipeline then this is not a problem. If we cannot have this expectation, then any pipeline processor would have to check two places for the event name – the event.name attribute and the Name field. That would be annoying, I would prefer we avoid this scenario.

[tedsuo]

But I do think the Name field should be added as an option onto the EmitLogRecord function. In part for the reasons described in the comment above: there may be bridges to loggers that are creating events in some way. But also because it seems wrong to hide it.

[pellared]

there may be bridges to loggers that are creating events in some way

The bridges can use Emit a Record when they want to emit an event and not a regular log record. See https://github.com/open-telemetry/opentelemetry-specification/issues/4260#issuecomment-2416659743

[pellared]

SIG meeting notes:

• This should be blocking stabilization of events handling in Logs SDK.
• All attendees are in favor of this change but it would have to be validated with the rest of the OTel community.

[lmolkova]

Based on the discussion in the Logs SIG (11/26) and during spec call (11/19) we'd like to proceed with the change.

We'll break it down into several pieces

1. [x] Update data model in the spec repo -https://github.com/open-telemetry/opentelemetry-specification/pull/4320

   • Update Logger.emit or LogRecord API to take optional event name

2. [x] Update proto definition - https://github.com/open-telemetry/opentelemetry-proto/pull/600

3. [x] Deprecate event.name attribute in semantic conventions and update links to data model. - @lmolkova

   • Open question: we might want to reserve event.name for bridging purposes - this door remains open after deprecation
   • https://github.com/open-telemetry/semantic-conventions/pull/1646

4. [ ] PRs/prototypes for OTel API/SDK that add EventName

   • [ ] Python + OpenAI instrumentation with events - @lmolkova
   • [ ] Java - @trask
   • [ ] Collector - @lmolkova - OTLP receiver/exporter - Processors - anything special there?

5. Socialize it across sigs (spec, maintainers, client, semconv)

There will be no backward compatibility or transition period given that event.name is an experimental attribute used by relatively new experimental conventions.

• OTel SDKs that provide emit event API should populate top-level EventName property on the LogRecord instead of event.name attribute when this attribute was populated by the SDK.
• If event.name is provided by the caller, SDK is not expected to detect or remove it.
• Same goes to collector: it is not expected to interact with event.name attribute in any specific way. Once new proto version is supported, users should be able to use transformation processor to interact with EventName and potentially populate it using event.name attribute value.
• Instrumentations that produce events using explicit event.name attribute can do a breaking change and start using LogRecord.EventName property instead of the attribute. It's up to each instrumentation component to provide (or not provide) transition story.
• Telemetry consumers should expect to receive deprecated event.name attribute, new LogRecord.EventName property or both. When both are present, the LogRecord.EventName should be used as a source of truth.

[lmolkova]

Semantic conventions that depend on event.name:

• gen-ai events and corresponding python instrumentation
• az.resource.log and the corresponding collector receiver
• device.app.lifecycle event - did not find any instrumentations in otel org.
• feature_flag.evaluation aka feature_flag event - no instrumentations in otel org
• exception and rpc.message are span events and should not populate event.name

/cc @open-telemetry/semconv-mobile-approvers @open-telemetry/semconv-feature-flag-approvers, LMK if I missed something and there are instrumentations or other components that populate event.name attribute.

[tigrannajaryan]

There will be no backward compatibility or transition period given that event.name is an experimental attribute used by relatively new experimental conventions.

I like the simplicity of this approach, however in the spec call where this change was discussed the idea that we will have a transition period was floated. Please make sure there is clear visibility that we are not doing it (Slack, spec call, Log SIG, etc). I want to make sure there are no existing users of event.name that we don't know about and who we will cause pain by this decision.