From 2227510be6952393755813bf5108c268a9838b8e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 13 Jun 2024 13:05:58 -0700 Subject: [PATCH 1/6] Update kafka spring example to align with main spec --- docs/messaging/kafka.md | 75 +++++++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index cb477b56d2..e1c87668c0 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 to offset. + +Frameworks such as Quarkus and Spring Boot provide integrations with Kafka which allow to +configure processing callbacks, so corresponding instrumentations can create "Process" +spans in addition to "Receive" spans created by Kafka instrumentations for polling calls. + +```mermaid +flowchart LR; + subgraph PRODUCER + P[Span Send T] + end + subgraph CONSUMER + direction TB + R1[Span Poll T] + R2[Span Process T] + R3[Span Commit T] + 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` | +| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit | +|-|-|-|-|-| +| Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | +| Parent | | | (optional) Span Publish | Span Process | +| Links | | Span Publish | Span Publish | | +| SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | | 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"` | +| `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | +| `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | +| `messaging.operation.name` | `send` | `poll` | `"process"` | `commit` | +| `messaging.operation.type` | `"publish"` | `"receive"` | `"process"` | `"settle"` | +| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | `"8"` | +| `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | | +| `messaging.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | +| `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | +| `messaging.kafka.message.offset` | | `"12"` | `"12"` | `"12"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 09be6376accbfcc3d47cbeaf6f7013fb39d728a3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 13 Jun 2024 13:23:38 -0700 Subject: [PATCH 2/6] changelog --- .chloggen/1155.yaml | 4 ++++ docs/messaging/kafka.md | 4 ++-- 2 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 .chloggen/1155.yaml diff --git a/.chloggen/1155.yaml b/.chloggen/1155.yaml new file mode 100644 index 0000000000..00c5cac4af --- /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 e1c87668c0..1b41d27ea8 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -173,12 +173,12 @@ flowchart LR; | Parent | | | (optional) Span Publish | Span Process | | Links | | Span Publish | Span Publish | | | SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | `Ok` | +| Status | `Ok` | `Ok` | `Ok` | `Ok` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | | `messaging.operation.name` | `send` | `poll` | `"process"` | `commit` | | `messaging.operation.type` | `"publish"` | `"receive"` | `"process"` | `"settle"` | -| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | `"8"` | +| `messaging.client.id` | `"5"` | `"8"` | `"8"` | `"8"` | | `messaging.kafka.message.key` | `"myKey"` | `"myKey"` | `"myKey"` | | | `messaging.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | | `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | From 0948d80f0dee50008a7b9c9fd4713f2d26d71008 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 13 Jun 2024 13:42:14 -0700 Subject: [PATCH 3/6] up --- docs/messaging/kafka.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 1b41d27ea8..943851c27a 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -139,10 +139,10 @@ If an intermediary broker is present, `service.name` and `peer.service` will not ### Apache Kafka with Quarkus or Spring Boot Example In this example, the producer publishes a message to a topic T on Apache Kafka. -Consumer receives the message, processes it and commits to offset. +Consumer receives the message, processes it and commits the offset. -Frameworks such as Quarkus and Spring Boot provide integrations with Kafka which allow to -configure processing callbacks, so corresponding instrumentations can create "Process" +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 From a4f7ca7725b3549d0433f9e2a461b404622eede0 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 19 Jun 2024 20:13:23 -0700 Subject: [PATCH 4/6] review --- docs/messaging/kafka.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 943851c27a..22f09bd4a0 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -148,13 +148,13 @@ spans in addition to "Receive" spans created by Kafka instrumentations for polli ```mermaid flowchart LR; subgraph PRODUCER - P[Span Send T] + P[Span 'send T'] end subgraph CONSUMER direction TB - R1[Span Poll T] - R2[Span Process T] - R3[Span Commit T] + R1[Span 'poll T'] + R2[Span 'process T'] + R3[Span 'commit T'] end P-. link .-R1; @@ -167,16 +167,16 @@ flowchart LR; linkStyle 1 color:green,stroke:green ``` -| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit | +| Field or Attribute | Span `"send T"` | Span `"poll T"` | Span `"process T"` | Span `"commit T"` | |-|-|-|-|-| | Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | -| Parent | | | (optional) Span Publish | Span Process | -| Links | | Span Publish | Span Publish | | +| Parent | | | (optional) `"send T"` | `"process T"` | +| Links | | `"send T"` | `"send T"` | | | SpanKind | `PRODUCER` | `CONSUMER` | `SERVER` | `CLIENT` | -| Status | `Ok` | `Ok` | `Ok` | `Ok` | +| Status | `UNSET` | `UNSET` | `UNSET` | `UNSET` | | `messaging.system` | `"kafka"` | `"kafka"` | `"kafka"` | `"kafka"` | | `messaging.destination.name` | `"T"` | `"T"` | `"T"` | `"T"` | -| `messaging.operation.name` | `send` | `poll` | `"process"` | `commit` | +| `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"` | | From 049ec3d84dbab261cb69ff443e78841cfdfa11dd Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 19 Jun 2024 20:15:44 -0700 Subject: [PATCH 5/6] up --- .chloggen/1155.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/1155.yaml b/.chloggen/1155.yaml index 00c5cac4af..4b71d69ec3 100644 --- a/.chloggen/1155.yaml +++ b/.chloggen/1155.yaml @@ -1,4 +1,4 @@ change_type: bug_fix component: messaging -note: Update kafka Spring example to align with the messaging spec +note: Update Kafka Spring example to align with the messaging spec issues: [ 1155 ] From e8ea1fb25abf57856a4b51f951d82007615681e5 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 20 Jun 2024 10:51:56 -0700 Subject: [PATCH 6/6] review --- docs/messaging/kafka.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/messaging/kafka.md b/docs/messaging/kafka.md index 22f09bd4a0..14b01a072d 100644 --- a/docs/messaging/kafka.md +++ b/docs/messaging/kafka.md @@ -148,13 +148,13 @@ spans in addition to "Receive" spans created by Kafka instrumentations for polli ```mermaid flowchart LR; subgraph PRODUCER - P[Span 'send T'] + P[Span Send] end subgraph CONSUMER direction TB - R1[Span 'poll T'] - R2[Span 'process T'] - R3[Span 'commit T'] + R1[Span Poll] + R2[Span Process] + R3[Span Commit] end P-. link .-R1; @@ -167,21 +167,21 @@ flowchart LR; linkStyle 1 color:green,stroke:green ``` -| Field or Attribute | Span `"send T"` | Span `"poll T"` | Span `"process T"` | Span `"commit T"` | +| Field or Attribute | Span Send | Span Poll | Span Process | Span Commit T | |-|-|-|-|-| | Span name | `"send T"` | `"poll T"` | `"process T"` | `"commit T"` | -| Parent | | | (optional) `"send T"` | `"process T"` | -| Links | | `"send T"` | `"send 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.destination.consumer.group` | | `"my-group"` | `"my-group"` | `"my-group"` | -| `messaging.destination.partition.id` | `"1"` | `"1"` | `"1"` | `"1"` | | `messaging.kafka.message.offset` | | `"12"` | `"12"` | `"12"` | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status