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

@@ -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,
+    ) {
+    }
+}

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 = [],
+    ) {
+    }
+}

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);
+    }
+}

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);
+    }
+}