Add Instana Propagator: Instana Propagator Extension

src/Extension/Propagator/Instana/InstanaMultiPropagator.php

@@ -0,0 +1,175 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Extension\Propagator\Instana;
+
+use OpenTelemetry\API\Trace\NonRecordingSpan;
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\SpanContext;
+use OpenTelemetry\API\Trace\SpanContextInterface;
+use OpenTelemetry\API\Trace\SpanContextValidator;
+use OpenTelemetry\API\Trace\TraceFlags;
+use OpenTelemetry\Context\Context;
+use OpenTelemetry\Context\ContextInterface;
+use OpenTelemetry\Context\Propagation\ArrayAccessGetterSetter;
+use OpenTelemetry\Context\Propagation\PropagationGetterInterface;
+use OpenTelemetry\Context\Propagation\PropagationSetterInterface;
+use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
+
+/**
+ * InstanaPropagator is a propagator that supports the specification for multiple
+ * "instana" http headers used for trace context propagation across service
+ * boundaries.
+ */
+final class InstanaMultiPropagator implements TextMapPropagatorInterface
+{
+    /**
+     * The  X-INSTANA-T header is required and is encoded as 32 lower-hex characters.
+     * For example, a 128-bit TraceId header might look like: X-Instana-T: 463ac35c9f6413ad48485a3953bb6124 .
+     *
+     */
+    private const INSTANA_TRACE_ID_HEADER = 'X-INSTANA-T';
+
+    /**
+     * The X-Instana-S header must be present on a child span and absent on the root span.
+     * It is encoded as 16 lower-hex characters.
+     * For example, a ParentSpanId header might look like: X-Instana-S: 0020000000000001
+     *
+     */
+    private const INSTANA_SPAN_ID_HEADER = 'X-INSTANA-S';
+
+    /**
+     * An accept sampling decision is encoded as X-INSTANA-L: 1 and a deny as X-INSTANA-L: 0.
+     * Absent means defer the decision to the receiver of this header.
+     * For example, a Sampled header might look like: X-Instana-L: 1
+     *
+     */
+    private const INSTANA_LEVEL_HEADER = 'X-INSTANA-L';
+
+    private const IS_SAMPLED = '1';
+    private const VALID_SAMPLED = [self::IS_SAMPLED, 'true'];
+    private const IS_NOT_SAMPLED = '0';
+    private const VALID_NON_SAMPLED = [self::IS_NOT_SAMPLED, 'false'];
+
+    private const FIELDS = [
+        self::INSTANA_TRACE_ID_HEADER,
+        self::INSTANA_SPAN_ID_HEADER,
+        self::INSTANA_LEVEL_HEADER,
+    ];
+
+    private static ?self $instance = null;
+
+    public static function getInstance(): self
+    {
+        if (null === self::$instance) {
+            self::$instance = new self();
+        }
+
+        return self::$instance;
+    }
+
+    /** {@inheritdoc} */
+    public function fields(): array
+    {
+        return self::FIELDS;
+    }
+
+    /** {@inheritdoc} */
+    public function inject(&$carrier, ?PropagationSetterInterface $setter = null, ?ContextInterface $context = null): void
+    {
+        $setter ??= ArrayAccessGetterSetter::getInstance();
+        $context ??= Context::getCurrent();
+        $spanContext = Span::fromContext($context)->getContext();
+
+        if (!$spanContext->isValid()) {
+            return;
+        }
+
+        // Inject multiple Instana headers
+        $setter->set($carrier, self::INSTANA_TRACE_ID_HEADER, $spanContext->getTraceId());
+        $setter->set($carrier, self::INSTANA_SPAN_ID_HEADER, $spanContext->getSpanId());
+        $setter->set($carrier, self::INSTANA_LEVEL_HEADER, $spanContext->isSampled() ? self::IS_SAMPLED : self::IS_NOT_SAMPLED);
+    }
+
+    public function extract($carrier, ?PropagationGetterInterface $getter = null, ?ContextInterface $context = null): ContextInterface
+    {
+        $getter ??= ArrayAccessGetterSetter::getInstance();
+        $context ??= Context::getCurrent();
+
+        $traceId = self::readHeader($carrier, $getter, self::INSTANA_TRACE_ID_HEADER);
+        $spanId = self::readHeader($carrier, $getter, self::INSTANA_SPAN_ID_HEADER);
+        $level = self::getSampledValue($carrier, $getter);
+
+        $spanContext = self::extractImpl($carrier, $getter);
+
+        if (($traceId === '' &&  $spanId === '') && $level !== null) {
+            return (new NonRecordingSpan($spanContext))
+                ->storeInContext($context);
+
+        } elseif (!$spanContext->isValid()) {
+            return $context;
+        }
+
+        return $context->withContextValue(Span::wrap($spanContext));
+
+    }
+
+    private static function readHeader($carrier, PropagationGetterInterface $getter, string $key): string
+    {
+        // By convention, X-INSTANA-* headers are sent all-upper-case. For http and http/2, Node.js normalizes all headers to
+        // all-lower-case, that's why we first read via the lower case variant of the header name. For other protocols, no
+        // such normalization happens, so we also need to read via the original all-upper-case variant.
+        $header = $getter->get($carrier, strtolower($key)) ?: $getter->get($carrier, $key);
+
+        // Return the header or an empty string if not found
+        return $header ?: '';
+    }
+    private static function getSampledValue($carrier, PropagationGetterInterface $getter): ?int
+    {
+        $value = $getter->get($carrier, self::INSTANA_LEVEL_HEADER);
+
+        if ($value === null) {
+            return null;
+        }
+
+        if (in_array(strtolower($value), self::VALID_SAMPLED)) {
+            return (int) self::IS_SAMPLED;
+        }
+        if (in_array(strtolower($value), self::VALID_NON_SAMPLED)) {
+            return (int) self::IS_NOT_SAMPLED;
+        }
+
+        return null;
+    }
+
+    private static function extractImpl($carrier, PropagationGetterInterface $getter): SpanContextInterface
+    {
+        $traceId = self::readHeader($carrier, $getter, self::INSTANA_TRACE_ID_HEADER);
+        $spanId = self::readHeader($carrier, $getter, self::INSTANA_SPAN_ID_HEADER);
+        $level = self::getSampledValue($carrier, $getter);
+
+        if ($traceId && strlen($traceId) < 32) {
+            $traceId = str_pad($traceId, 32, '0', STR_PAD_LEFT);
+        }
+
+        if ($spanId && strlen($spanId) < 16) {
+            $spanId =  str_pad($spanId, 16, '0', STR_PAD_LEFT);
+        }
+
+        if ((SpanContextValidator::isValidTraceId($traceId) || SpanContextValidator::isValidSpanId($spanId))) {
+            return SpanContext::createFromRemoteParent(
+                $traceId,
+                $spanId,
+                $level ? TraceFlags::SAMPLED : TraceFlags::DEFAULT
+            );
+        }
+
+        return SpanContext::createFromRemoteParent(
+            SpanContextValidator::INVALID_TRACE,
+            SpanContextValidator::INVALID_SPAN,
+            $level ? TraceFlags::SAMPLED : TraceFlags::DEFAULT
+        );
+
+    }
+}

src/Extension/Propagator/Instana/README.md

@@ -0,0 +1,60 @@
+OpenTelemetry Instana Propagator
+
+[![NPM Published Version][npm-img]][npm-url]
+[![Apache License][license-image]][license-image]
+
+
+The OpenTelemetry Propagator for Instana provides HTTP header propagation for systems that are using IBM Observability by Instana.
+This propagator translates the Instana trace correlation headers (`X-INSTANA-T/X-INSTANA-S/X-INSTANA-L`) into the OpenTelemetry `SpanContext`, and vice versa.
+It does not handle `TraceState`.
+
+
+## Installation
+
+```sh
+composer require @instana/opentelemetry-php-propagator-instana
+```
+
+## Usage
+
+
+
+## Propagator Details
+
+There are three headers that the propagator handles: `X-INSTANA-T` (the trace ID), `X-INSTANA-S` (the parent span ID), and `X-INSTANA-L` (the sampling level).
+
+Example header triplet:
+
+* `X-INSTANA-T: 80f198ee56343ba864fe8b2a57d3eff7`,
+* `X-INSTANA-S: e457b5a2e4d86bd1`,
+* `X-INSTANA-L: 1`.
+
+A short summary for each of the headers is provided below. More details are available at <https://www.ibm.com/docs/en/obi/current?topic=monitoring-traces#tracing-headers>.
+
+### X-INSTANA-T -- trace ID
+
+* A string of either 16 or 32 characters from the alphabet `0-9a-f`, representing either a 64 bit or 128 bit ID.
+* This header corresponds to the [OpenTelemetry TraceId](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext).
+* If the propagator receives an X-INSTANA-T header value that is shorter than 32 characters when _extracting_ headers into the OpenTelemetry span context, it will left-pad the string with the character "0" to length 32.
+* No length transformation is applied when _injecting_ the span context into headers.
+
+### X-INSTANA-S -- parent span ID
+
+* Format: A string of 16 characters from the alphabet `0-9a-f`, representing a 64 bit ID.
+* This header corresponds to the [OpenTelemetry SpanId](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext).
+
+### X-INSTANA-L - sampling level
+
+* The only two valid values are `1` and `0`.
+* A level of `1` means that this request is to be sampled, a level of `0` means that the request should not be sampled.
+* This header corresponds to the sampling bit of the [OpenTelemetry TraceFlags](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#spancontext).
+
+## Useful links
+
+* For more information on Instana, visit <https://www.instana.com/> and [Instana' documentation](https://www.ibm.com/docs/en/obi/current).
+* For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+
+
+## License
+
+Apache 2.0 - See [LICENSE][license-url] for more information.

src/Extension/Propagator/Instana/_register.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+use OpenTelemetry\Extension\Propagator\Instana\InstanaMultiPropagator;
+use OpenTelemetry\SDK\Registry;
+
+if (!class_exists(Registry::class)) {
+    return;
+}
+Registry::registerTextMapPropagator(
+    'instana',
+    InstanaMultiPropagator::getInstance()
+);

src/Extension/Propagator/Instana/composer.json

@@ -0,0 +1,37 @@
+{
+    "name": "instana/opentelemetry-php-propagator-instana",
+    "description": "Instana propagator extension for OpenTelemetry PHP.",
+    "keywords": ["opentelemetry", "otel", "tracing", "apm", "extension", "propagator", "instana"],
+    "type": "library",
+    "support": {
+        "issues": "https://github.com/open-telemetry/opentelemetry-php/issues",
+        "source": "https://github.com/open-telemetry/opentelemetry-php",
+        "docs": "https://opentelemetry.io/docs/php",
+        "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V"
+    },
+    "license": "Apache-2.0",
+    "authors": [
+        {
+            "name": "opentelemetry-php contributors",
+            "homepage": "https://github.com/open-telemetry/opentelemetry-php/graphs/contributors"
+        }
+    ],
+    "require": {
+        "php": "^8.1",
+        "open-telemetry/api": "^1.0",
+        "open-telemetry/context": "^1.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "OpenTelemetry\\Extension\\Propagator\\Instana\\": "."
+        },
+        "files": [
+            "_register.php"
+        ]
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-main": "1.0.x-dev"
+        }
+    }
+}