diff --git a/.chloggen/1155.yaml b/.chloggen/1155.yaml new file mode 100644 index 0000000000..4b71d69ec3 --- /dev/null +++ b/.chloggen/1155.yaml @@ -0,0 +1,4 @@ +change_type: bug_fix +component: messaging +note: Update Kafka Spring example to align with the messaging spec +issues: [ 1155 ] diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index cb477b56d2..14b01a072d 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -138,41 +138,50 @@ If an intermediary broker is present, `service.name` and `peer.service` will not ### Apache Kafka with Quarkus or Spring Boot Example -Given is a process P, that publishes a message to a topic T1 on Apache Kafka. -One process, CA, receives the message and publishes a new message to a topic T2 that is then received and processed by CB. - -Frameworks such as Quarkus and Spring Boot separate processing of a received message from producing subsequent messages out. -For this reason, receiving (Span Rcv1) is the parent of both processing (Span Proc1) and producing a new message (Span Prod2). -The span representing message receiving (Span Rcv1) should set `messaging.operation.type` to `process`, -as it does not only receive the message but also converts the input message to something suitable for the processing operation to consume and creates the output message from the result of processing. - -``` -Process P: | Span Prod1 | --- -Process CA: | Span Rcv1 | - | Span Proc1 | - | Span Prod2 | --- -Process CB: | Span Rcv2 | +In this example, the producer publishes a message to a topic T on Apache Kafka. +Consumer receives the message, processes it and commits the offset. + +Frameworks such as Quarkus and Spring Boot provide integrations with Kafka allowing to +configure and instrument processing callbacks, so corresponding instrumentations should create "Process" +spans in addition to "Receive" spans created by Kafka instrumentations for polling calls. + +```mermaid +flowchart LR; + subgraph PRODUCER + P[Span Send] + end + subgraph CONSUMER + direction TB + R1[Span Poll] + R2[Span Process] + R3[Span Commit] + end + + P-. link .-R1; + P-. link .-R2; + R2-- parent ---R3; + + classDef normal fill:green + class P,R1,R2,R3 normal + linkStyle 0 color:green,stroke:green + linkStyle 1 color:green,stroke:green ``` -| Field or Attribute | Span Prod1 | Span Rcv1 | Span Proc1 | Span Prod2 | Span Rcv2 | -|-|-|-|-|-|-| -| Span name | `"send T1"` | `"send T1"` | `"process T1"` | `"send T2"` | `"poll T2`" | -| Parent | | Span Prod1 | Span Rcv1 | Span Rcv1 | Span Prod2 | -| Links | | | | | | -| SpanKind | `PRODUCER` | `CONSUMER` | `CONSUMER` | `PRODUCER` | `CONSUMER` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | -| `peer.service` | `"myKafka"` | | | `"myKafka"` | | -| `service.name` | | `"myConsumer1"` | `"myConsumer1"` | | `"myConsumer2"` | -| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | -| `messaging.destination.name` | `"T1"` | `"T1"` | `"T1"` | `"T2"` | `"T2"` | -| `messaging.operation.name` | `send` | `send` | `"process"` | `send` | `"poll"` | -| `messaging.operation.type` | `publish` | `publish` | `"process"` | `publish` | `"receive"` | -| `messaging.client.id` | | `"5"` | `"5"` | `"5"` | `"8"` | -| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | `"anotherKey"` | `"anotherKey"` | -| `messaging.kafka.consumer.group` | | `"my-group"` | `"my-group"` | | `"another-group"` | -| `messaging.kafka.destination.partition` | `"1"` | `"1"` | `"1"` | `"3"` | `"3"` | -| `messaging.kafka.message.offset` | `"12"` | `"12"` | `"12"` | `"32"` | `"32"` | +| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit T | +|-|-|-|-|-| +| Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | +| Parent | | | (optional) Span Send | Span Process | +| Links | | Span Send | Span Send | | +| SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | +| Status | `UNSET` | `UNSET` | `UNSET` | `UNSET` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | +| `messaging.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | +| `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | +| `messaging.operation.name` | `"send"` | `"poll"` | `"process"` | `"commit"` | +| `messaging.operation.type` | `"publish"` | `"receive"` | `"process"` | `"settle"` | +| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | +| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | | +| `messaging.kafka.message.offset` | | `"12"` | `"12"` | `"12"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status