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,41 @@ | ||
| # 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. | | ||
| | `"error"` | Event with the details of one captured error, fault or exception. | | ||
|
|
||
| ## Message event attributes | ||
|
|
||
| Event `"name"` MUST be `"message"`. | ||
|
|
||
| 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. |
||
|
|
||
| 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. | ||
|
|
||
| ## Error event attributes | ||
|
There was a problem hiding this comment. 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. There was a problem hiding this comment. I will take care of it. |
||
|
|
||
| Event `"name"` MUST be `"error"`. | ||
|
|
||
| | Attribute name | Notes and examples | Required? | | ||
| | :------------- | :------------------------------------- | --------- | | ||
| | `error.kind` | The type or "kind" of an error. E.g., `"Exception"`, `"OSError"` | Yes | | ||
|
There was a problem hiding this comment. In some places we use There was a problem hiding this comment. 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. |
||
| | `error.message` | A concise, human-readable, one-line message explaining the event. E.g., `"Could not connect to backend"`, `"Cache invalidation succeeded"` | Yes | | ||
|
There was a problem hiding this comment. 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. |
||
| | `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 | | ||
|
There was a problem hiding this comment. I suggest There was a problem hiding this comment. I am fine with |
||
| | `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 | | ||
|
There was a problem hiding this comment. Would you allow this to include the caused-by fragments of a Java exception? There was a problem hiding this comment. 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. There was a problem hiding this comment. I have submitted an OTEP open-telemetry/oteps#69 addressing what the value of |
||
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.
This is missing a description of what a
messageevent is even supposed to describe, i.e. when should I addmessageevents to my span.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.
@arminru 29 days ago:
@kbrockhoff please help :-)