Provide guidance to language SIGs when they need to implement Event API

[lmolkova]

Spec currently says

https://github.com/open-telemetry/opentelemetry-specification/blob/0b3328bb17fa6f86af521f8d22dbbcddea2ac914/specification/logs/event-api.md?plain=1#L40-L53

also

https://github.com/open-telemetry/opentelemetry-specification/blob/0b3328bb17fa6f86af521f8d22dbbcddea2ac914/specification/logs/event-api.md?plain=1#L79-L81

I believe it means that some languages with common logging libraries don't need Event API at all - it's optional.

E.g. today I can write something like

.NET:

logger.LogInformation(new EventId(id: 42, name: "com.foo.my-event-id"), "something important");

Java with slf4j:

logger.atInfo()
 .addKeyValue("event.name", "com.foo.my-event-id")
 .log("something important") 

Python:

logger.info("something important", extra={"event.name": "com.foo.my-event-name"})

Providing structured event bodies is possible too - it's a bit more complicated and nuanced, but we need to support it for both events and logs.

• Presumably many languages can support events though existing common logging facades.
• In such languages Event-specific APIs (EventLogger EventLoggerProvider) are not necessary and don't need to be implemented.
• Arguably AnyValue type is not specific to events and it should be possible to create a log record without event.name with complex body when logging API allows it

---

So, instead of implementing EventLogger (and provider) such languages could define and document how to use existing logging APIs to create events (or logs with structured payloads).

It seems like Event API should only be added when:

• there are no popular/common logging APIs in the ecosystem or
• existing logging APIs don't provide reasonable ways to emit rich logs/events.

Related: https://github.com/open-telemetry/opentelemetry-specification/issues/4189

[jack-berg]

Providing structured event bodies is possible too - it's a bit more complicated and nuanced

This is the key question to me. Even if its possible to record structured bodies, is it intuitive how to do so? At what point are the ergonomics poor enough to justify an API?

I agree with the sentiment of this though.. if a logging API is available and has sufficiently good ergonomics, then using an OpenTelemetry event API only stands to complicate things.

A few other examples of impedance mismatch that may justify a event API:

• Obvious difference between body and attributes, which popular/common logging APIs likely don't make
• Ability to explicitly set the context to control whether or not the log is associated with a span
• Difference notion of scope (i.e. no scope attributes)
• ..maybe more? These examples were off the cuff.

[lmolkova]

I agree that there are caveats and uncertainties. I assume language SIG would decide whether there is a reasonable way to use logging API.

I'd like them to evaluate options and make a decision.

[lmolkova]

To demonstrate that bodies have reasonable ergonomics at least in some languages:

Python: (supported to some extent today)

logger.info({"key": "value", "complex_key": {...}}, extra={"event.name": "com.foo.my-event-name"})

.NET

logger.FoodRecallNotice(new FoodRecallNotice
{
    BrandName = "Contoso",
    ProductDescription = "Salads",
    ProductType = "Food & Beverages",
    RecallReasonDescription = "due to a possible health risk from Listeria monocytogenes",
    CompanyName = "Contoso Fresh Vegetables, Inc.",
});

internal static partial class LoggerExtensions
{
    [LoggerMessage(LogLevel.Critical)]
    public static partial void FoodRecallNotice(
        this ILogger logger,
        [LogProperties(OmitReferenceName = true)] in FoodRecallNotice foodRecallNotice);
}

it does not map complex object to log body (but it could in the future) - see https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/logs/complex-objects