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.

Author: brettmc

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

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