Common event attribute names #397

kbrockhoff · 2019-12-17T21:14:11Z

Standard attributes for message and error events.

This reverts commit d7834fe.

jmacd

Overall I'm a but worried that we're rushing into semantic conventions for a logging system, here. I'd like to keep it as restricted as possible until there's more attention to give this broad topic.

jmacd · 2019-12-18T05:35:10Z

specification/data-events.md

+| :------------- | :------------------------------------- | --------- |
+| `error.kind`   | The type or "kind" of an error. E.g., `"Exception"`, `"OSError"` | Yes |
+| `error.message` | A concise, human-readable, one-line message explaining the event. E.g., `"Could not connect to backend"`, `"Cache invalidation succeeded"` | Yes |
+| `error.object` | For languages that support such a thing (e.g., Java, Python), the actual Throwable/Exception/Error object instance itself. E.g., A `java.lang.UnsupportedOperationException` instance, a python `exceptions.NameError` instance | No |


I suggest error.type here. It's not clear how to set error.kind when you have a definite type name, though. Do we need both?

I am fine with error.type. These came from the OpenTracing spec.

jmacd · 2019-12-18T05:36:08Z

specification/data-events.md

+| `error.kind`   | The type or "kind" of an error. E.g., `"Exception"`, `"OSError"` | Yes |
+| `error.message` | A concise, human-readable, one-line message explaining the event. E.g., `"Could not connect to backend"`, `"Cache invalidation succeeded"` | Yes |
+| `error.object` | For languages that support such a thing (e.g., Java, Python), the actual Throwable/Exception/Error object instance itself. E.g., A `java.lang.UnsupportedOperationException` instance, a python `exceptions.NameError` instance | No |
+| `error.stack` | A stack trace in platform-conventional format; may or may not pertain to an error. E.g., `"File \"example.py\", line 7, in \<module\>\ncaller()\nFile \"example.py\", line 5, in caller\ncallee()\nFile \"example.py\", line 2, in callee\nraise Exception(\"Yikes\")\n"` | No |


Would you allow this to include the caused-by fragments of a Java exception?

Would you ever want to record the location where the error is being recorded as distinct from the location where an exception occurred? I think of these as the location of the log statement vs the location of the throw statement, for example.

I have submitted an OTEP open-telemetry/oteps#69 addressing what the value of error.object should be. It would include all of the data items mentioned above.

jmacd · 2019-12-18T05:37:20Z

specification/data-events.md

+| Attribute name | Notes and examples                     | Required? |
+| :------------- | :------------------------------------- | --------- |
+| `error.kind`   | The type or "kind" of an error. E.g., `"Exception"`, `"OSError"` | Yes |
+| `error.message` | A concise, human-readable, one-line message explaining the event. E.g., `"Could not connect to backend"`, `"Cache invalidation succeeded"` | Yes |


There's going to be a desire to record information events that are not errors. It would be nice to have a "message" attribute and a reserved event name for those.

tedsuo · 2019-12-18T17:48:24Z

specification/data-events.md

+
+Event `"name"` MUST be `"message"`.
+
+Message events MUST be associated with a tracing span.


I feel there needs to be some guidance as to when we add these attributes on an event vs on a span. It's fine to say that they should always be an event, even when the span only have one "event" such as an http request.

Yes we should always use them as event attributes even though we know only one event can occur per Span.

tedsuo

Messages, errors, DBs, and other semantic conventions are developing type systems. I feel like we need to review these type systems; right now there is no guidance as to what types we support, and what the semantics for that particular type may be.

For example, If my error type is Exception, how should I fill in the remaining fields? Does it matter?

tedsuo · 2019-12-18T17:53:57Z

specification/data-events.md

+
+| Attribute name | Notes and examples                     | Required? |
+| :------------- | :------------------------------------- | --------- |
+| `error.kind`   | The type or "kind" of an error. E.g., `"Exception"`, `"OSError"` | Yes |


In some places we use kind and in other places we use type to describe the same thing. So now we have message.type and error.kind, along with span.kind and db.type. We should standardize on a single convention for this.

FWIW in the Metrics API spec I've avoided using "type" except when it refers to an actual programming language type, not a more abstract term. So, Instruments have kinds. The values they produce have types.

arminru · 2019-12-19T14:06:44Z

I don't quite understand what the proposed message event is about. When would I use this one and when would I create a (child) span with the attributes defined in #395?

bogdandrutu · 2019-12-25T16:00:03Z

specification/data-events.md

+| `message.type` | Either `"SENT"` or `"RECEIVED"`.       | Yes |
+| `message.id`   | Incremented integer value within the parent span starting with `1`. | Yes |
+| `message.compressed_size` | Compressed size in bytes. | No |
+| `message.uncompressed_size` | Uncompressed size in bytes. | No |


just as an idea, maybe we should think about a bit shorter names :) if you have any suggestion I would be happy to hear :)

You don't really need the word "uncompressed" in my opinion.

message.size - uncompressed size

message.compressed or message.compressed_size - compressed size

bogdandrutu · 2019-12-25T16:04:08Z

specification/data-events.md

+However, logging-only exporters will likely want to log it as this information
+is highly useful during the early stages of developing a new application.
+
+## Error event attributes


Can we split this PR into two (message and errors). I think we should consider if for errors we want to have a more specific helper API than just attributes, also the correlation with the Status.

So to make progress we can probably soon merge the message part and keep discussing the errors.

+1 on splitting it up :)

I will take care of it.

bogdandrutu · 2019-12-25T16:08:21Z

specification/data-events.md

+
+Event `"name"` MUST be `"message"`.
+
+Message events MUST be associated with a tracing span.


Yes we should always use them as event attributes even though we know only one event can occur per Span.

…ions-open-telemetry#362

dyladan · 2020-01-17T14:02:55Z

specification/data-events.md

+| `message.content` | The body or main contents of the message. If binary, then message should be Base64 encoded. | No |
+
+The `message.id` MUST be calculated as two different counters starting from `1`
+one for sent messages and one for received message. This way we guarantee that


Three different uses of one/1 in this sentence, which refer to message id and types of message ids are confusing. I would go with something along the lines of:

The message.id MUST be calculated as two different counters starting from 1, the first for sent messages and the second for received messages.

jmacd · 2020-01-21T21:16:44Z

specification/data-events.md

+
+## Message event attributes
+
+Each message sent/received within a span should be recorded as an event. In the


I'm inclined to say that messages "MAY" be recorded as events. For a gRPC stream, in particular, I'm not sure that message events are always desired. I'd like the semantic convention to apply when the decision is made to record message events, but not to specify when you SHOULD record message events.

jmacd · 2020-01-21T21:29:13Z

specification/data-events.md

+| `message.uncompressed_size` | Uncompressed size in bytes. | No |
+| `message.content` | The body or main contents of the message. If binary, then message should be Base64 encoded. | No |
+
+The `message.id` MUST be calculated as two different counters starting from `1`,


Should this be called a sequence number? It's not clear that message-ids must be sequential integers, nor who is responsible for calculating them. I'd be more comfortable calling them message-ids and not mentioning counters. Some implementations may use counters, some may not.

jmacd · 2020-01-21T21:30:33Z

specification/data-events.md

+In case of unary calls only one sent and one received message will be recorded
+for both client and server spans.
+
+Most exporters will likely drop the `message.content` attribute if present.


Tangentially, it makes me wonder why we don't have an API to declare keys with metadata like a description, some kind of priority as discussed here, potentially type information, as well as a clearly stated namespace.

dyladan · 2020-01-28T14:12:01Z

I'm confused about the use case for when you would use this message event instead of a messaging type span?

dyladan · 2020-02-04T13:55:19Z

@kbrockhoff when would you use message span events rather than a messaging type span?

kbrockhoff · 2020-02-04T19:11:39Z

Message span events are for spans where multiple messages are sent in the same span. For example, gRPC client-side streaming, server-side streaming, bidirectional streaming variants. Another example is HTTP server-sent events. I also see this used even for RPC-type spans where only one message is sent and received. It would be the consistent place where message size and content is recorded rather than in span attributes.

kbrockhoff · 2020-02-04T19:19:03Z

Most of these event attributes are already mentioned in the RPC semantic conventions. https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-rpc.md This PR just separates them out to emphasize they are applicable to more than gRPC.

The only addition is 'message.content' which is important for OpenTelemetry adoption by applications that currently don't have any observability instrumentation.

Oberon00 · 2020-02-05T09:13:01Z

I would think you should simply create multiple spans in that case. I can see the benefit of having to specify the messaging destination only once though (maybe related: #274). So are these events supposed to only occur on messaging spans, or any span? If any span, are they related to "messaging"/pubsub at all? Or are these for any network communication?

arminru · 2020-02-13T16:29:06Z

@kbrockhoff I would also expect that one would just create multiple (child) spans with the messaging attributes (#418) set on them. With the events as well we would have two competing ways of reporting messages without a clear distinction on when to use what.

@bogdandrutu You introduced the events defined in https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-rpc.md#events in PR #7. Do you think we could settle for reporting messages as spans or are there reasons for representing them as events?

kbrockhoff · 2020-02-14T14:22:29Z

It does not make sense to treat each message as a separate span in some streaming cases. This is real code backed by a process that takes 10-15 minutes:

    @GetMapping(path = "/awards-processes/{id}/events", produces = MediaType.APPLICATION_STREAM_JSON_VALUE)
    public Flux<AwardEvent> getAwardProcessEventStream(@PathVariable("id") String id) {
        AwardsProcessor processor = processorMap.get(id);
        if (processor == null ||
                "COMPLETED".equals(processor.getCurrentStatus()) || "FAILED".equals(processor.getCurrentStatus())) {
            return Flux.fromStream(() -> processAwardsService.getEventsForAwardProcess(id).stream());
        } else {
            return processor.getEventStream();
        }
    }

Oberon00 · 2020-02-14T14:31:06Z

@kbrockhoff I assume you would want to trace every single message in the event stream on the span here?

Maybe we could solve this in/after #418 by amending it with wording such as

Any subset of these attributes MAY be set on events with the name "messaging" on the span. In that case, attributes that are always the same for all messaging events SHOULD be set on the span. This might even result in emtpy "messaging" events. If there is nothing in common between the messaging events, a full Span SHOULD be created for each message instead of using events.

This sounds in fact useful for any semantic convention, so maybe we can find a generic wording to add to https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md#span-conventions.

SergeyKanzhelev · 2020-02-17T22:46:04Z

specification/data-events.md

+## Message event attributes
+
+Each message sent/received within a span should be recorded as an event. In the
+case of synchronous RPC calls there will be one sent and one received event per


should the recommended limit on number of messages associated with the span defined?

SergeyKanzhelev · 2020-02-17T22:48:16Z

specification/data-events.md

+| :------------- | :------------------------------------- | --------- |
+| `message.type` | Either `"SENT"` or `"RECEIVED"`.       | Yes |
+| `message.id`   | Unique identifier within a span and `message.type` for the individual message. Further specifications for common protocols are discussed below. | No |
+| `message.compressed_size` | Compressed size in bytes. | No |


is it always known that the message was compressed? Perhaps size will be size of a message, and than two separate sizes for compressed and uncompressed be specified.

SergeyKanzhelev · 2020-02-17T22:49:28Z

specification/data-events.md

+| `message.id`   | Unique identifier within a span and `message.type` for the individual message. Further specifications for common protocols are discussed below. | No |
+| `message.compressed_size` | Compressed size in bytes. | No |
+| `message.uncompressed_size` | Uncompressed size in bytes. | No |
+| `message.content` | The body or main contents of the message. If binary, then message should be Base64 encoded. | No |


should there be an attribute for the metadata/headers? May be more valuable than the content of the message and cheaper to collect.

SergeyKanzhelev · 2020-02-17T22:51:16Z

specification/data-events.md

+
+To conserve bandwith and/or storage, exporters MAY drop the `message.content`
+attribute if present. Logging-only exporters bundled with default OpenTelemetry
+SDKs SHOULD provide affordances for logging this information as it is highly


In case of instrumentation adapters passing an additional configuration may sounds ok. However if messaging SDK is pre-instrumented with OpenTelemetry - it will be a setting on messaging SDK itself. Perhaps this paragraph can be rephrased to express this

SergeyKanzhelev · 2020-02-17T22:52:06Z

specification/data-events.md

+| Attribute name | Notes and examples                     | Required? |
+| :------------- | :------------------------------------- | --------- |
+| `message.type` | Either `"SENT"` or `"RECEIVED"`.       | Yes |
+| `message.id`   | Unique identifier within a span and `message.type` for the individual message. Further specifications for common protocols are discussed below. | No |


specify the attribute type. string?

SergeyKanzhelev · 2020-02-17T22:52:24Z

specification/data-events.md

+
+| Attribute name | Notes and examples                     | Required? |
+| :------------- | :------------------------------------- | --------- |
+| `message.type` | Either `"SENT"` or `"RECEIVED"`.       | Yes |


should it be boolean or more types are expected?

github-actions · 2020-08-12T03:18:31Z

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

bogdandrutu · 2020-08-13T18:14:20Z

This was merged in a different PR. Available in https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/messaging.md

kbrockhoff added 3 commits December 17, 2019 15:06

initial def of event attribute names

d7834fe

Revert "initial def of event attribute names"

c77a664

This reverts commit d7834fe.

initial def of event attribute names

89729ad

kbrockhoff requested review from AloisReitbauer, bogdandrutu, c24t, carlosalberto, iredelmeier, jmacd, reyang, SergeyKanzhelev, songy23, tedsuo, tigrannajaryan and yurishkuro as code owners December 17, 2019 21:14

jmacd reviewed Dec 18, 2019

View reviewed changes

tedsuo reviewed Dec 18, 2019

View reviewed changes

jmacd mentioned this pull request Dec 18, 2019

Rename Message in Event to Name open-telemetry/opentelemetry-go#389

Merged

bogdandrutu reviewed Dec 25, 2019

View reviewed changes

kbrockhoff added 7 commits December 26, 2019 16:32

Merge remote-tracking branch 'upstream/master'

ccfcd27

Merge remote-tracking branch 'upstream/master' into event-sem-convent…

27e93e8

…ions-open-telemetry#362

Merge remote-tracking branch 'upstream/master'

f177ad2

Merge remote-tracking branch 'upstream/master'

94cfd25

Merge remote-tracking branch 'upstream/master'

86a1479

Merge branch 'master' into event-sem-conventions-open-telemetry#362

824d777

remove error event info to separate PR

c54869d

dyladan reviewed Jan 17, 2020

View reviewed changes

jmacd reviewed Jan 21, 2020

View reviewed changes

kbrockhoff added 4 commits January 22, 2020 16:52

Merge remote-tracking branch 'upstream/master'

02e7bd0

Merge remote-tracking branch 'upstream/master'

a42d217

Merge branch 'master' into event-sem-conventions-open-telemetry#362

148d2fd

Improve and expand on the definition of message.id

a5c59ac

kbrockhoff requested review from jmacd, dyladan and Oberon00 January 23, 2020 16:55

SergeyKanzhelev reviewed Feb 17, 2020

View reviewed changes

carlosalberto added the area:semantic-conventions Related to semantic conventions label Jun 12, 2020

reyang added release:required-for-ga Must be resolved before GA release, or nice to have before GA release:after-ga Not required before GA release, and not going to work on before GA and removed release:required-for-ga Must be resolved before GA release, or nice to have before GA labels Jul 6, 2020

github-actions bot added the Stale label Aug 12, 2020

bogdandrutu closed this Aug 13, 2020


		Event `"name"` MUST be `"message"`.

		Message events MUST be associated with a tracing span.


		## Message event attributes

		Each message sent/received within a span should be recorded as an event. In the

Common event attribute names #397

Common event attribute names #397

Conversation

kbrockhoff commented Dec 17, 2019

jmacd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tedsuo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arminru commented Dec 19, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dyladan Jan 17, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dyladan commented Jan 28, 2020

dyladan commented Feb 4, 2020

kbrockhoff commented Feb 4, 2020

kbrockhoff commented Feb 4, 2020

Oberon00 commented Feb 5, 2020

arminru commented Feb 13, 2020

kbrockhoff commented Feb 14, 2020

Oberon00 commented Feb 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Aug 12, 2020

bogdandrutu commented Aug 13, 2020

dyladan Jan 17, 2020 •

edited

Loading

Oberon00 commented Feb 14, 2020 •

edited

Loading