From bee9c64ae90f5a1714585473188a3ec224aa3f22 Mon Sep 17 00:00:00 2001
From: Brett McBride <brett.a.mcbride@gmail.com>
Date: Sat, 31 Aug 2024 09:17:53 +1000
Subject: [PATCH] adding auto-instrumentation attribute to API (#1371)

adding WithSpan and SpanAttribute attributes to the API. These attributes
are used by an upcoming feature in auto-instrumentation which allows users
to add attributes to their code to enable auto-instrumentation.
---
 src/API/Instrumentation/SpanAttribute.php     | 24 ++++++++++++++++
 src/API/Instrumentation/WithSpan.php          | 28 +++++++++++++++++++
 .../API/Instrumentation/SpanAttributeTest.php | 19 +++++++++++++
 .../Unit/API/Instrumentation/WithSpanTest.php | 22 +++++++++++++++
 4 files changed, 93 insertions(+)
 create mode 100644 src/API/Instrumentation/SpanAttribute.php
 create mode 100644 src/API/Instrumentation/WithSpan.php
 create mode 100644 tests/Unit/API/Instrumentation/SpanAttributeTest.php
 create mode 100644 tests/Unit/API/Instrumentation/WithSpanTest.php

diff --git a/src/API/Instrumentation/SpanAttribute.php b/src/API/Instrumentation/SpanAttribute.php
new file mode 100644
index 000000000..b2dcd1ef8
--- /dev/null
+++ b/src/API/Instrumentation/SpanAttribute.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Instrumentation;
+
+use Attribute;
+
+/**
+ * For function and methods that have the {@link WithSpan}
+ * attribute, adding this attribute to an argument will
+ * add the argument as a span attribute.
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+final class SpanAttribute
+{
+    /**
+     * @param string|null $name Optional name to use for the attribute. Default: argument name.
+     */
+    public function __construct(
+        public readonly ?string $name = null,
+    ) {
+    }
+}
diff --git a/src/API/Instrumentation/WithSpan.php b/src/API/Instrumentation/WithSpan.php
new file mode 100644
index 000000000..4fa3ad7b4
--- /dev/null
+++ b/src/API/Instrumentation/WithSpan.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\API\Instrumentation;
+
+use Attribute;
+use OpenTelemetry\API\Trace\SpanKind; //@phan-suppress-current-line PhanUnreferencedUseNormal
+
+/**
+ * Functions and methods with this attribute will be auto-instrumented
+ * by the OpenTelemetry extension.
+ */
+#[Attribute(Attribute::TARGET_FUNCTION|Attribute::TARGET_METHOD)]
+final class WithSpan
+{
+    /**
+     * @param string|null $span_name Optional span name. Default: function name or class::method
+     * @param int|null $span_kind Optional {@link SpanKind}. Default: {@link SpanKind::KIND_INTERNAL}
+     * @param array $attributes Optional attributes to be added to the span.
+     */
+    public function __construct(
+        public readonly ?string $span_name = null,
+        public readonly ?int $span_kind = null,
+        public readonly array $attributes = [],
+    ) {
+    }
+}
diff --git a/tests/Unit/API/Instrumentation/SpanAttributeTest.php b/tests/Unit/API/Instrumentation/SpanAttributeTest.php
new file mode 100644
index 000000000..d6437aa82
--- /dev/null
+++ b/tests/Unit/API/Instrumentation/SpanAttributeTest.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Tests\Unit\API\Instrumentation;
+
+use OpenTelemetry\API\Instrumentation\SpanAttribute;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(SpanAttribute::class)]
+class SpanAttributeTest extends TestCase
+{
+    public function test_with_span(): void
+    {
+        $attr = new SpanAttribute('foo');
+        $this->assertSame('foo', $attr->name);
+    }
+}
diff --git a/tests/Unit/API/Instrumentation/WithSpanTest.php b/tests/Unit/API/Instrumentation/WithSpanTest.php
new file mode 100644
index 000000000..9dfd1824f
--- /dev/null
+++ b/tests/Unit/API/Instrumentation/WithSpanTest.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Tests\Unit\API\Instrumentation;
+
+use OpenTelemetry\API\Instrumentation\WithSpan;
+use OpenTelemetry\API\Trace\SpanKind;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(WithSpan::class)]
+class WithSpanTest extends TestCase
+{
+    public function test_with_span(): void
+    {
+        $attr = new WithSpan('foo', SpanKind::KIND_PRODUCER, ['foo' => 'bar']);
+        $this->assertSame('foo', $attr->span_name);
+        $this->assertSame(SpanKind::KIND_PRODUCER, $attr->span_kind);
+        $this->assertSame(['foo' => 'bar'], $attr->attributes);
+    }
+}