Add event.summary as a recommendation for events #1074

alexvanboxel · 2024-05-25T07:53:28Z

Changes

Events are identified by an event.name and attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, event.summary allows a backend to display a human-readable representation of the event.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
If your PR does not need a change log, start the PR title with [chore]
schema-next.yaml updated with changes to existing conventions.

Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, `event.message` allows a backend to display a human-readable representation of the event.

alexvanboxel · 2024-05-26T15:38:04Z

Proposed PR for issue #1076

As discussed in the Eventing SIG on 2024-05-24 cc: @MSNev @trask @JamieDanielson

model/registry/event.yaml

trask · 2024-05-28T18:07:50Z

model/registry/event.yaml

@@ -16,3 +16,13 @@ groups:
          separation of semantics for events in separate domains like browser, mobile, and
          kubernetes.
        examples: ['browser.mouse.click', 'device.app.lifecycle']
+      - id: message


maybe event.description?

I took message as it's a convention that already exists... but granted it could be confusing with messaging.: description is not bad idea.

breedx-splk

Respectfully, I don't think we should do this.

Events are identified by an event.name and attributes and fields in the body that carry specific meaning.

Yes. Events have defined semantics and attributes are spec'd to convey those semantics.

However, since these events will be combined with other logs, event.message allows a backend to display a human-readable representation of the event.

The fact that Events happen to be an extension of Logs should be irrelevant here. Users and consumers of Events should not be concerned with the underlying transport mechanism, and there are APIs to help treat events as a legitimate, separate signal type.

Why are we trying to allow a backend to display something human readable? Backends don't typically display much anyway. It sounds like this use case is already covered by structured logging, and I don't think we should muddy Events with a message field whose human-readable content could be misleading or otherwise conflict the semantics of the event itself.

alexvanboxel · 2024-05-30T06:41:41Z

Why are we trying to allow a backend to display something human readable? Backends don't typically display much anyway. It sounds like this use case is already covered by structured logging, and I don't think we should muddy Events with a message field whose human-readable content could be misleading or otherwise conflict the semantics of the event itself.

Maybe the definition of backend is not clear and could be better specified. I meant as backend logging backends (like DataDog, Google Logging, Elastic, ... those are the systems I have experience with), because they display the logs to the user: For us (as an end-user) it's important to mix our normal logs without events in the same stream. We use the convention of message in our structured logs, so when our teams do exploratory work they don't see blurps of JSON inter-mingeled with normal logs lines.

We defined our internal business event based ontop of structured logs with success (as we mandate the message field in the body). Imagine the backlash we'll get that when we upgrade to OTel events that the experience for the user degrades. That will not help adoption.

alexvanboxel · 2024-05-30T06:57:18Z

We defined our internal business event based ontop of structured logs with success (as we mandate the message field in the body). Imagine the backlash we'll get that when we upgrade to OTel events that the experience for the user degrades. That will not help adoption.

Maybe an extra note: I'm afraid that if we cannot leverage the fact that logs are also meant for human consumption, for events, my feeling on the fact that events are built on top of logs will flip to unsupportive (we will keep on using our events based on structured logs). Then, it would probably have been better to make logs their own signal. At least then, if that signal had a message/description in the proto, at least a log-backend could also consume those signals and do something with it.

alexvanboxel · 2024-05-31T11:56:22Z

@MSNev I've removed the workflow started example, and added examples parallel to the examples in event.name
@trask I've changed the PR to change event.message -> event.description (It very much aligns with how a metric is defined, it also has a name and description). Some systems may display the description, others not.

breedx-splk · 2024-06-07T16:52:53Z

I think I could be talked into this if there was wording to say something like "If the event.name for the event is well known and the structure and semantics of the event are described by OpenTelemetry, then the description field SHOULD NOT be populated."

docs/general/events.md

model/registry/event.yaml

trask · 2024-06-07T17:17:12Z

one potential concern with the name event.description is that it's not quite analogous to metric "description" since metric description is a constant value as opposed to this new proposal which varies per event instance

alexvanboxel · 2024-06-07T19:47:34Z

As asked in the Eventing SIG, I'll add a few redacted events with its message/summary/description:

Event: import:dgc_asset_import
Summary: Exported 1057 nodes from 166 roots in 0.051s

{
  "message": "Exported 1057 nodes from 166 roots in 0.051s",
  "event_class": "generic",
  "event_name": "export:dgc_asset_export",
  "root_nodes_count": 166,
  "authenticated_id": "REDACTED",
  "duration": 51,
  "output_format": "JSON",
  "root_resource_type": "terms",
  "c4_container": "backend",
  "max_page_nodes_count": 1057,
  "send_notification": false,
  "query_limit": 200,
  "resource_types": [
    "vocabulary",
    "terms",
    "attributes",
    "source",
    "type",
    "status",
    "target"
  ],
  "timestamp": "2024-06-07T19:11:44.563Z",
  "data_size": 404475,
  "trace_id": "8853d755645a95f3809341f2c41ed92c",
  "output_type": "TEXT",
  "all_nodes_count": 1057,
  "span_id": "bcad170d7e71c0d0",
  "count_limit": 10001,
  "query_type": "TABLE_VIEW_CONFIG",
  "validation_enabled": false,
  "request_source": "JAVA_API",
  "valid_query": true,
  "c4_system": "knowledgegraph",
  "status": "INFO"
}

Event: import:dgc_asset_import
Summary: Asset import completed with result: SUCCESS

{
  "message": "Asset import completed with result: SUCCESS",
  "operation_type": "IMPORT",
  "community_by_mapping_count": 0,
  "simulation": false,
  "resources_updated": {
    "MP": 5
  },
  "job_state": "COMPLETED",
  "authenticated_id": "REDACTED",
  "duration": 25,
  "community_by_name_count": 0,
  "domain_by_id_count": 0,
  "asset_by_name_count": 0,
  "domain_by_mapping_count": 0,
  "file_type": "JSON",
  "job_result": "SUCCESS",
  "send_notification": false,
  "continue_on_error": false,
  "timestamp": "2024-06-07T19:11:44.568Z",
  "commands_executed": 0,
  "trace_id": "bcdfe64836f084dac3edd79b33546fd4",
  "span_id": "6d3936b98a8181e4",
  "community_by_id_count": 0,
  "domain_by_name_count": 0,
  "asset_by_mapping_count": 5,
  "request_source": "REST_API",
  "commands_skipped": 0,
  "save_result": false,
  "asset_by_id_count": 0,
  "service": "dgc",
  "job_id": "REDACTED",
  "event_class": "generic",
  "event_name": "import:dgc_asset_import",
  "commands_count_in_request": 7,
  "errors_count": 0,
  "status": "INFO"
}

Event: catalogjdbc:edge_jdbc_connect
Summary: connection to the datasource has been established

{
  "message": "connection to the datasource has been established",
  "database_name": "REDACTED",
  "timing": {
    "total_calls": 2,
    "time_unit": "MILLISECONDS",
    "max_time": 16994,
    "mean_time": 8606,
    "total_time": 17212
  },
  "schema_connection_id": "REDACTED",
  "schema_name": "REDACTED",
  "driver_class_name": "REDACTED",
  "duration": 17212,
  "tmp_msg": "",
  "database_id": "REDACTED",
  "engine": "JAVA_API",
  "service": "jdbc-ingestion",
  "schema_id": "REDACTED",
  "event_name": "catalogjdbc:edge_jdbc_connect",
  "event_class": "generic",
  "correlation_id": "REACTED",
  "status": "INFO",
  "timestamp": "2024-06-07T19:27:10.826Z"
}

breedx-splk · 2024-06-07T21:05:45Z

Thanks for the examples, @alexvanboxel . I think these do a good job of demonstrating what these are for, and I think they also demonstrate:

The data in the message is redundant with the data contained in the event body. In the first example, node count, root count, and time are all fields within the event. In the second example, the message effectively restates the job_state (COMPLETED) and job_result (SUCCESS). In the third example, the message seems to be explaining the semantic behind the event name itself. I definitely understand that this can be useful to a human operator who might otherwise be unfamiliar with the event structure....however, I think in practice this is better solved by having schema-aware (event-specific) toString() type implementations. Because...
The free-form nature of the message field opens itself up to inaccurate or misleading information! And because the field is just any text, it is impossible to constrain/limit the contents via conventions or specification. For example, there's nothing to prevent the message in the second example from reading "Asset import failed with result: MEGAFAILURE", even though this directly conflicts with the true event content.

I will remove my blocking request, because I think there isn't too much harm in this, but unfortunately I cannot offer a supportive approval. I ask that other reviewers please consider some phrasing that discourages the use of the message/description/summary for well-specified otel events.

I also still think that an attribute is a reasonable place to put a summary of the event, and we don't need it to be first-class Event field.

I've said my peace. Others can continue discussing.

alexvanboxel · 2024-06-10T08:14:33Z

Thanks for the examples, @alexvanboxel . I think these do a good job of demonstrating what these are for, and I think they also demonstrate:

The data in the message is redundant with the data contained in the event body. In the first example, node count, root count, and time are all fields within the event. In the second example, the message effectively restates the job_state (COMPLETED) and job_result (SUCCESS). In the third example, the message seems to be explaining the semantic behind the event name itself. I definitely understand that this can be useful to a human operator who might otherwise be unfamiliar with the event structure....however, I think in practice this is better solved by having schema-aware (event-specific) toString() type implementations. Because...

The free-form nature of the message field opens itself up to inaccurate or misleading information! And because the field is just any text, it is impossible to constrain/limit the contents via conventions or specification. For example, there's nothing to prevent the message in the second example from reading "Asset import failed with result: MEGAFAILURE", even though this directly conflicts with the true event content.

I will remove my blocking request, because I think there isn't too much harm in this, but unfortunately I cannot offer a supportive approval. I ask that other reviewers please consider some phrasing that discourages the use of the message/description/summary for well-specified otel events.

I also still think that an attribute is a reasonable place to put a summary of the event, and we don't need it to be first-class Event field.

Thanks for the feedback. I've added a section that I hope formulates your concerns. I've also renamed everything to summary as this is till now the best name that was suggested.

alexvanboxel · 2024-06-10T08:15:40Z

one potential concern with the name event.description is that it's not quite analogous to metric "description" since metric description is a constant value as opposed to this new proposal which varies per event instance

Yes, I think summary is the best name suggested.

trask · 2024-06-10T21:27:19Z

event.summary allows a backend to display a human-readable representation of the event

does the same issue exist for how to display a human-readable representation of a structured log?

tedsuo · 2024-06-14T17:40:27Z

Had a discussion about the summary attribute today in the Event SIG. It's a very useful field, Alex's example above (#1074 (comment)) really shows that.

One question is whether the content of the summary attribute should be strictly defined as part of the semantic convention for the event. We (Me, Nev, Trask) feel that the value should not be strictly defined. Like severity, the event summary is context specific: whatever message the person writing the event wants to communicate to the person reading the event is fine.

For example, a commonly defined database event in a particular library may want to include a library-specific summary. An end user tracking down a production problem may flag a particular failure or exception as suspicious and mention some context specific information in the summary.

Because the content of this attribute is not intended to be indexed and used as part of machine analysis, strictly defining its content is not necessary. This is different from the Span name field, which is used both as a primary index and a UI label and thus ends up creating a lot of fuss about its structure and content. I appreciate having the concept of a summary field that has no purpose other than to deliver a short message from one human to another.

Personally, I would prefer summary to be a proto field, not an attribute, in order to keep it completely separate from the attributes which are intended to be used as indexes. But I'm not going to die on that hill, I don't think that there is real harm in keeping it as an attribute. :)

lmolkova · 2024-06-14T18:39:01Z

model/registry/event.yaml

+          Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific
+          meaning. However, since these events will be combined with other logs, `event.summary` allows a
+          centralized logging system to display a human-readable representation of the event.
+


This paragraph does not seem to provide new information - it's already captured in the event name, the markdown, and the brief. Could it be removed?

Suggested change

Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific

meaning. However, since these events will be combined with other logs, `event.summary` allows a

centralized logging system to display a human-readable representation of the event.

lmolkova · 2024-06-14T18:47:42Z

model/registry/event.yaml

+          When summaries are generated, they are not expected to include every attribute and field that is part of the
+          event but could contain those that are meaningful for a human operator when visually navigating a centralized
+          log system. Instrumentation libraries that produce events defined within the standard OpenTelemetry are not
+          expected to add an `event.summary` attribute, as these are well-known events.


Could we make it normative? E.g.

Suggested change

When summaries are generated, they are not expected to include every attribute and field that is part of the

event but could contain those that are meaningful for a human operator when visually navigating a centralized

log system. Instrumentation libraries that produce events defined within the standard OpenTelemetry are not

expected to add an `event.summary` attribute, as these are well-known events.

It's NOT RECOMMENDED to record full string representation of the event on the `event.summary` attribute. The summary SHOULD be concise and human-readable as it's expected to be used by a human operator when visually navigating a centralized log system.

I removed

Instrumentation libraries that produce events defined within the standard
OpenTelemetry are not expected to add an event.summary attribute, as these are well-known events.

I'm not sure how it could work - if we have 100+ events defined, no backend would be able to special-case each event and define human-readable representation of it. I.e. I don't understand why we would NOT allow to define a summary for at least some standards events.

thompson-tomo · 2024-06-15T12:21:54Z

I would also agree to not making it strongly typed and instead would propose an attribute for the outcome as suggested in #1089

github-actions · 2024-07-01T03:20:24Z

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

github-actions · 2024-07-08T03:20:33Z

Closed as inactive. Feel free to reopen if this PR is still being worked on.

MSNev · 2024-07-12T17:09:37Z

@alexvanboxel Do you want this reopened?

alexvanboxel · 2024-07-13T09:29:28Z

@alexvanboxel Do you want this reopened?

yes, please. I've been on holiday and couldn't (we'll it holiday) pick this up. I can pick it up again.

github-actions · 2024-07-30T03:20:50Z

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

JamieDanielson · 2024-08-19T22:29:49Z

In looking at this again, my understanding of the general consensus so far is that having event.summary as an optional property on events is fine, and in some cases especially useful for human operators to get a succinct summary of valuable details within the event. The open questions I can see are:

Should this be a top-level field as it is here, or should it be an attribute?
What is the expectation for "well-known" events in OTel? Should summary be optional, required, or "disallowed"?

Is there anything else I am missing that needs to be resolved for this?

thompson-tomo · 2024-08-27T11:55:57Z

.chloggen/event-message.yaml

+# Use pipe (|) for multiline entries.
+subtext: |
+  Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific
+  meaning. However, since these events will be combined with other logs, `event.description` allows a


Should be event.summary

thompson-tomo · 2024-08-27T11:57:36Z

The biggest question for me is should the summary be strongly typed ie an enum or free text

github-actions · 2024-09-12T03:20:29Z

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

github-actions · 2024-10-04T03:21:17Z

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

github-actions · 2024-10-12T03:20:53Z

Closed as inactive. Feel free to reopen if this PR is still being worked on.

alexvanboxel force-pushed the eventmessage branch from f2a4fca to f55bff4 Compare May 26, 2024 09:43

alexvanboxel force-pushed the eventmessage branch from f55bff4 to 02c0631 Compare May 26, 2024 10:54

alexvanboxel marked this pull request as ready for review May 26, 2024 11:06

alexvanboxel requested a review from tigrannajaryan as a code owner May 26, 2024 11:06

alexvanboxel requested review from a team May 26, 2024 11:06

github-actions bot assigned reyang May 26, 2024

trisch-me approved these changes May 26, 2024

View reviewed changes

MSNev reviewed May 28, 2024

View reviewed changes

model/registry/event.yaml Outdated Show resolved Hide resolved

trask reviewed May 28, 2024

View reviewed changes

breedx-splk previously requested changes May 29, 2024

View reviewed changes

MSNev mentioned this pull request May 29, 2024

Events should recommend having an outcome attribute #1089

Open

alexvanboxel force-pushed the eventmessage branch 2 times, most recently from 42a1401 to 3ac8d4a Compare May 31, 2024 10:52

Address issues from PR

23efdca

alexvanboxel force-pushed the eventmessage branch from 3ac8d4a to 23efdca Compare May 31, 2024 11:09

alexvanboxel changed the title ~~Add event.message as a recommendation for events~~ Add event.description as a recommendation for events May 31, 2024

JamieDanielson reviewed Jun 7, 2024

View reviewed changes

docs/general/events.md Outdated Show resolved Hide resolved

JamieDanielson reviewed Jun 7, 2024

View reviewed changes

model/registry/event.yaml Outdated Show resolved Hide resolved

Merge branch 'main' into eventmessage

0f1a43c

Add more clarity on the purpose of summary

8f19d75

alexvanboxel force-pushed the eventmessage branch from 1952be4 to 8f19d75 Compare June 10, 2024 08:07

alexvanboxel changed the title ~~Add event.description as a recommendation for events~~ Add event.summary as a recommendation for events Jun 10, 2024

lmolkova reviewed Jun 14, 2024

View reviewed changes

github-actions bot added the Stale label Jul 1, 2024

github-actions bot closed this Jul 8, 2024

alexvanboxel reopened this Jul 13, 2024

github-actions bot removed the Stale label Jul 14, 2024

github-actions bot added the Stale label Jul 30, 2024

JamieDanielson removed the Stale label Aug 6, 2024

thompson-tomo suggested changes Aug 27, 2024

View reviewed changes

github-actions bot added the Stale label Sep 12, 2024

github-actions bot removed the Stale label Sep 19, 2024

github-actions bot added the Stale label Oct 4, 2024

github-actions bot closed this Oct 12, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add event.summary as a recommendation for events #1074

Add event.summary as a recommendation for events #1074

alexvanboxel commented May 25, 2024 •

edited

Loading

alexvanboxel commented May 26, 2024

trask May 28, 2024

alexvanboxel May 29, 2024

breedx-splk left a comment

alexvanboxel commented May 30, 2024 •

edited

Loading

alexvanboxel commented May 30, 2024 •

edited

Loading

alexvanboxel commented May 31, 2024

breedx-splk commented Jun 7, 2024

trask commented Jun 7, 2024

alexvanboxel commented Jun 7, 2024

breedx-splk commented Jun 7, 2024

alexvanboxel commented Jun 10, 2024

alexvanboxel commented Jun 10, 2024

trask commented Jun 10, 2024

tedsuo commented Jun 14, 2024

lmolkova Jun 14, 2024

lmolkova Jun 14, 2024 •

edited

Loading

thompson-tomo commented Jun 15, 2024 •

edited

Loading

github-actions bot commented Jul 1, 2024

github-actions bot commented Jul 8, 2024

MSNev commented Jul 12, 2024

alexvanboxel commented Jul 13, 2024

github-actions bot commented Jul 30, 2024

JamieDanielson commented Aug 19, 2024

thompson-tomo Aug 27, 2024

thompson-tomo commented Aug 27, 2024

github-actions bot commented Sep 12, 2024

github-actions bot commented Oct 4, 2024

github-actions bot commented Oct 12, 2024

	Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific
	meaning. However, since these events will be combined with other logs, `event.summary` allows a
	centralized logging system to display a human-readable representation of the event.

Add event.summary as a recommendation for events #1074

Add event.summary as a recommendation for events #1074

Conversation

alexvanboxel commented May 25, 2024 • edited Loading

Changes

Merge requirement checklist

alexvanboxel commented May 26, 2024

trask May 28, 2024

Choose a reason for hiding this comment

alexvanboxel May 29, 2024

Choose a reason for hiding this comment

breedx-splk left a comment

Choose a reason for hiding this comment

alexvanboxel commented May 30, 2024 • edited Loading

alexvanboxel commented May 30, 2024 • edited Loading

alexvanboxel commented May 31, 2024

breedx-splk commented Jun 7, 2024

trask commented Jun 7, 2024

alexvanboxel commented Jun 7, 2024

breedx-splk commented Jun 7, 2024

alexvanboxel commented Jun 10, 2024

alexvanboxel commented Jun 10, 2024

trask commented Jun 10, 2024

tedsuo commented Jun 14, 2024

lmolkova Jun 14, 2024

Choose a reason for hiding this comment

lmolkova Jun 14, 2024 • edited Loading

Choose a reason for hiding this comment

thompson-tomo commented Jun 15, 2024 • edited Loading

github-actions bot commented Jul 1, 2024

github-actions bot commented Jul 8, 2024

MSNev commented Jul 12, 2024

alexvanboxel commented Jul 13, 2024

github-actions bot commented Jul 30, 2024

JamieDanielson commented Aug 19, 2024

thompson-tomo Aug 27, 2024

Choose a reason for hiding this comment

thompson-tomo commented Aug 27, 2024

github-actions bot commented Sep 12, 2024

github-actions bot commented Oct 4, 2024

github-actions bot commented Oct 12, 2024

alexvanboxel commented May 25, 2024 •

edited

Loading

alexvanboxel commented May 30, 2024 •

edited

Loading

alexvanboxel commented May 30, 2024 •

edited

Loading

lmolkova Jun 14, 2024 •

edited

Loading

thompson-tomo commented Jun 15, 2024 •

edited

Loading