Defined additional semantic convention attribute names

specification/data-async-messaging.md

@@ -0,0 +1,18 @@
+# Semantic conventions for asynchronous messaging spans
+
+For call publishing a message to the bus, the `SpanKind` MUST be `Producer`.
+For call retrieving a message from the bus, the `SpanKind` MUST be `Consumer`.
+
+## Common Attributes
+
+| Attribute name | Notes and examples                                           | Required? |
+| :------------- | :----------------------------------------------------------- | --------- |
+| `message_bus.destination` | An address at which messages can be exchanged. E.g. A Kafka record has an associated "topic name" that can be extracted by the instrumented producer or consumer and stored using this tag. | Yes |
+| `message_bus.type` | The brand of message bus or client API library such as `"kafka"`, `"rabbitmq"` or `"jms"`. | Yes |
+| `message_bus.protocol` | The transport protocol such as `"AMQP"` or `"MQTT"`. | No |
+| `message_bus.user` | Username for accessing bus. E.g., `"tibuser1"` or `"consumer_user"`. | No |
+| `message_bus.url` | Connection substring such as `"tibjmsnaming://localhost:7222"` or `"https://queue.amazonaws.com/80398EXAMPLE/MyQueue"`. | No |
+
+Additionally at least one of `net.peer.name` or `net.peer.ip` from the [network attributes][] is required and `net.peer.port` is recommended.
+
+[network attributes]: data-span-general.md#general-network-connection-attributes

specification/data-events.md

@@ -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.
+
+| Attribute name | Notes and examples                     | Required? |
+| :------------- | :------------------------------------- | --------- |
+| `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 |
+| `message.content` | The body or main contents of the message. If binary, then message should be Base64 encoded. | No |
+
+Most exporters will likely drop the `message.content` attribute if present.
+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
+
+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 |
+| `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 |

specification/data-http.md

@@ -176,10 +176,12 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i
 | `http.server_name` | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | [1] |
 | `http.route` | The matched route (path template). (TODO: Define whether to prepend application root) E.g. `"/users/:userID?"`. | No |
 | `http.client_ip` | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For][]). Note that this is not necessarily the same as `net.peer.ip`, which would identify the network-level peer, which may be a proxy. | No |
+| `http.user_agent` | Value of the HTTP [User-Agent] header sent by the client or else a calculated user agent device identifier compatible with the backend system in use. | No |
 
 [HTTP request line]: https://tools.ietf.org/html/rfc7230#section-3.1.1
 [HTTP host header]: https://tools.ietf.org/html/rfc7230#section-5.4
 [X-Forwarded-For]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
+[User-Agent]: https://tools.ietf.org/html/rfc7231#section-5.5.3
 
 **[1]**: `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. <https://github.com/open-telemetry/opentelemetry-python/pull/148>).
 It is thus preferred to supply the raw data that *is* available.

specification/data-resource-semantic-conventions.md

@@ -40,6 +40,7 @@ Certain attribute groups in this document have a **Required** column. For these
 | service.name | Logical name of the service. <br/> MUST be the same for all instances of horizontally scaled services. | `shoppingcart` | Yes |
 | service.namespace | A namespace for `service.name`.<br/>A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. The field is optional. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. | `Shop` | No |
 | service.instance.id | The string ID of the service instance. <br/>MUST be unique for each instance of the same `service.namespace,service.name` pair (in other words `service.namespace,service.name,service.id` triplet MUST be globally unique). The ID helps to distinguish instances of the same service that exist at the same time (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent and stay the same for the lifetime of the service instance, however it is acceptable that the ID is ephemeral and changes during important lifetime events for the service (e.g. service restarts). If the service has no inherent unique ID that can be used as the value of this attribute it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122 for more recommendations). | `627cc493-f310-47de-96bd-71410b7dec09` | Yes |
+| service.version | The version string of the service API or implementation as defined below under library. | `semver:2.0.0` | No |
 
 Note: `service.namespace` and `service.name` are not intended to be concatenated for the purpose of forming a single globally unique name for the service. For example the following 2 sets of attributes actually describe 2 different services (despite the fact that the concatenation would result in the same string):
 

specification/data-semantic-conventions.md

@@ -30,3 +30,5 @@ The following semantic conventions for spans are defined:
 * [Database](data-database.md): Spans for SQL and NoSQL client calls.
 * [RPC/RMI](data-rpc.md): Spans for remote procedure calls (e.g., gRPC).
 * [General](data-span-general.md): General semantic attributes that may be used in describing different kinds of operations.
+* [Messaging](data-async-messaging.md): Spans for asynchronous messaging systems.
+* [Event](data-events.md): Attributes for events.

specification/data-span-general.md

@@ -9,6 +9,7 @@ Particular operations may refer to or require some of these attributes.
 <!-- toc -->
 
 - [General network connection attributes](#general-network-connection-attributes)
+- [General identity attributes](#general-identity-attributes)
 
 <!-- tocstop -->
 
@@ -65,3 +66,20 @@ It will usually not make sense to use reverse-lookup to obtain `net.host.name`,
 If `net.transport` is `"unix"` or `"pipe"`, the absolute path to the file representing it should be used as `net.peer.name` (`net.host.name` doesn't make sense in that context).
 If there is no such file (e.g., anonymous pipe),
 the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation.
+
+## General identity attributes
+
+These attributes may be used for any operation with an authenticated and/or authorized enduser.
+
+|  Attribute name |                                 Notes and examples                                |
+| :-------------- | :-------------------------------------------------------------------------------- |
+| `auth.user`     | Username or client_id extracted from the access token or [Authorization] header.  |
+| `auth.role`     | Actual/assumed role the client is making the request under extracted from token or application security context. |
+| `auth.scope`    | Scopes or granted authorities the client currently possesses extracted from token or application security context. |
+
+[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2
+
+Given the sensitive nature of this information, SDKs and exporters may want to provide configurable
+functionality to drop these attributes for use cases where the information is not needed or would violate
+policies or regulations.
+