Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Asynchronous messaging span attributes #395

Closed
wants to merge 2 commits into from
Closed

Asynchronous messaging span attributes #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4800dab
initial def of attributes for asychronous messaging spans
kbrockhoff Dec 17, 2019
cefc55b
Merge remote-tracking branch 'upstream/master' into async-msg-sem-con…
kbrockhoff Dec 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions specification/data-async-messaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like message_bus could be shortened to message.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, what is a message bus? In my understanding there are message queues (anycast) and topics (broadcast). A bus sounds like something used to implement a topic.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This lingo comes over from OpenTracing: https://github.com/opentracing/specification/blob/master/semantic_conventions.md#message-bus

I'm fine with calling it message though one could argue that is too vague.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this really required?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the removal of the 'component' attribute, having at least one required attribute facilitates branching logic. I don't know of any use case where this value won't exist. It could be argued though that this would be used as the name of the span in most cases.

| `message_bus.type` | The brand of message bus or client API library such as `"kafka"`, `"rabbitmq"` or `"jms"`. | Yes |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be name? Type does not sound like what the description suggests.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I followed the same conventions as the database spec which uses db.type

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think type in the db conventions refers more to the flavor of db like sql instead of a specific sql database. For instance mysql, postgresql, ms sql server, and sqlite may all have type = sql

| `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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry not to much experience here, but who is the user in this case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the username the client uses to authenticate with the message bus instance. In other words, 'message_bus.user' is the equivalent of 'db.user'

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why it is not peer.user I feel like we have too many users, and may better to standardize as peer or other category and use that everywhere.

| `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
1 change: 1 addition & 0 deletions specification/data-semantic-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,4 @@ 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.