Common event attribute names #397
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # Semantic conventions for events | ||
|
|
||
| Event types are identified by the event name. Library and application implementors | ||
| are free to define any event name that make sense with the exception of the | ||
| following reserved names. | ||
|
|
||
| ## Reserved event names | ||
|
|
||
| | Event name | Notes and examples | | ||
| | :---------- | :----------------------------------------------------------------- | | ||
| | `"message"` | Event with the details of a single message within a span. | | ||
|
|
||
| ## 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 | ||
|
There was a problem hiding this comment. should the recommended limit on number of messages associated with the span defined? |
||
| span. In case of a stream span such as a gRPC stream, WebSocket or HTTP | ||
| server-sent events, there could be multiple messages with each message recorded | ||
| as an individual event. | ||
|
|
||
| Event `"name"` MUST be `"message"`. | ||
|
There was a problem hiding this comment. This is missing a description of what a There was a problem hiding this comment.
@kbrockhoff please help :-) |
||
|
|
||
| Message events MUST be associated with a tracing span. | ||
|
There was a problem hiding this comment. 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. There was a problem hiding this comment. Yes we should always use them as event attributes even though we know only one event can occur per Span. |
||
|
|
||
| | Attribute name | Notes and examples | Required? | | ||
| | :------------- | :------------------------------------- | --------- | | ||
| | `message.type` | Either `"SENT"` or `"RECEIVED"`. | Yes | | ||
|
There was a problem hiding this comment. should it be boolean or more types are expected? |
||
| | `message.id` | Incremented integer value within the parent span starting with `1`. | Yes | | ||
|
There was a problem hiding this comment. This describes the format, but not the semantic meaning at all. "An incremented integer value" doesn't describe what the attribute is actually telling me. There was a problem hiding this comment. I added paragraph on meaning. There was a problem hiding this comment. Suggestion: maybe just specify these as opaque identifiers? |
||
| | `message.compressed_size` | Compressed size in bytes. | No | | ||
|
There was a problem hiding this comment. is it always known that the message was compressed? Perhaps |
||
| | `message.uncompressed_size` | Uncompressed size in bytes. | No | | ||
|
There was a problem hiding this comment. just as an idea, maybe we should think about a bit shorter names :) if you have any suggestion I would be happy to hear :) There was a problem hiding this comment. You don't really need the word "uncompressed" in my opinion.
|
||
| | `message.content` | The body or main contents of the message. If binary, then message should be Base64 encoded. | No | | ||
|
There was a problem hiding this comment. should there be an attribute for the metadata/headers? May be more valuable than the content of the message and cheaper to collect. |
||
|
|
||
| The `message.id` MUST be calculated as two different counters starting from `1`, | ||
|
There was a problem hiding this comment. What is the use-case for There was a problem hiding this comment. 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. There was a problem hiding this comment. The "two different counters" wording is confusing to me. Above it says this is a single incrementing integer, but this implies that there are 2 integers? Does it mean that a message spend span has an incrementing id, and the message receive span has its own separate incrementing id? In this case, if a parent span sends 3 messages that get ids 1, 2, and 3, and they arrive out of order, one gets dropped, or arrive in separate invocations of the receiver, could they have different ids on the receiving side than they did on the sending side? There was a problem hiding this comment. Added more clarifying verbiage. |
||
| the first for sent messages and the second for received messages. This way we | ||
| guarantee that the values will be consistent between different implementations. | ||
| In protocols where the message id is included as a header in the message, the | ||
| received message id should be that sent be the server instead of its own | ||
| incremented value. | ||
|
|
||
| Most exporters will likely drop the `message.content` attribute if present. | ||
|
There was a problem hiding this comment. Most exporters will likely not drop There was a problem hiding this comment. I could see 3 levels of attribute:
The default tracer would keep recommended and required, a low-bandwidth tracer could drop all except required, and an enhanced attributes tracer could keep all attributes. There was a problem hiding this comment. Additionally there would need to be some database that the exporter can consult to determine in which category an attribute falls. There was a problem hiding this comment. And a way (another use for named tracer?) to tell the tracer which "mode" to operate in. There was a problem hiding this comment. I think the use case of the logging exporter shows that this is a configuration you want to do on the exporter level (logging exporter: all, Jaeger exporter: normal, for example). There was a problem hiding this comment. 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. |
||
| 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. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.