chore: document message link strategy

worldia · Sep 1, 2022 · 7cfad9c · 7cfad9c
1 parent 17baa81
commit 7cfad9c
Show file tree

Hide file tree

Showing 6 changed files with 27 additions and 11 deletions.
diff --git a/docs/tracing/link-strategy-for-message.md b/docs/tracing/link-strategy-for-message.md
@@ -0,0 +1,13 @@
+# Link strategy for a message
+
+```php
+use Instrumentation\Tracing\Propagation\Messenger\PropagationStrategyStamp;
+
+$message = new MyMessage();
+
+// Message processing will be recorded as a child span (default)
+$messageBus->dispatch($message, [new PropagationStrategyStamp(PropagationStrategyStamp::STRATEGY_PARENT)]);    
+
+// Message processing will be recorded as a new root span, and a link to the parent span will be set
+$messageBus->dispatch($message, [new PropagationStrategyStamp(PropagationStrategyStamp::STRATEGY_LINK)]);    
+```
diff --git a/readme.md b/readme.md
@@ -58,6 +58,7 @@ instrumentation:
     - [Add Urls to your traces in error messages](./docs/tracing/add-urls-to-your-traces.md)
     - [Use upstream request id as trace id](./docs/tracing/upstream-request-id.md)
     - [Customize operation (span) name for a message](./docs/tracing/custom-operation-name-for-message.md)
+    - [Link strategy for a message](./docs/tracing/link-strategy-for-message.md)    
     - [Propagating trace/baggage context in HTTP requests](./docs/tracing/propagating-context.md)
 - **Metrics**
     - [Adding a metric](./docs/metrics/adding-a-metric.md)

diff --git a/spec/Tracing/Instrumentation/EventSubscriber/MessageEventSubscriberSpec.php b/spec/Tracing/Instrumentation/EventSubscriber/MessageEventSubscriberSpec.php
@@ -45,6 +45,8 @@ public function let(
         $tracer->spanBuilder(Argument::type('string'))->willReturn($spanBuilder);
         $spanBuilder->setSpanKind(Argument::type('int'))->willReturn($spanBuilder);
         $spanBuilder->setAttributes(Argument::type('iterable'))->willReturn($spanBuilder);
+        $spanBuilder->addLink(Argument::cetera())->willReturn($spanBuilder);
+        $spanBuilder->setNoParent()->willReturn($spanBuilder);
         $spanBuilder->startSpan()->willReturn($span);
         $span->activate()->willReturn($scope);
         $span->recordException(Argument::cetera())->willReturn($span);

diff --git a/...mentation/Messenger/StrategyStampSpec.php → ...essenger/PropagationStrategyStampSpec.php b/...mentation/Messenger/StrategyStampSpec.php → ...essenger/PropagationStrategyStampSpec.php
@@ -5,17 +5,17 @@
  * (c) Worldia <developers@worldia.com>
  */
 
-namespace spec\Instrumentation\Tracing\Instrumentation\Messenger;
+namespace spec\Instrumentation\Tracing\Propagation\Messenger;
 
-use Instrumentation\Tracing\Instrumentation\Messenger\StrategyStamp;
+use Instrumentation\Tracing\Propagation\Messenger\PropagationStrategyStamp;
 use PhpSpec\ObjectBehavior;
 use Symfony\Component\Messenger\Stamp\StampInterface;
 
-class StrategyStampSpec extends ObjectBehavior
+class PropagationStrategyStampSpec extends ObjectBehavior
 {
     public function it_implements_stamp_interface(): void
     {
-        $this->beConstructedWith(StrategyStamp::STRATEGY_LINK);
+        $this->beConstructedWith(PropagationStrategyStamp::STRATEGY_LINK);
         $this->shouldBeAnInstanceOf(StampInterface::class);
     }
 

diff --git a/src/Tracing/Instrumentation/EventSubscriber/MessageEventSubscriber.php b/src/Tracing/Instrumentation/EventSubscriber/MessageEventSubscriber.php
@@ -11,8 +11,8 @@
 use Instrumentation\Tracing\Instrumentation\MainSpanContextInterface;
 use Instrumentation\Tracing\Instrumentation\Messenger\AttributesStamp;
 use Instrumentation\Tracing\Instrumentation\Messenger\OperationNameStamp;
-use Instrumentation\Tracing\Instrumentation\Messenger\StrategyStamp;
 use Instrumentation\Tracing\Instrumentation\TracerAwareTrait;
+use Instrumentation\Tracing\Propagation\Messenger\PropagationStrategyStamp;
 use OpenTelemetry\API\Trace\SpanInterface;
 use OpenTelemetry\API\Trace\SpanKind;
 use OpenTelemetry\API\Trace\StatusCode;
@@ -76,7 +76,7 @@ public function onConsume(WorkerMessageReceivedEvent $event): void
                 ->setSpanKind(SpanKind::KIND_CONSUMER)
                 ->setAttributes($attributes);
 
-            if (StrategyStamp::STRATEGY_LINK === $strategy) {
+            if (PropagationStrategyStamp::STRATEGY_LINK === $strategy) {
                 $linkContext = Span::getCurrent()->getContext();
                 $builder->setNoParent()->addLink($linkContext);
             }
@@ -166,12 +166,12 @@ private function getAttributes(Envelope $envelope): array
 
     private function getStrategy(Envelope $envelope): string
     {
-        /** @var StrategyStamp|null $stamp */
-        $stamp = $envelope->last(StrategyStamp::class);
+        /** @var PropagationStrategyStamp|null $stamp */
+        $stamp = $envelope->last(PropagationStrategyStamp::class);
         if ($stamp) {
             return $stamp->getStrategy();
         }
 
-        return StrategyStamp::STRATEGY_PARENT;
+        return PropagationStrategyStamp::STRATEGY_LINK;
     }
 }
diff --git a/...strumentation/Messenger/StrategyStamp.php → ...on/Messenger/PropagationStrategyStamp.php b/...strumentation/Messenger/StrategyStamp.php → ...on/Messenger/PropagationStrategyStamp.php
@@ -7,11 +7,11 @@
  * (c) Worldia <developers@worldia.com>
  */
 
-namespace Instrumentation\Tracing\Instrumentation\Messenger;
+namespace Instrumentation\Tracing\Propagation\Messenger;
 
 use Symfony\Component\Messenger\Stamp\StampInterface;
 
-final class StrategyStamp implements StampInterface
+final class PropagationStrategyStamp implements StampInterface
 {
     public const STRATEGY_LINK = 'link';
     public const STRATEGY_PARENT = 'parent';