Support complex attributes in the Event API

[trask]

Fixes #4199

Allow complex attributes on Events.

Based on discussion in open-telemetry/semantic-conventions#1651 and in today's Specification SIG meeting (recording).

The biggest struggle currently for launching the Event API is the "two property bags" problem, also known as "do I put my event key/value pairs into event attributes or into the event body?"

The Log SIG has been trying to figure out a satisfactory answer to this for a month.

The proposal from @lmolkova is to put everything into event attributes, eliminating one of these "property bags" and answering the question of where to put event key/value pairs.

The event body could still potentially be used for dumping unstructured (or possibly very large) data.

To make this work, we need complex attributes on Events.

This would allow for example "locally scoped" attributes on an event to be defined as a complex attribute in the semantic conventions, e.g. an event named browser.page_navigation_timing could define a complex attribute in the semantic conventions named browser.page_navigation_timing (could be the same as the event name or different), which would contain it's "locally scoped" event attributes underneath it, e.g.

{
  "user.name": ...,
  ...,
  "browser.page_navigation_timing": {
    "name": ...,
    "fetchStart": ...,
    "unloadEventStart": ...,
    "unloadEventEnd": ...,
    ...
  },
  ...
}

[pellared]

A prototype in OTel Go: open-telemetry/opentelemetry-go#6017

The Go SIG strongly prefers: open-telemetry/opentelemetry-go#6018. However, it is also using supporting complex log attributes. Therefore, still an approval from my side as it makes this prototype more aligned.

[austinlparker]

Quick question/clarification - since this strikes me as extending the common attribute definition (https://opentelemetry.io/docs/specs/otel/common/), are we limiting the depth of complex attributes?

[reyang]

We have limits on the number of attributes https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md#readablelogrecord. This PR would give people a workaround if they just add everything to a single complex attribute - which is concerning from reliability/performance/security perspective.

[pellared]

This PR would give people a workaround if they just add everything to a single complex attribute - which is concerning from reliability/performance/security perspective.

The attribute limiting issue is already present in the existing Logs (Bridge) API. What is more there are no limits for the Body. More:

• No limits for log record body #4006

[trask]

We discussed in the Log SIG yesterday and decided that these both need to be addressed before stabilizing Events:

• Length limits for complex attribute bodies
• What does "number of attributes" limit mean for logs?

I'll open a tracking issue. EDIT #4335

But we don't think it's a blocker for this PR since it's a pre-existing issue for Log attributes.

[reyang]

But we don't think it's a blocker for this PR since it's a pre-existing issue for Log attributes.

+1

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[felixbarny]

Is this just about enabling complex attributes for events or also for logs? In order to be able to map structured data according to the recommendations for logging bridges into attributes, I think it's required for logs to also support complex attributes.

Example:

logger.info('hi', {foo: 'bar', baz: { qux: 'quux'}})
{
  "body": "hi",
  "attributes": {
    "foo": "bar",
    "baz": { qux: "quux"}
  }
}

[trask]

Is this just about enabling complex attributes for events or also for logs?

Logs already support complex attributes (and is stable)

[jsuereth]

TL;DR; I'm in for this direction and this change, but I suspect we may need more language around this change.

This diff is much smaller than I anticipated given.

• As others call out, we should update attribute length guards to include these in the future.
• As discussed in the specification meeting, we should provide guidance around how to interact with rich attributes and "flat" attributes. E.g. is "x": { "y": value } the same as "x.y": value ? (as you know, we've guarded this in semantic conventions)

Approving, under the assumption we all agree on this direction and the follow-on PRs are follow-on PRs.

[pellared]

• As discussed in the specification meeting, we should provide guidance around how to interact with rich attributes and "flat" attributes. E.g. is "x": { "y": value } the same as "x.y": value ? (as you know, we've guarded this in semantic conventions)

Double-checking. Do we have tracking issue for it?

[trask]

As others call out, we should update attribute length guards to include these in the future.

this is tracked in #4335

As discussed in the specification meeting, we should provide guidance around how to interact with rich attributes and "flat" attributes. E.g. is "x": { "y": value } the same as "x.y": value ? (as you know, we've guarded this in semantic conventions)

there are a lot of different pieces to this in my mind, I've added it to next week's spec SIG meeting, I'd like to understand which parts you think are required pre- event stability

[jsuereth]

there are a lot of different pieces to this in my mind, I've added it to next week's spec SIG meeting, I'd like to understand which parts you think are required pre- event stability

Selfishly I want to understand how to model events and attributes in semantic conventions given this change (e.g. what policies do we enforce, what makes a valid event, how do you re-use attributes between events and other signals). I'll have a think about what is needed before we stabilize events, but I do think knowing how to define semconv + instrumentation for them is something we'll need (if not in this PR then prior to saying it's stable).