From 02d88d991ed17143780ea52f2ac1614200cc5953 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Thu, 7 Nov 2024 09:14:31 +0100 Subject: [PATCH 01/23] feat: Add tooling to generate stubs for the Public PHP API --- Makefile | 5 + src/ddtrace_php_api.stubs.php | 2305 ++++++++++++++++++++++++++++++ tooling/stubs/composer.json | 10 + tooling/stubs/generate-stubs.php | 26 + 4 files changed, 2346 insertions(+) create mode 100644 src/ddtrace_php_api.stubs.php create mode 100644 tooling/stubs/composer.json create mode 100644 tooling/stubs/generate-stubs.php diff --git a/Makefile b/Makefile index 954f0ef1bb..14f1c40192 100644 --- a/Makefile +++ b/Makefile @@ -512,6 +512,11 @@ generate: @composer -dtooling/generation generate @composer -dtooling/generation verify +# Generates the stubs file for the public API +generate_stubs: + @composer -dtooling/stubs update + @composer -dtooling/stubs generate + # Find all generated core dumps, sorted by date descending cores: find . -path "./*/vendor" -prune -false -o \( -type f -regex ".*\/core\.?[0-9]*" \) -printf "%T@ %Tc %p\n" | sort -n -r diff --git a/src/ddtrace_php_api.stubs.php b/src/ddtrace_php_api.stubs.php new file mode 100644 index 0000000000..d0151b3192 --- /dev/null +++ b/src/ddtrace_php_api.stubs.php @@ -0,0 +1,2305 @@ +getActive()->getSpan(), + * and null will be returned if {@link Scope#active()} is null. + * + * @return Span|null + */ + public function getActiveSpan(); + /** + * Starts a new span that is activated on a scope manager. + * + * It's also possible to not finish the {@see \DDTrace\Contracts\Span} when + * {@see \DDTrace\Contracts\Scope} context expires: + * + * $scope = $tracer->startActiveSpan('...', [ + * 'finish_span_on_close' => false, + * ]); + * $span = $scope->getSpan(); + * try { + * $span->setTag(Tags\HTTP_METHOD, 'GET'); + * // ... + * } finally { + * $scope->close(); + * } + * // $span->finish() is not called as part of Scope deactivation as + * // finish_span_on_close is false + * + * @param string $operationName + * @param array|StartSpanOptions $options Same as for startSpan() with + * aditional option of `finish_span_on_close` that enables finishing + * of span whenever a scope is closed. It is true by default. + * + * @return Scope A Scope that holds newly created Span and is activated on + * a ScopeManager. + */ + public function startActiveSpan($operationName, $options = []); + /** + * Starts and returns a new span representing a unit of work. + * + * Whenever `child_of` reference is not passed then + * {@see \DDTrace\Contracts\ScopeManager::getActive()} span is used as `child_of` + * reference. In order to ignore implicit parent span pass in + * `ignore_active_span` option set to true. + * + * Starting a span with explicit parent: + * + * $tracer->startSpan('...', [ + * 'child_of' => $parentSpan, + * ]); + * + * @see \DDTrace\StartSpanOptions + * + * @param string $operationName + * @param array|StartSpanOptions $options See StartSpanOptions for + * available options. + * + * @return Span + * + * @throws InvalidSpanOption for invalid option + * @throws InvalidReferencesSet for invalid references set + */ + public function startSpan($operationName, $options = []); + /** + * @param SpanContext $spanContext + * @param string $format + * @param mixed $carrier + * + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier); + /** + * @param string $format + * @param mixed $carrier + * @return SpanContext|null + * + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation + */ + public function extract($format, $carrier); + /** + * Allow tracer to send span data to be instrumented. + * + * This method might not be needed depending on the tracing implementation + * but one should make sure this method is called after the request is delivered + * to the client. + * + * As an implementor, a good idea would be to use {@see register_shutdown_function} + * or {@see fastcgi_finish_request} in order to not to delay the end of the request + * to the client. + */ + public function flush(); + /** + * @param mixed $prioritySampling + */ + public function setPrioritySampling($prioritySampling); + /** + * @return int|null + */ + public function getPrioritySampling(); + /** + * This behaves just like Tracer::startActiveSpan(), but it saves the Scope instance + * on the tracer to be accessed later by Tracer::getRootScope(). + * + * @param string $operationName + * @param array $options + * @return Scope + */ + public function startRootSpan($operationName, $options = []); + /** + * @return Scope|null + */ + public function getRootScope(); + /** + * Returns the root span or null and never throws an exception. + * + * @return Span|null + */ + public function getSafeRootSpan(); + /** + * Returns the entire trace encoded as a plain-old PHP array. + * + * @return array + */ + public function getTracesAsArray(); + /** + * Returns the count of currently stored traces + * + * @return int + */ + public function getTracesCount(); +} +namespace DDTrace\Log; + +trait LoggingTrait +{ + /** + * Emits a log message at debug level. + * + * @param string $message + * @param array $context + */ + protected static function logDebug($message, array $context = []) + { + } + /** + * Emits a log message at warning level. + * + * @param string $message + * @param array $context + */ + protected static function logWarning($message, array $context = []) + { + } + /** + * Emits a log message at error level. + * + * @param string $message + * @param array $context + */ + protected static function logError($message, array $context = []) + { + } + /** + * @return bool + */ + protected static function isLogDebugActive() + { + } +} +namespace DDTrace; + +final class Tracer implements \DDTrace\Contracts\Tracer +{ + use \DDTrace\Log\LoggingTrait; + /** + * @param Transport $transport + * @param Propagator[] $propagators + * @param array $config + */ + public function __construct(\DDTrace\Transport $transport = null, array $propagators = null, array $config = []) + { + } + public function limited() + { + } + /** + * Resets this tracer to its original state. + */ + public function reset() + { + } + /** + * @return Tracer + */ + public static function noop() + { + } + /** + * {@inheritdoc} + */ + public function startSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function startRootSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function getRootScope() + { + } + /** + * {@inheritdoc} + */ + public function startActiveSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier) + { + } + /** + * {@inheritdoc} + */ + public function extract($format, $carrier) + { + } + /** + * @return void + */ + public function flush() + { + } + /** + * {@inheritdoc} + */ + public function getScopeManager() + { + } + /** + * @return null|Span + */ + public function getActiveSpan() + { + } + /** + * {@inheritdoc} + */ + public function getTracesAsArray() + { + } + public function addUrlAsResourceNameToSpan(\DDTrace\Contracts\Span $span) + { + } + /** + * @param mixed $prioritySampling + */ + public function setPrioritySampling($prioritySampling) + { + } + /** + * {@inheritdoc} + */ + public function getPrioritySampling() + { + } + /** + * Returns the root span or null and never throws an exception. + * + * @return SpanInterface|null + */ + public function getSafeRootSpan() + { + } + /** + * @return string + */ + public static function version() + { + } + /** + * {@inheritdoc} + */ + public function getTracesCount() + { + } +} +/** + * Although DataDog uses nanotime to report spans PHP does not support nanotime + * plus, nanotime is a uint64 which is not supported either. Microtime will be used + * and there will be transformations in reporting in order to send nanotime. + */ +class Time +{ + /** + * @return int + */ + public static function now() + { + } + /** + * @return int + */ + public static function fromMicrotime($microtime) + { + } + /** + * @param mixed $time + * @return bool + */ + public static function isValid($time) + { + } +} +interface Transport +{ + /** + * @param TracerInterface $tracer + */ + public function send(\DDTrace\Contracts\Tracer $tracer); + /** + * @param string $key + * @param string $value + * @return void + */ + public function setHeader($key, $value); +} +namespace DDTrace\Transport; + +final class Internal implements \DDTrace\Transport +{ + public function send(\DDTrace\Contracts\Tracer $tracer) + { + } + public function setHeader($key, $value) + { + } +} +namespace DDTrace\Contracts; + +/** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Span.php + */ +interface Span +{ + /** + * @return string + */ + public function getOperationName(); + /** + * Yields the SpanContext for this Span. Note that the return value of + * Span::getContext() is still valid after a call to Span::finish(), as is + * a call to Span::getContext() after a call to Span::finish(). + * + * @return SpanContext + */ + public function getContext(); + /** + * Sets the end timestamp and finalizes Span state. + * + * With the exception of calls to getContext() (which are always allowed), + * finish() must be the last call made to any span instance, and to do + * otherwise leads to undefined behavior but not returning an exception. + * + * As an implementor, make sure you call {@see Tracer::deactivate()} + * otherwise new spans might try to be child of this one. + * + * If the span is already finished, a warning should be logged. + * + * @param float|int|\DateTimeInterface|null $finishTime if passing float or int + * it should represent the timestamp (including as many decimal places as you need) + * @return void + */ + public function finish($finishTime = null); + /** + * If the span is already finished, a warning should be logged. + * + * @param string $newOperationName + */ + public function overwriteOperationName($newOperationName); + /** + * Sets the span's resource name. + * + * @param string $resource + */ + public function setResource($resource); + /** + * Adds a tag to the span. + * + * If there is a pre-existing tag set for key, it is overwritten. + * + * As an implementor, consider using "standard tags" listed in {@see \DDTrace\Tags} + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param mixed $value + * @param boolean $setIfFinished + * @return void + */ + public function setTag($key, $value, $setIfFinished = false); + /** + * @param string $key + * @return string|null + */ + public function getTag($key); + /** + * Adds a log record to the span in key => value format, key must be a string and tag must be either + * a string, a boolean value, or a numeric type. + * + * If the span is already finished, a warning should be logged. + * + * @param array $fields + * @param int|float|\DateTimeInterface $timestamp + * @return void + */ + public function log(array $fields = [], $timestamp = null); + /** + * Adds a baggage item to the SpanContext which is immutable so it is required to use + * SpanContext::withBaggageItem to get a new one. + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param string $value + * @return void + */ + public function addBaggageItem($key, $value); + /** + * @param string $key + * @return string|null returns null when there is not a item under the provided key + */ + public function getBaggageItem($key); + /** + * @return array + */ + public function getAllBaggageItems(); + /** + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param \Throwable|\Exception|bool|null $error + * @throws \InvalidArgumentException + */ + public function setError($error); + /** + * Stores an error message and type in the Span. + * + * @param string $message + * @param string $type + */ + public function setRawError($message, $type); + /** + * Tells whether or not this Span contains errors. + * + * @return bool + */ + public function hasError(); + /** + * @return int + */ + public function getStartTime(); + /** + * @return int + */ + public function getDuration(); + /** + * @return string + */ + public function getTraceId(); + /** + * @return string + */ + public function getSpanId(); + /** + * @return null|string + */ + public function getParentId(); + /** + * @return string + */ + public function getResource(); + /** + * @return string + */ + public function getService(); + /** + * @return string|null + */ + public function getType(); + /** + * @return bool + */ + public function isFinished(); + /** + * @return array + */ + public function getAllTags(); + /** + * Tells whether or not the span has the provided tag. Note that there are no guarantees that the tag value is + * not empty. + * + * @param string $name + * @return bool + */ + public function hasTag($name); + /** + * Set a DD metric. + * + * @param string $key + * @param mixed $value + */ + public function setMetric($key, $value); + /** + * @return array All the currently set metrics. + */ + public function getMetrics(); +} +namespace DDTrace\Data; + +/** + * Class Span + * @property string $operationName + * @property string $resource + * @property string $service + * @property string $type + * @property int $startTime + * @property int $duration + * @property array $tags + * @property array $metrics + */ +abstract class Span implements \DDTrace\Contracts\Span +{ + /** + * @var SpanContextData + */ + public $context; + /** + * @var bool + */ + public $hasError = false; + /** + * @var \DDTrace\SpanData + */ + protected $internalSpan; + public function &__get($name) + { + } + public function __set($name, $value) + { + } + public function __isset($name) + { + } +} +namespace DDTrace; + +class Span extends \DDTrace\Data\Span +{ + use \DDTrace\Log\LoggingTrait; + public $internalSpan; + /** + * Span constructor. + * @param SpanData $internalSpan + * @param SpanContext $context + */ + public function __construct(\DDTrace\SpanData $internalSpan, \DDTrace\SpanContext $context) + { + } + /** + * {@inheritdoc} + */ + public function getTraceId() + { + } + /** + * {@inheritdoc} + */ + public function getSpanId() + { + } + /** + * {@inheritdoc} + */ + public function getParentId() + { + } + /** + * {@inheritdoc} + */ + public function overwriteOperationName($operationName) + { + } + /** + * {@inheritdoc} + */ + public function getResource() + { + } + /** + * {@inheritdoc} + */ + public function getService() + { + } + /** + * {@inheritdoc} + */ + public function getType() + { + } + /** + * {@inheritdoc} + */ + public function getStartTime() + { + } + /** + * {@inheritdoc} + */ + public function getDuration() + { + } + /** + * {@inheritdoc} + */ + public function setTag($key, $value, $setIfFinished = false) + { + } + /** + * {@inheritdoc} + */ + public function getTag($key) + { + } + /** + * {@inheritdoc} + */ + public function getAllTags() + { + } + /** + * {@inheritdoc} + */ + public function hasTag($name) + { + } + /** + * @param string $key + * @param mixed $value + */ + public function setMetric($key, $value) + { + } + /** + * @return array + */ + public function getMetrics() + { + } + /** + * {@inheritdoc} + */ + public function setResource($resource) + { + } + /** + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param Throwable|Exception|bool|null $error + * @throws InvalidArgumentException + */ + public function setError($error) + { + } + /** + * @param string $message + * @param string $type + */ + public function setRawError($message, $type) + { + } + public function hasError() + { + } + /** + * {@inheritdoc} + */ + public function finish($finishTime = null) + { + } + /** + * {@inheritdoc} + */ + public function isFinished() + { + } + /** + * {@inheritdoc} + */ + public function getOperationName() + { + } + /** + * {@inheritdoc} + */ + public function getContext() + { + } + /** + * {@inheritdoc} + */ + public function log(array $fields = [], $timestamp = null) + { + } + /** + * {@inheritdoc} + */ + public function addBaggageItem($key, $value) + { + } + /** + * {@inheritdoc} + */ + public function getBaggageItem($key) + { + } + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() + { + } + public function __destruct() + { + } +} +namespace DDTrace\Processing; + +/** + * A span processor in charge of adding the trace analytics client config metric when appropriate. + * + * NOTE: this may be transformer into a filter for consistency with other tracers, but for now we did not implement + * any filtering functionality so giving it such name as of now might be misleading. + */ +final class TraceAnalyticsProcessor +{ + /** + * @param array $metrics + * @param bool|float $value + */ + public static function normalizeAnalyticsValue(&$metrics, $value) + { + } +} +namespace OpenTelemetry\SDK\Trace; + +final class SpanBuilder implements \OpenTelemetry\API\Trace\SpanBuilderInterface +{ + /** @param non-empty-string $spanName */ + public function __construct(string $spanName, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, \OpenTelemetry\SDK\Trace\TracerSharedState $tracerSharedState) + { + } + /** + * @inheritDoc + */ + public function setParent($context) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function setStartTimestamp(int $timestampNanos) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function setSpanKind(int $spanKind) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function startSpan() : \OpenTelemetry\API\Trace\SpanInterface + { + } +} +final class Span extends \OpenTelemetry\API\Trace\Span implements \OpenTelemetry\SDK\Trace\ReadWriteSpanInterface +{ + /** + * This method _MUST_ not be used directly. + * End users should use a {@see API\TracerInterface} in order to create spans. + * + * @param non-empty-string $name + * @psalm-param API\SpanKind::KIND_* $kind + * @param list $links + * + * @internal + * @psalm-internal OpenTelemetry + */ + public static function startSpan(\DDTrace\SpanData $span, \OpenTelemetry\API\Trace\SpanContextInterface $context, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, int $kind, \OpenTelemetry\API\Trace\SpanInterface $parentSpan, \OpenTelemetry\Context\ContextInterface $parentContext, \OpenTelemetry\SDK\Trace\SpanProcessorInterface $spanProcessor, \OpenTelemetry\SDK\Resource\ResourceInfo $resource, array $attributes, array $links, int $totalRecordedLinks, array $events, bool $isRemapped = true) : self + { + } + public function getName() : string + { + } + /** + * @inheritDoc + */ + public function getContext() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public function getParentContext() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public function getInstrumentationScope() : \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface + { + } + public function hasEnded() : bool + { + } + /** + * @inheritDoc + */ + public function toSpanData() : \OpenTelemetry\SDK\Trace\SpanDataInterface + { + } + /** + * @inheritDoc + */ + public function getDuration() : int + { + } + /** + * @inheritDoc + */ + public function getKind() : int + { + } + /** + * @inheritDoc + */ + public function getAttribute(string $key) + { + } + public function getStartEpochNanos() : int + { + } + public function getTotalRecordedLinks() : int + { + } + public function getTotalRecordedEvents() : int + { + } + /** + * @inheritDoc + */ + public function isRecording() : bool + { + } + /** + * @inheritDoc + */ + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function updateName(string $name) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function setStatus(string $code, string $description = null) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function end(int $endEpochNanos = null) : void + { + } + public function endOTelSpan(int $endEpochNanos = null) : void + { + } + public function getResource() : \OpenTelemetry\SDK\Resource\ResourceInfo + { + } + /** + * @internal + * @return SpanData + */ + public function getDDSpan() : \DDTrace\SpanData + { + } +} +namespace OpenTelemetry\Context; + +/** + * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#context + */ +final class Context implements \OpenTelemetry\Context\ContextInterface +{ + public static function createKey(string $key) : \OpenTelemetry\Context\ContextKeyInterface + { + } + /** + * @param ContextStorageInterface&ExecutionContextAwareInterface $storage + */ + public static function setStorage(\OpenTelemetry\Context\ContextStorageInterface $storage) : void + { + } + /** + * @return ContextStorageInterface&ExecutionContextAwareInterface + */ + public static function storage() : \OpenTelemetry\Context\ContextStorageInterface + { + } + /** + * @param ContextInterface|false|null $context + * + * @internal OpenTelemetry + */ + public static function resolve($context, ?\OpenTelemetry\Context\ContextStorageInterface $contextStorage = null) : \OpenTelemetry\Context\ContextInterface + { + } + /** + * @internal + */ + public static function getRoot() : \OpenTelemetry\Context\ContextInterface + { + } + public static function getCurrent() : \OpenTelemetry\Context\ContextInterface + { + } + public function activate() : \OpenTelemetry\Context\ScopeInterface + { + } + public function withContextValue(\OpenTelemetry\Context\ImplicitContextKeyedInterface $value) : \OpenTelemetry\Context\ContextInterface + { + } + public function with(\OpenTelemetry\Context\ContextKeyInterface $key, $value) : self + { + } + public function get(\OpenTelemetry\Context\ContextKeyInterface $key) + { + } +} +namespace DDTrace\OpenTelemetry; + +// Operation Name Conventions +class Convention +{ + public static function defaultOperationName(\DDTrace\SpanData $span) : string + { + } +} +namespace DDTrace\OpenTelemetry\API\Trace; + +final class SpanContext implements \OpenTelemetry\API\Trace\SpanContextInterface +{ + /** + * @inheritDoc + */ + public function getTraceId() : string + { + } + public function getTraceIdBinary() : string + { + } + /** + * @inheritDoc + */ + public function getSpanId() : string + { + } + public function getSpanIdBinary() : string + { + } + public function getTraceState() : ?\OpenTelemetry\API\Trace\TraceStateInterface + { + } + public function isSampled() : bool + { + } + public function isValid() : bool + { + } + public function isRemote() : bool + { + } + public function getTraceFlags() : int + { + } + /** @inheritDoc */ + public static function createFromRemoteParent(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function create(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function getInvalid() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public static function createFromLocalSpan(\DDTrace\SpanData $span, bool $sampled, ?string $traceId = null, ?string $spanId = null) + { + } +} +namespace DDTrace\Contracts; + +/** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Scope.php + */ +/** + * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint. + * + * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a + * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an + * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given + * {@link Span} is scheduled and on the path. + */ +interface Scope +{ + /** + * Mark the end of the active period for the current thread and {@link Scope}, + * updating the {@link ScopeManager#active()} in the process. + * + * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined + * behavior. + */ + public function close(); + /** + * @return Span the {@link Span} that's been scoped by this {@link Scope} + */ + public function getSpan(); +} +namespace DDTrace; + +final class Scope implements \DDTrace\Contracts\Scope +{ + public function __construct(\DDTrace\ScopeManager $scopeManager, \DDTrace\Contracts\Span $span, $finishSpanOnClose) + { + } + /** + * {@inheritdoc} + */ + public function close() + { + } + /** + * {@inheritdoc} + * + * @return SpanInterface + */ + public function getSpan() + { + } +} +/** + * Propagator implementations should be able to inject and extract + * SpanContexts into an implementation specific carrier. + */ +interface Propagator +{ + const DEFAULT_BAGGAGE_HEADER_PREFIX = 'ot-baggage-'; + const DEFAULT_TRACE_ID_HEADER = 'x-datadog-trace-id'; + const DEFAULT_PARENT_ID_HEADER = 'x-datadog-parent-id'; + const DEFAULT_SAMPLING_PRIORITY_HEADER = 'x-datadog-sampling-priority'; + const DEFAULT_ORIGIN_HEADER = 'x-datadog-origin'; + /** + * Inject takes the SpanContext and injects it into the carrier using + * an implementation specific method. + * + * @param SpanContextInterface $spanContext + * @param array|\ArrayAccess $carrier + * @return void + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier); + /** + * Extract returns the SpanContext from the given carrier using an + * implementation specific method. + * + * @param array|\ArrayAccess $carrier + * @return SpanContextInterface + */ + public function extract($carrier); +} +namespace DDTrace\Propagators; + +final class TextMap implements \DDTrace\Propagator +{ + use \DDTrace\Log\LoggingTrait; + /** + * @param Tracer $tracer + */ + public function __construct(\DDTrace\Contracts\Tracer $tracer) + { + } + /** + * {@inheritdoc} + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier) + { + } + /** + * {@inheritdoc} + */ + public function extract($carrier) + { + } +} +namespace DDTrace\Contracts; + +/** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/ScopeManager.php + */ +/** + * Keeps track of the current active `Span`. + */ +interface ScopeManager +{ + const DEFAULT_FINISH_SPAN_ON_CLOSE = true; + /** + * Activates an `Span`, so that it is used as a parent when creating new spans. + * The implementation must keep track of the active spans sequence, so + * that previous spans can be resumed after a deactivation. + * + * @param Span $span the {@link Span} that should become the {@link #active()} + * @param bool $finishSpanOnClose whether span should automatically be finished + * when {@link Scope#close()} is called. Its default value is true. + * + * @return Scope instance to control the end of the active period for the {@link Span}. It is a + * programming error to neglect to call {@link Scope#close()} on the returned instance. + */ + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE); + /** + * Return the currently active {@link Scope} which can be used to access the + * currently active {@link Scope#getSpan()}. + * + * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent + * (as {@link References#CHILD_OF} reference) of any + * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()} + * time rather than at {@link Tracer#buildSpan(String)} time. + * + * @return Scope|null + */ + public function getActive(); + /** + * Closes all the current request root spans. Typically there only will be one. + */ + public function close(); +} +namespace DDTrace; + +final class ScopeManager implements \DDTrace\Contracts\ScopeManager +{ + public function __construct(\DDTrace\SpanContext $rootContext = null) + { + } + /** + * {@inheritdoc} + * @param Span|SpanInterface $span + */ + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE) + { + } + /** + * {@inheritdoc} + */ + public function getActive() + { + } + public function deactivate(\DDTrace\Scope $scope) + { + } + /** @internal */ + public function getPrimaryRoot() + { + } + /** @internal */ + public function getTopScope() + { + } + /** + * Closes all the current request root spans. Typically there only will be one. + */ + public function close() + { + } +} +namespace DDTrace\Contracts; + +/** + * SpanContext must be immutable in order to avoid complicated lifetime + * issues around Span finish and references. + * + * Baggage items are key => value string pairs that apply to the given Span, + * its SpanContext, and all Spans which directly or transitively reference + * the local Span. That is, baggage items propagate in-band along with the + * trace itself. + */ +interface SpanContext extends \IteratorAggregate +{ + /** + * Returns the value of a baggage item based on its key. If there is no + * value with such key it will return null. + * + * @param string $key + * @return string|null + */ + public function getBaggageItem($key); + /** + * Creates a new SpanContext out of the existing one and the new key => value pair. + * + * @param string $key + * @param string $value + * @return SpanContext + */ + public function withBaggageItem($key, $value); + /** + * @return array + */ + public function getAllBaggageItems(); + /** + * Gets initial priority sampling, upon span creation + * + * @return int + */ + public function getPropagatedPrioritySampling(); + /** + * Sets initial priority sampling, to be consumed upon span creation + * + * @param int $propagatedPrioritySampling + */ + public function setPropagatedPrioritySampling($propagatedPrioritySampling); + /** + * Returns whether or not this context represents the root span for a specific host. + * + * @return bool + */ + public function isHostRoot(); + /** + * @return string + */ + public function getTraceId(); + /** + * @return string + */ + public function getSpanId(); + /** + * @return string|null + */ + public function getParentId(); + /** + * @return bool + */ + public function isDistributedTracingActivationContext(); +} +namespace DDTrace\Data; + +abstract class SpanContext implements \DDTrace\Contracts\SpanContext +{ + /** + * The unique integer (63-bit unsigned) ID of the trace containing this span. + * It is stored in decimal representation. + * + * @var string + */ + public $traceId; + /** + * The span integer (63-bit unsigned) ID. + * It is stored in devimal representation. + * + * @var string + */ + public $spanId; + /** + * The span integer ID of the parent span. + * It is stored in decimal representation. + * + * @var string|null + */ + public $parentId; + /** + * Whether or not this SpanContext represent a distributed tracing remote context. + * When the Tracer::extract() extracts a span context because of distributed tracing then this property is true, + * otherwise is false. + * + * @var bool + */ + public $isDistributedTracingActivationContext; + /** + * Initial priority sampling, upon span creation + * + * @var int + */ + public $propagatedPrioritySampling; + /** + * The origin of the distributed trace. + * + * @var string|null + */ + public $origin; + /** + * @var SpanContextInterface + */ + public $parentContext; + /** + * @var array + */ + public $baggageItems; +} +namespace DDTrace; + +final class SpanContext extends \DDTrace\Data\SpanContext +{ + public function __construct($traceId, $spanId, $parentId = null, array $baggageItems = [], $isDistributedTracingActivationContext = false) + { + } + public static function createAsChild(\DDTrace\Contracts\SpanContext $parentContext, $startTime = null) + { + } + public static function createAsRoot(array $baggageItems = [], $startTime = null) + { + } + /** + * {@inheritdoc} + */ + public function getTraceId() + { + } + /** + * {@inheritdoc} + */ + public function getSpanId() + { + } + /** + * {@inheritdoc} + */ + public function getParentId() + { + } + /** + * {@inheritdoc} + */ + #[\ReturnTypeWillChange] + public function getIterator() + { + } + /** + * {@inheritdoc} + */ + public function getPropagatedPrioritySampling() + { + } + /** + * {@inheritdoc} + */ + public function setPropagatedPrioritySampling($propagatedPrioritySampling) + { + } + /** + * {@inheritdoc} + */ + public function getBaggageItem($key) + { + } + /** + * {@inheritdoc} + */ + public function withBaggageItem($key, $value) + { + } + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() + { + } + public function isEqual(\DDTrace\Contracts\SpanContext $spanContext) + { + } + /** + * {@inheritdoc} + */ + public function isDistributedTracingActivationContext() + { + } + /** + * {@inheritdoc} + */ + public function isHostRoot() + { + } +} +class Type +{ + const CACHE = 'cache'; + const HTTP_CLIENT = 'http'; + const WEB_SERVLET = 'web'; + const CLI = 'cli'; + const SQL = 'sql'; + const MESSAGE_CONSUMER = 'queue'; + const MESSAGE_PRODUCER = 'queue'; + const CASSANDRA = 'cassandra'; + const ELASTICSEARCH = 'elasticsearch'; + const MEMCACHED = 'memcached'; + const MONGO = 'mongodb'; + const OPENAI = 'openai'; + const REDIS = 'redis'; + const SYSTEM = 'system'; +} +class Tag +{ + // Generic + const ENV = 'env'; + const SPAN_TYPE = 'span.type'; + const SPAN_KIND = 'span.kind'; + const SPAN_KIND_VALUE_SERVER = 'server'; + const SPAN_KIND_VALUE_CLIENT = 'client'; + const SPAN_KIND_VALUE_PRODUCER = 'producer'; + const SPAN_KIND_VALUE_CONSUMER = 'consumer'; + const SPAN_KIND_VALUE_INTERNAL = 'internal'; + const COMPONENT = 'component'; + const SERVICE_NAME = 'service.name'; + const MANUAL_KEEP = 'manual.keep'; + const MANUAL_DROP = 'manual.drop'; + const PID = 'process_id'; + const RESOURCE_NAME = 'resource.name'; + const DB_STATEMENT = 'sql.query'; + const ERROR = 'error'; + const ERROR_MSG = 'error.message'; + // string representing the error message + const ERROR_TYPE = 'error.type'; + // string representing the type of the error + const ERROR_STACK = 'error.stack'; + // human readable version of the stack + const HTTP_METHOD = 'http.method'; + const HTTP_ROUTE = 'http.route'; + const HTTP_STATUS_CODE = 'http.status_code'; + const HTTP_URL = 'http.url'; + const HTTP_VERSION = 'http.version'; + const LOG_EVENT = 'event'; + const LOG_ERROR = 'error'; + const LOG_ERROR_OBJECT = 'error.object'; + const LOG_MESSAGE = 'message'; + const LOG_STACK = 'stack'; + const NETWORK_DESTINATION_NAME = 'network.destination.name'; + const TARGET_HOST = 'out.host'; + const TARGET_PORT = 'out.port'; + const BYTES_OUT = 'net.out.bytes'; + const ANALYTICS_KEY = '_dd1.sr.eausr'; + const HOSTNAME = '_dd.hostname'; + const ORIGIN = '_dd.origin'; + const VERSION = 'version'; + const SERVICE_VERSION = 'service.version'; + // OpenTelemetry compatible tag + // Elasticsearch + const ELASTICSEARCH_BODY = 'elasticsearch.body'; + const ELASTICSEARCH_METHOD = 'elasticsearch.method'; + const ELASTICSEARCH_PARAMS = 'elasticsearch.params'; + const ELASTICSEARCH_URL = 'elasticsearch.url'; + // Database + const DB_NAME = 'db.name'; + const DB_CHARSET = 'db.charset'; + const DB_INSTANCE = 'db.instance'; + const DB_TYPE = 'db.type'; + const DB_SYSTEM = 'db.system'; + const DB_ROW_COUNT = 'db.row_count'; + const DB_STMT = 'db.statement'; + const DB_USER = 'db.user'; + // Laravel Queue + const LARAVELQ_ATTEMPTS = 'messaging.laravel.attempts'; + const LARAVELQ_BATCH_ID = 'messaging.laravel.batch_id'; + const LARAVELQ_CONNECTION = 'messaging.laravel.connection'; + const LARAVELQ_MAX_TRIES = 'messaging.laravel.max_tries'; + const LARAVELQ_NAME = 'messaging.laravel.name'; + const LARAVELQ_TIMEOUT = 'messaging.laravel.timeout'; + // MongoDB + const MONGODB_BSON_ID = 'mongodb.bson.id'; + const MONGODB_COLLECTION = 'mongodb.collection'; + const MONGODB_DATABASE = 'mongodb.db'; + const MONGODB_PROFILING_LEVEL = 'mongodb.profiling_level'; + const MONGODB_READ_PREFERENCE = 'mongodb.read_preference'; + const MONGODB_SERVER = 'mongodb.server'; + const MONGODB_TIMEOUT = 'mongodb.timeout'; + const MONGODB_QUERY = 'mongodb.query'; + // REDIS + const REDIS_RAW_COMMAND = 'redis.raw_command'; + // Message Queue + const MQ_SYSTEM = 'messaging.system'; + const MQ_DESTINATION = 'messaging.destination'; + const MQ_DESTINATION_KIND = 'messaging.destination_kind'; + const MQ_TEMP_DESTINATION = 'messaging.temp_destination'; + const MQ_PROTOCOL = 'messaging.protocol'; + const MQ_PROTOCOL_VERSION = 'messaging.protocol_version'; + const MQ_URL = 'messaging.url'; + const MQ_MESSAGE_ID = 'messaging.message_id'; + const MQ_CONVERSATION_ID = 'messaging.conversation_id'; + const MQ_MESSAGE_PAYLOAD_SIZE = 'messaging.message_payload_size_bytes'; + const MQ_OPERATION = 'messaging.operation'; + const MQ_CONSUMER_ID = 'messaging.consumer_id'; + // RabbitMQ + const RABBITMQ_DELIVERY_MODE = 'messaging.rabbitmq.delivery_mode'; + const RABBITMQ_EXCHANGE = 'messaging.rabbitmq.exchange'; + const RABBITMQ_ROUTING_KEY = 'messaging.rabbitmq.routing_key'; + // Exec + const EXEC_CMDLINE_EXEC = 'cmd.exec'; + const EXEC_CMDLINE_SHELL = 'cmd.shell'; + const EXEC_TRUNCATED = 'cmd.truncated'; + const EXEC_EXIT_CODE = 'cmd.exit_code'; +} +final class Reference +{ + /** + * A Span may be the ChildOf a parent Span. In a ChildOf reference, + * the parent Span depends on the child Span in some capacity. + */ + const CHILD_OF = 'child_of'; + /** + * Some parent Spans do not depend in any way on the result of their + * child Spans. In these cases, we say merely that the child Span + * FollowsFrom the parent Span in a causal sense. + */ + const FOLLOWS_FROM = 'follows_from'; + /** + * @param SpanContextInterface|SpanInterface $context + * @param string $type + * @throws InvalidReferenceArgument on empty type + * @return Reference when context is invalid + */ + public static function create($type, $context) + { + } + /** + * @return SpanContextInterface + */ + public function getContext() + { + } + /** + * Checks whether a Reference is of one type. + * + * @param string $type the type for the reference + * @return bool + */ + public function isType($type) + { + } +} +namespace DDTrace\Sampling; + +class PrioritySampling +{ + // The Agent will drop the trace, as instructed by any mechanism that is not the sampler. + const USER_REJECT = -1; + // Automatic sampling decision. The Agent should drop the trace. + const AUTO_REJECT = 0; + // Automatic sampling decision. The Agent should keep the trace. + const AUTO_KEEP = 1; + // The Agent should keep the trace, as instructed by any mechanism that is not the sampler. + // The backend will only apply sampling if above maximum volume allowed. + const USER_KEEP = 2; + // It was not possible to parse + const UNKNOWN = null; + /** + * @param mixed|string $value + * @return int|null + */ + public static function parse($value) + { + } +} +namespace DDTrace\Exceptions; + +/** + * Thrown when passing an invalid argument for a reference + */ +final class InvalidReferenceArgument extends \InvalidArgumentException +{ + /** + * @return InvalidReferenceArgument + */ + public static function forEmptyType() + { + } + /** + * @param mixed $context + * @return InvalidReferenceArgument + */ + public static function forInvalidContext($context) + { + } +} +/** + * Thrown when trying to inject or extract in an invalid format + */ +final class UnsupportedFormat extends \UnexpectedValueException +{ + /** + * @param string $format + * @return UnsupportedFormat + */ + public static function forFormat($format) + { + } +} +final class InvalidSpanArgument extends \InvalidArgumentException +{ + public static function forTagKey($key) + { + } + public static function forError($error) + { + } +} +/** + * Thrown when a reference has more than one parent in the SpanOptions + */ +final class InvalidReferencesSet extends \DomainException +{ + /** + * @param string $message + * @return InvalidReferencesSet + */ + public static function create($message) + { + } + /** + * @return InvalidReferencesSet + */ + public static function forMoreThanOneParent() + { + } +} +/** + * Thrown when passing an invalid option on Span creation + */ +final class InvalidSpanOption extends \InvalidArgumentException +{ + /** + * @return InvalidSpanOption + */ + public static function forIncludingBothChildOfAndReferences() + { + } + /** + * @param mixed $reference + * @return InvalidSpanOption + */ + public static function forInvalidReference($reference) + { + } + /** + * @return InvalidSpanOption + */ + public static function forInvalidStartTime() + { + } + public static function forInvalidChildOf($childOfOption) + { + } + /** + * @param string $key + * @return InvalidSpanOption + */ + public static function forUnknownOption($key) + { + } + /** + * @param mixed $tag + * @return InvalidSpanOption + */ + public static function forInvalidTag($tag) + { + } + /** + * @param mixed $tagValue + * @return InvalidSpanOption + */ + public static function forInvalidTagValue($tagValue) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forInvalidTags($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forInvalidReferenceSet($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forFinishSpanOnClose($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forIgnoreActiveSpan($value) + { + } +} +namespace DDTrace; + +final class GlobalTracer +{ + /** + * GlobalTracer::set sets the [singleton] Tracer returned by get(). + * Those who use GlobalTracer (rather than directly manage a Tracer instance) + * should call GlobalTracer::set as early as possible in bootstrap, prior to + * start a new span. Prior to calling GlobalTracer::set, any Spans started + * via the `Tracer::startActiveSpan` (etc) globals are noops. + * + * @param TracerInterface $tracer + */ + public static function set(\DDTrace\Contracts\Tracer $tracer) + { + } + /** + * GlobalTracer::get returns the global singleton `Tracer` implementation. + * Before `GlobalTracer::set` is called, the `GlobalTracer::get` is a noop + * implementation that drops all data handed to it. + * + * @return TracerInterface + */ + public static function get() + { + } +} +namespace DDTrace\Http; + +/** + * A utility class that provides methods to work on urls + */ +class Urls +{ + /** + * Inject URL replacement patterns using '*' and '$*' as wildcards + * The '*' wildcard will match one or more characters to be replaced with '?' + * The '$*' wildcard will match one or more characters without replacement + * + * @param string[] $patternsWithWildcards + */ + public function __construct(array $patternsWithWildcards = []) + { + } + /** + * Removes query string and fragment and user information from a url. + * + * @param string $url + * @param bool $dropUserInfo Optional. If `true`, removes the user information fragment instead of obfuscating it. + * Defaults to `false`. + */ + public static function sanitize($url, $dropUserInfo = false) + { + } + /** + * Extracts the hostname of a given URL + * + * @param string $url + * @return string + */ + public static function hostname($url) + { + } + /** + * Metadata keys must start with [a-zA-Z:] so IP addresses, + * for example, need to be prefixed with a valid character. + * + * Note: then name of this function is misleading, as it should actually be normalizeUrlForService(), but since this + * part of the public API, we keep it like this and discuss a future deprecation. + * + * @param string $url + * @return string + */ + public static function hostnameForTag($url) + { + } + /** + * Reduces cardinality of a url. + * + * @param string $url + * @return string + */ + public function normalize($url) + { + } +} +namespace DDTrace\Log; + +/** + * A global logger holder. Can be configured to use a specific logger. If not configured, it returns a NullLogger. + */ +final class Logger +{ + /** + * Sets the global logger instance. + * + * @param LoggerInterface $logger + */ + public static function set(\DDTrace\Log\LoggerInterface $logger) + { + } + /** + * Retrieves the global logger instance. If not set, it falls back to a NullLogger. + * + * @return LoggerInterface + */ + public static function get() + { + } + /** + * Reset the logger. + */ + public static function reset() + { + } +} +/** + * Known log levels. + */ +final class LogLevel +{ + /** + * Const list from https://www.php-fig.org/psr/psr-3/ + */ + const EMERGENCY = 'emergency'; + const ALERT = 'alert'; + const CRITICAL = 'critical'; + const ERROR = 'error'; + const WARNING = 'warning'; + const NOTICE = 'notice'; + const INFO = 'info'; + const DEBUG = 'debug'; + /** + * All the log levels. + * + * @return string[] + */ + public static function all() + { + } +} +/** + * Provides methods to interpolate log messages. + */ +trait InterpolateTrait +{ + /** + * Interpolates context values into the message placeholders. Example code from: + * https://www.php-fig.org/psr/psr-3/ + * + * @param string $message + * @param array $context + * @return string + */ + public static function interpolate($message, array $context = []) + { + } +} +/** + * JSON logger that writes to a stream, with simple logs correlation support. + * Heavily inspired from Monolog's StreamHandler. + * @internal This logger is internal and can be removed without prior notice + */ +final class DatadogLogger +{ + use \DDTrace\Log\InterpolateTrait; + const DEFAULT_JSON_FLAGS = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRESERVE_ZERO_FRACTION | JSON_PARTIAL_OUTPUT_ON_ERROR; + public function __construct($stream = null, $mode = 'a') + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function emergency($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function alert($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function critical($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function error($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function notice($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function info($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function debug($message, array $context = []) + { + } + /** + * @param string $level + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function log(string $level, $message, array $context = []) + { + } + public function customErrorHandler(int $code, string $msg) : bool + { + } +} +/** + * Defines logging methods as used in DDTrace code. + */ +interface LoggerInterface +{ + /** + * Logs a message at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function debug($message, array $context = array()); + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []); + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = array()); + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level); +} +/** + * An abstract logger. + */ +abstract class AbstractLogger implements \DDTrace\Log\LoggerInterface +{ + /** + * @param string $level + */ + public function __construct($level) + { + } + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level) + { + } +} +/** + * An implementation of the DDTrace\LoggerInterface that logs to the error_log. + */ +class ErrorLogLogger extends \DDTrace\Log\AbstractLogger +{ + use \DDTrace\Log\InterpolateTrait; + /** + * Logs a debug message. Substitution is provided as specified in: + * https://www.php-fig.org/psr/psr-3/ + * + * @param string $message + * @param array $context + */ + public function debug($message, array $context = []) + { + } + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = []) + { + } +} +/** + * An implementation of the DDTrace\LoggerInterface that logs nothing. + */ +final class NullLogger extends \DDTrace\Log\AbstractLogger +{ + /** + * Logs a debug at the debug level. + * + * @param string $message + * @param array $context + */ + public function debug($message, array $context = array()) + { + } + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = array()) + { + } + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level) + { + } +} +namespace DDTrace\Obfuscation; + +/** + * Converts strings with wildcards into search/replace regex arrays + * The following is converted + * - * -> ? + * - $* -> ${n} + */ +// Examples: /api/v1/users/*,/api/v1/rooms/*/$*,/api/v1/bookings/*/guests +// - /api/v1/users/123 -> /api/v1/users/? +// - /api/v1/rooms/123/details -> /api/v1/rooms/?/details +// - /api/v1/rooms/foo-bar-room/gallery -> /api/v1/rooms/?/gallery +// - /api/v1/bookings/123/guests/ -> /api/v1/bookings/?/guests +final class WildcardToRegex +{ + const REPLACEMENT_CHARACTER = '?'; + /** + * @param string $wildcardPattern + * + * @return string[] + */ + public static function convert($wildcardPattern) + { + } +} +namespace DDTrace; + +class Format +{ + /** + * Used a (single) arbitrary binary blob representing a SpanContext + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `string`. + */ + const BINARY = 'binary'; + /** + * Used for an arbitrary string-to-string map with an unrestricted character set for both keys and values + * + * Unlike `HTTP_HEADERS`, the `TEXT_MAP` format does not restrict the key or + * value character sets in any way. + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + */ + const TEXT_MAP = 'text_map'; + /** + * Used for a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. + * In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly + * recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. + * + * Unlike `TEXT_MAP`, the `HTTP_HEADERS` format requires that the keys and values be valid as HTTP headers as-is + * (i.e., character casing may be unstable and special characters are disallowed in keys, values should be + * URL-escaped, etc). + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + * + * For example, Tracer::inject(): + * + * $headers = [] + * $tracer->inject($span->getContext(), Format::HTTP_HEADERS, $headers) + * $request = new GuzzleHttp\Psr7\Request($uri, $body, $headers); + * + * Or Tracer::extract(): + * + * $headers = $request->getHeaders() + * $clientContext = $tracer->extract(Formats::HTTP_HEADERS, $headers) + * + * @see http://www.php-fig.org/psr/psr-7/#12-http-headers + * @see http://php.net/manual/en/function.getallheaders.php + */ + const HTTP_HEADERS = 'http_headers'; +} +final class StartSpanOptions +{ + /** + * @param array $options + * @throws InvalidSpanOption when one of the options is invalid + * @throws InvalidReferencesSet when there are inconsistencies about the references + * @return StartSpanOptions + */ + public static function create(array $options) + { + } + /** + * @param SpanInterface|SpanContextInterface $parent + * @return StartSpanOptions + */ + public function withParent($parent) + { + } + /** + * @return Reference[] + */ + public function getReferences() + { + } + /** + * @return array + */ + public function getTags() + { + } + /** + * @return int|float|\DateTime|null if returning float or int it should represent + * the timestamp (including as many decimal places as you need) + */ + public function getStartTime() + { + } + /** + * @return bool + */ + public function shouldFinishSpanOnClose() + { + } + /** + * @return bool + */ + public function shouldIgnoreActiveSpan() + { + } +} \ No newline at end of file diff --git a/tooling/stubs/composer.json b/tooling/stubs/composer.json new file mode 100644 index 0000000000..d3b8fd1083 --- /dev/null +++ b/tooling/stubs/composer.json @@ -0,0 +1,10 @@ +{ + "require-dev": { + "php-stubs/generator": "^0.8.4" + }, + "scripts": { + "generate": [ + "php generate-stubs.php" + ] + } +} diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php new file mode 100644 index 0000000000..7b26dad10e --- /dev/null +++ b/tooling/stubs/generate-stubs.php @@ -0,0 +1,26 @@ + require $file, FILES_TO_LOAD)); + +$files = array_map(fn($file) => str_replace(SRC_DIR . "bridge/../", "", $file), $files); + +$generator = new StubsGenerator(); +$finder = Finder::create()->in(SRC_DIR)->path($files); + +$stubs = $generator->generate($finder)->prettyPrint(); + +$outputFile = SRC_DIR . "ddtrace_php_api.stubs.php"; +file_put_contents($outputFile, $stubs); + +echo sprintf("Stubs generated at %s\n", $outputFile); From 1fd307e3df629953ea2f60de36fa18853e187314 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Fri, 8 Nov 2024 09:27:51 +0100 Subject: [PATCH 02/23] chore: Merge all stubs into one single file during artifact generation --- tooling/bin/generate-final-artifact.sh | 28 ++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index 77334b6980..5e6ad1409a 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -152,6 +152,34 @@ for architecture in "${architectures[@]}"; do "${tmp_folder_final_musl_appsec}/etc/recommended.json" fi + ######################## + # PHP Stubs + ######################## + $stubs = [ + '/home/circleci/app/src/ddtrace_php_api.stubs.php', + '/home/circleci/app/ext/ddtrace.stub.php', + '/home/circleci/app/ext/hook/uhook.stub.php', + '/home/circleci/app/ext/hook/uhook_attributes.stub.php', + ]; + + $mergedStubs = ''; + foreach ($stubs as $stub) { + $content = file_get_contents($stub); + $content = preg_replace('/^<\?php/', '', $content); + $mergedStubs .= "\n### " . basename($stub) . " ###" + $merg$mergedStubsed .= $content; + } + + $stub = " $tmp_folder_final_gnu/dd-library-php/ddtrace_api.stubs.php + if [[ -z ${DDTRACE_MAKE_PACKAGES_ASAN:-} ]]; then + echo "$stub" > $tmp_folder_final_musl/dd-library-php/ddtrace_api.stubs.php + if [[ $architecture == "x86_64" ]]; then + echo "$stub" > $tmp_folder_final_windows/dd-library-php/ddtrace_api.stubs.php + fi + fi + ######################## # Final archives ######################## From 4223bc30ae0328b27d712017c063743515747e30 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Fri, 8 Nov 2024 09:28:20 +0100 Subject: [PATCH 03/23] fix: typo --- tooling/bin/generate-final-artifact.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index 5e6ad1409a..d36a7077e0 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -166,8 +166,7 @@ for architecture in "${architectures[@]}"; do foreach ($stubs as $stub) { $content = file_get_contents($stub); $content = preg_replace('/^<\?php/', '', $content); - $mergedStubs .= "\n### " . basename($stub) . " ###" - $merg$mergedStubsed .= $content; + $mergedStubs .= $content; } $stub = " Date: Fri, 8 Nov 2024 09:42:25 +0100 Subject: [PATCH 04/23] fix: language --- tooling/bin/generate-final-artifact.sh | 38 +++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index d36a7077e0..fbeffb7df8 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -155,27 +155,27 @@ for architecture in "${architectures[@]}"; do ######################## # PHP Stubs ######################## - $stubs = [ - '/home/circleci/app/src/ddtrace_php_api.stubs.php', - '/home/circleci/app/ext/ddtrace.stub.php', - '/home/circleci/app/ext/hook/uhook.stub.php', - '/home/circleci/app/ext/hook/uhook_attributes.stub.php', - ]; - - $mergedStubs = ''; - foreach ($stubs as $stub) { - $content = file_get_contents($stub); - $content = preg_replace('/^<\?php/', '', $content); - $mergedStubs .= $content; - } - - $stub = " $tmp_folder_final_gnu/dd-library-php/ddtrace_api.stubs.php + stubs=( + "/home/circleci/app/src/ddtrace_php_api.stubs.php" + "/home/circleci/app/ext/ddtrace.stub.php" + "/home/circleci/app/ext/hook/uhook.stub.php" + "/home/circleci/app/ext/hook/uhook_attributes.stub.php" + ) + + mergedStubs="" + for stub in "${stubs[@]}"; do + content=$(<"$stub") + content="${content# "$tmp_folder_final_gnu/dd-library-php/ddtrace_api.stubs.php" if [[ -z ${DDTRACE_MAKE_PACKAGES_ASAN:-} ]]; then - echo "$stub" > $tmp_folder_final_musl/dd-library-php/ddtrace_api.stubs.php + echo -e "$stub" > "$tmp_folder_final_musl/dd-library-php/ddtrace_api.stubs.php" if [[ $architecture == "x86_64" ]]; then - echo "$stub" > $tmp_folder_final_windows/dd-library-php/ddtrace_api.stubs.php + echo -e "$stub" > "$tmp_folder_final_windows/dd-library-php/ddtrace_api.stubs.php" fi fi From f97335baa09f1b1ec41513fd1d2609cb0711453a Mon Sep 17 00:00:00 2001 From: Alexandre Choura <42672104+PROFeNoM@users.noreply.github.com> Date: Fri, 8 Nov 2024 10:06:07 +0100 Subject: [PATCH 05/23] Rename `/home/circleci/app` to `/home/circleci/datadog` --- tooling/bin/generate-final-artifact.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index fbeffb7df8..639dc9a8c0 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -156,10 +156,10 @@ for architecture in "${architectures[@]}"; do # PHP Stubs ######################## stubs=( - "/home/circleci/app/src/ddtrace_php_api.stubs.php" - "/home/circleci/app/ext/ddtrace.stub.php" - "/home/circleci/app/ext/hook/uhook.stub.php" - "/home/circleci/app/ext/hook/uhook_attributes.stub.php" + "/home/circleci/datadog/src/ddtrace_php_api.stubs.php" + "/home/circleci/datadog/ext/ddtrace.stub.php" + "/home/circleci/datadog/ext/hook/uhook.stub.php" + "/home/circleci/datadog/ext/hook/uhook_attributes.stub.php" ) mergedStubs="" From 0ce1b279e4dbea6615d9333a022e86a70a72bd34 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 14:43:56 +0100 Subject: [PATCH 06/23] feat: Use PROJECT_ROOT as third argument --- Makefile | 3 ++- tooling/bin/generate-final-artifact.sh | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 14f1c40192..8d16bb464d 100644 --- a/Makefile +++ b/Makefile @@ -478,7 +478,8 @@ $(PACKAGES_BUILD_DIR): bundle.tar.gz: $(PACKAGES_BUILD_DIR) bash ./tooling/bin/generate-final-artifact.sh \ $(VERSION) \ - $(PACKAGES_BUILD_DIR) + $(PACKAGES_BUILD_DIR) \ + $(PROJECT_ROOT) $(PACKAGES_BUILD_DIR)/datadog-setup.php: $(PACKAGES_BUILD_DIR) bash ./tooling/bin/generate-installers.sh \ diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index 639dc9a8c0..aba249f08b 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -156,10 +156,10 @@ for architecture in "${architectures[@]}"; do # PHP Stubs ######################## stubs=( - "/home/circleci/datadog/src/ddtrace_php_api.stubs.php" - "/home/circleci/datadog/ext/ddtrace.stub.php" - "/home/circleci/datadog/ext/hook/uhook.stub.php" - "/home/circleci/datadog/ext/hook/uhook_attributes.stub.php" + "$3/src/ddtrace_php_api.stubs.php" + "$3/ext/ddtrace.stub.php" + "$3/ext/hook/uhook.stub.php" + "$3/ext/hook/uhook_attributes.stub.php" ) mergedStubs="" From e0f5063fef1af215370edf53c3ef81a1bb9a70bc Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 14:44:51 +0100 Subject: [PATCH 07/23] ci: Rename `cbindgen up-to-date` to `generated files up-to-date` --- .circleci/continue_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/continue_config.yml b/.circleci/continue_config.yml index 23d0c3e548..d5c1b68849 100644 --- a/.circleci/continue_config.yml +++ b/.circleci/continue_config.yml @@ -3882,7 +3882,7 @@ jobs: phpize php run-tests.php -p $(which php) -d datadog.remote_config_enabled=false --show-diff -g "FAIL,XFAIL,BORK,WARN,LEAK,XLEAK,SKIP" tests/ext/profiling - "cbindgen up-to-date": + "generated files up-to-date": working_directory: ~/datadog docker: - image: datadog/dd-trace-ci:buster From 3622bc6bbf2f6a47bbbc21ebd0c9a9622398146e Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 14:50:42 +0100 Subject: [PATCH 08/23] feat: Regenerate PHP stubs and compare them --- .circleci/continue_config.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.circleci/continue_config.yml b/.circleci/continue_config.yml index d5c1b68849..9ff6c1de61 100644 --- a/.circleci/continue_config.yml +++ b/.circleci/continue_config.yml @@ -3885,7 +3885,7 @@ jobs: "generated files up-to-date": working_directory: ~/datadog docker: - - image: datadog/dd-trace-ci:buster + - image: datadog/dd-trace-ci:8.3-buster steps: - restore_cache: keys: @@ -3900,6 +3900,12 @@ jobs: set -eu make cbindgen git diff --exit-code components-rs + - run: + name: Regenerate PHP stubs and compare them + command: | + set -eu + make generate_stubs + git diff --exit-code src/ddtrace_php_api.stubs.php - run: name: Ensure no non-bundled rust git dependencies are used command: | From c135675a71a2510dfe9f4bed70c096e5e22f5896 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 14:52:45 +0100 Subject: [PATCH 09/23] style: Put generated artifact directly in the artifacts --- tooling/bin/generate-final-artifact.sh | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index aba249f08b..ca6bd65e38 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -170,14 +170,7 @@ for architecture in "${architectures[@]}"; do done stub=" "$tmp_folder_final_gnu/dd-library-php/ddtrace_api.stubs.php" - if [[ -z ${DDTRACE_MAKE_PACKAGES_ASAN:-} ]]; then - echo -e "$stub" > "$tmp_folder_final_musl/dd-library-php/ddtrace_api.stubs.php" - if [[ $architecture == "x86_64" ]]; then - echo -e "$stub" > "$tmp_folder_final_windows/dd-library-php/ddtrace_api.stubs.php" - fi - fi + echo -e "$stub" > "$packages_build_dir/ddtrace_api.stubs.php" ######################## # Final archives From c685562b0d62f1a7afd6045471eb8dfbbffda593 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:06:02 +0100 Subject: [PATCH 10/23] fix: generated files up-to-date --- .circleci/continue_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/continue_config.yml b/.circleci/continue_config.yml index 9ff6c1de61..58edc6ae58 100644 --- a/.circleci/continue_config.yml +++ b/.circleci/continue_config.yml @@ -5744,7 +5744,7 @@ workflows: name: "Static Analysis 80" docker_image: datadog/dd-trace-ci:php-8.0_buster scenario: opentracing10 - - "cbindgen up-to-date" + - "generated files up-to-date" - "Post-Install Hook": requires: [ 'Prepare Code' ] From 46aa623082b3a5617fcdb1a30240d9f9d18200c2 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:08:17 +0100 Subject: [PATCH 11/23] fix: buster image name --- .circleci/continue_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/continue_config.yml b/.circleci/continue_config.yml index 58edc6ae58..eb90056776 100644 --- a/.circleci/continue_config.yml +++ b/.circleci/continue_config.yml @@ -3885,7 +3885,7 @@ jobs: "generated files up-to-date": working_directory: ~/datadog docker: - - image: datadog/dd-trace-ci:8.3-buster + - image: datadog/dd-trace-ci:php-8.3_buster steps: - restore_cache: keys: From 56ab089244a8db9f0edb8d37fac42b5077381446 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:15:06 +0100 Subject: [PATCH 12/23] fix: src dir --- tooling/stubs/generate-stubs.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index 7b26dad10e..dd2eff0e30 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -4,7 +4,7 @@ use StubsGenerator\{StubsGenerator, Finder}; -const SRC_DIR = "/home/circleci/app/src/"; +$SRC_DIR = dirname(__DIR__, 3) . "/src/"; const FILES_TO_LOAD = [ "../../src/bridge/_files_api.php", "../../src/bridge/_files_tracer.php", @@ -13,14 +13,14 @@ $files = array_merge(...array_map(fn($file) => require $file, FILES_TO_LOAD)); -$files = array_map(fn($file) => str_replace(SRC_DIR . "bridge/../", "", $file), $files); +$files = array_map(fn($file) => str_replace($SRC_DIR . "bridge/../", "", $file), $files); $generator = new StubsGenerator(); -$finder = Finder::create()->in(SRC_DIR)->path($files); +$finder = Finder::create()->in($SRC_DIR)->path($files); $stubs = $generator->generate($finder)->prettyPrint(); -$outputFile = SRC_DIR . "ddtrace_php_api.stubs.php"; +$outputFile = $SRC_DIR . "ddtrace_php_api.stubs.php"; file_put_contents($outputFile, $stubs); echo sprintf("Stubs generated at %s\n", $outputFile); From 91547c4c4e61438fb9b5abb79d43130c39e3cfab Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:19:13 +0100 Subject: [PATCH 13/23] fix: src dir --- tooling/stubs/generate-stubs.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index dd2eff0e30..edb10dec5a 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -4,7 +4,7 @@ use StubsGenerator\{StubsGenerator, Finder}; -$SRC_DIR = dirname(__DIR__, 3) . "/src/"; +$SRC_DIR = dirname(__DIR__, 4) . "/src/"; const FILES_TO_LOAD = [ "../../src/bridge/_files_api.php", "../../src/bridge/_files_tracer.php", From 22e2d59a7c59715725d08dd1543e46a0ed6899f8 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:26:46 +0100 Subject: [PATCH 14/23] style: Rename merged stubs file --- tooling/bin/generate-final-artifact.sh | 2 +- tooling/stubs/generate-stubs.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index ca6bd65e38..5cbf982b77 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -170,7 +170,7 @@ for architecture in "${architectures[@]}"; do done stub=" "$packages_build_dir/ddtrace_api.stubs.php" + echo -e "$stub" > "$packages_build_dir/datadog_tracer.stubs.php" ######################## # Final archives diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index edb10dec5a..c1f3ce214c 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -4,7 +4,7 @@ use StubsGenerator\{StubsGenerator, Finder}; -$SRC_DIR = dirname(__DIR__, 4) . "/src/"; +$SRC_DIR = implode('/', array_slice(explode('/', __DIR__), 0, 3)) . '/src/'; const FILES_TO_LOAD = [ "../../src/bridge/_files_api.php", "../../src/bridge/_files_tracer.php", From 0de994d696cd299947d849847a943fb6c12cc6c5 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:31:30 +0100 Subject: [PATCH 15/23] fix: offset --- tooling/stubs/generate-stubs.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index c1f3ce214c..46b471b5d0 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -4,7 +4,7 @@ use StubsGenerator\{StubsGenerator, Finder}; -$SRC_DIR = implode('/', array_slice(explode('/', __DIR__), 0, 3)) . '/src/'; +$SRC_DIR = implode('/', array_slice(explode('/', __DIR__), 0, 4)) . '/src/'; const FILES_TO_LOAD = [ "../../src/bridge/_files_api.php", "../../src/bridge/_files_tracer.php", From 37b3e00f3283296f31f1d0285616385cf3415e9d Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:54:46 +0100 Subject: [PATCH 16/23] fix: Sort by name --- tooling/stubs/generate-stubs.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index 46b471b5d0..3fbc9f8add 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -16,7 +16,7 @@ $files = array_map(fn($file) => str_replace($SRC_DIR . "bridge/../", "", $file), $files); $generator = new StubsGenerator(); -$finder = Finder::create()->in($SRC_DIR)->path($files); +$finder = Finder::create()->in($SRC_DIR)->path($files)->sortByName(); $stubs = $generator->generate($finder)->prettyPrint(); From 6faa2101546f6f2ebbf2060e8f4f94f54642f1a3 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 15:59:23 +0100 Subject: [PATCH 17/23] chore: Update ddtrace_php_api.stubs.php --- src/ddtrace_php_api.stubs.php | 2486 +++++++++++++++++---------------- 1 file changed, 1245 insertions(+), 1241 deletions(-) diff --git a/src/ddtrace_php_api.stubs.php b/src/ddtrace_php_api.stubs.php index d0151b3192..7f47753c13 100644 --- a/src/ddtrace_php_api.stubs.php +++ b/src/ddtrace_php_api.stubs.php @@ -1,1658 +1,1482 @@ getActive()->getSpan(), - * and null will be returned if {@link Scope#active()} is null. - * - * @return Span|null - */ - public function getActiveSpan(); - /** - * Starts a new span that is activated on a scope manager. - * - * It's also possible to not finish the {@see \DDTrace\Contracts\Span} when - * {@see \DDTrace\Contracts\Scope} context expires: - * - * $scope = $tracer->startActiveSpan('...', [ - * 'finish_span_on_close' => false, - * ]); - * $span = $scope->getSpan(); - * try { - * $span->setTag(Tags\HTTP_METHOD, 'GET'); - * // ... - * } finally { - * $scope->close(); - * } - * // $span->finish() is not called as part of Scope deactivation as - * // finish_span_on_close is false - * - * @param string $operationName - * @param array|StartSpanOptions $options Same as for startSpan() with - * aditional option of `finish_span_on_close` that enables finishing - * of span whenever a scope is closed. It is true by default. - * - * @return Scope A Scope that holds newly created Span and is activated on - * a ScopeManager. - */ - public function startActiveSpan($operationName, $options = []); - /** - * Starts and returns a new span representing a unit of work. - * - * Whenever `child_of` reference is not passed then - * {@see \DDTrace\Contracts\ScopeManager::getActive()} span is used as `child_of` - * reference. In order to ignore implicit parent span pass in - * `ignore_active_span` option set to true. - * - * Starting a span with explicit parent: - * - * $tracer->startSpan('...', [ - * 'child_of' => $parentSpan, - * ]); - * - * @see \DDTrace\StartSpanOptions - * - * @param string $operationName - * @param array|StartSpanOptions $options See StartSpanOptions for - * available options. - * - * @return Span - * - * @throws InvalidSpanOption for invalid option - * @throws InvalidReferencesSet for invalid references set - */ - public function startSpan($operationName, $options = []); - /** - * @param SpanContext $spanContext - * @param string $format - * @param mixed $carrier - * - * @see Formats - * - * @throws UnsupportedFormat when the format is not recognized by the tracer - * implementation - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier); - /** - * @param string $format - * @param mixed $carrier - * @return SpanContext|null - * - * @see Formats - * - * @throws UnsupportedFormat when the format is not recognized by the tracer - * implementation - */ - public function extract($format, $carrier); - /** - * Allow tracer to send span data to be instrumented. - * - * This method might not be needed depending on the tracing implementation - * but one should make sure this method is called after the request is delivered - * to the client. - * - * As an implementor, a good idea would be to use {@see register_shutdown_function} - * or {@see fastcgi_finish_request} in order to not to delay the end of the request - * to the client. - */ - public function flush(); - /** - * @param mixed $prioritySampling - */ - public function setPrioritySampling($prioritySampling); - /** - * @return int|null - */ - public function getPrioritySampling(); - /** - * This behaves just like Tracer::startActiveSpan(), but it saves the Scope instance - * on the tracer to be accessed later by Tracer::getRootScope(). - * - * @param string $operationName - * @param array $options - * @return Scope - */ - public function startRootSpan($operationName, $options = []); - /** - * @return Scope|null + * @param ContextStorageInterface&ExecutionContextAwareInterface $storage */ - public function getRootScope(); + public static function setStorage(\OpenTelemetry\Context\ContextStorageInterface $storage) : void + { + } /** - * Returns the root span or null and never throws an exception. - * - * @return Span|null + * @return ContextStorageInterface&ExecutionContextAwareInterface */ - public function getSafeRootSpan(); + public static function storage() : \OpenTelemetry\Context\ContextStorageInterface + { + } /** - * Returns the entire trace encoded as a plain-old PHP array. + * @param ContextInterface|false|null $context * - * @return array + * @internal OpenTelemetry */ - public function getTracesAsArray(); + public static function resolve($context, ?\OpenTelemetry\Context\ContextStorageInterface $contextStorage = null) : \OpenTelemetry\Context\ContextInterface + { + } /** - * Returns the count of currently stored traces - * - * @return int + * @internal */ - public function getTracesCount(); + public static function getRoot() : \OpenTelemetry\Context\ContextInterface + { + } + public static function getCurrent() : \OpenTelemetry\Context\ContextInterface + { + } + public function activate() : \OpenTelemetry\Context\ScopeInterface + { + } + public function withContextValue(\OpenTelemetry\Context\ImplicitContextKeyedInterface $value) : \OpenTelemetry\Context\ContextInterface + { + } + public function with(\OpenTelemetry\Context\ContextKeyInterface $key, $value) : self + { + } + public function get(\OpenTelemetry\Context\ContextKeyInterface $key) + { + } } -namespace DDTrace\Log; +namespace DDTrace\OpenTelemetry; -trait LoggingTrait +// Operation Name Conventions +class Convention { - /** - * Emits a log message at debug level. - * - * @param string $message - * @param array $context - */ - protected static function logDebug($message, array $context = []) + public static function defaultOperationName(\DDTrace\SpanData $span) : string { } +} +namespace OpenTelemetry\SDK\Trace; + +final class Span extends \OpenTelemetry\API\Trace\Span implements \OpenTelemetry\SDK\Trace\ReadWriteSpanInterface +{ /** - * Emits a log message at warning level. + * This method _MUST_ not be used directly. + * End users should use a {@see API\TracerInterface} in order to create spans. * - * @param string $message - * @param array $context + * @param non-empty-string $name + * @psalm-param API\SpanKind::KIND_* $kind + * @param list $links + * + * @internal + * @psalm-internal OpenTelemetry */ - protected static function logWarning($message, array $context = []) + public static function startSpan(\DDTrace\SpanData $span, \OpenTelemetry\API\Trace\SpanContextInterface $context, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, int $kind, \OpenTelemetry\API\Trace\SpanInterface $parentSpan, \OpenTelemetry\Context\ContextInterface $parentContext, \OpenTelemetry\SDK\Trace\SpanProcessorInterface $spanProcessor, \OpenTelemetry\SDK\Resource\ResourceInfo $resource, array $attributes, array $links, int $totalRecordedLinks, array $events, bool $isRemapped = true) : self { } - /** - * Emits a log message at error level. - * - * @param string $message - * @param array $context - */ - protected static function logError($message, array $context = []) + public function getName() : string { } /** - * @return bool + * @inheritDoc */ - protected static function isLogDebugActive() + public function getContext() : \OpenTelemetry\API\Trace\SpanContextInterface { } -} -namespace DDTrace; - -final class Tracer implements \DDTrace\Contracts\Tracer -{ - use \DDTrace\Log\LoggingTrait; - /** - * @param Transport $transport - * @param Propagator[] $propagators - * @param array $config - */ - public function __construct(\DDTrace\Transport $transport = null, array $propagators = null, array $config = []) + public function getParentContext() : \OpenTelemetry\API\Trace\SpanContextInterface { } - public function limited() + public function getInstrumentationScope() : \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface + { + } + public function hasEnded() : bool { } /** - * Resets this tracer to its original state. + * @inheritDoc */ - public function reset() + public function toSpanData() : \OpenTelemetry\SDK\Trace\SpanDataInterface { } /** - * @return Tracer + * @inheritDoc */ - public static function noop() + public function getDuration() : int { } /** - * {@inheritdoc} + * @inheritDoc */ - public function startSpan($operationName, $options = []) + public function getKind() : int { } /** - * {@inheritdoc} + * @inheritDoc */ - public function startRootSpan($operationName, $options = []) + public function getAttribute(string $key) { } - /** - * {@inheritdoc} - */ - public function getRootScope() + public function getStartEpochNanos() : int { } - /** - * {@inheritdoc} - */ - public function startActiveSpan($operationName, $options = []) + public function getTotalRecordedLinks() : int { } - /** - * {@inheritdoc} - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier) + public function getTotalRecordedEvents() : int { } /** - * {@inheritdoc} + * @inheritDoc */ - public function extract($format, $carrier) + public function isRecording() : bool { } /** - * @return void + * @inheritDoc */ - public function flush() + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * {@inheritdoc} + * @inheritDoc */ - public function getScopeManager() + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * @return null|Span + * @inheritDoc */ - public function getActiveSpan() + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * {@inheritdoc} + * @inheritDoc */ - public function getTracesAsArray() - { - } - public function addUrlAsResourceNameToSpan(\DDTrace\Contracts\Span $span) + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * @param mixed $prioritySampling + * @inheritDoc */ - public function setPrioritySampling($prioritySampling) + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * {@inheritdoc} + * @inheritDoc */ - public function getPrioritySampling() + public function updateName(string $name) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * Returns the root span or null and never throws an exception. - * - * @return SpanInterface|null + * @inheritDoc */ - public function getSafeRootSpan() + public function setStatus(string $code, string $description = null) : \OpenTelemetry\API\Trace\SpanInterface { } /** - * @return string + * @inheritDoc */ - public static function version() + public function end(int $endEpochNanos = null) : void + { + } + public function endOTelSpan(int $endEpochNanos = null) : void + { + } + public function getResource() : \OpenTelemetry\SDK\Resource\ResourceInfo { } /** - * {@inheritdoc} + * @internal + * @return SpanData */ - public function getTracesCount() + public function getDDSpan() : \DDTrace\SpanData { } } -/** - * Although DataDog uses nanotime to report spans PHP does not support nanotime - * plus, nanotime is a uint64 which is not supported either. Microtime will be used - * and there will be transformations in reporting in order to send nanotime. - */ -class Time +final class SpanBuilder implements \OpenTelemetry\API\Trace\SpanBuilderInterface { + /** @param non-empty-string $spanName */ + public function __construct(string $spanName, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, \OpenTelemetry\SDK\Trace\TracerSharedState $tracerSharedState) + { + } /** - * @return int + * @inheritDoc */ - public static function now() + public function setParent($context) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanBuilderInterface { } /** - * @return int + * @inheritDoc */ - public static function fromMicrotime($microtime) + public function setStartTimestamp(int $timestampNanos) : \OpenTelemetry\API\Trace\SpanBuilderInterface { } /** - * @param mixed $time - * @return bool + * @inheritDoc */ - public static function isValid($time) + public function setSpanKind(int $spanKind) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function startSpan() : \OpenTelemetry\API\Trace\SpanInterface { } } -interface Transport +namespace DDTrace\OpenTelemetry\API\Trace; + +final class SpanContext implements \OpenTelemetry\API\Trace\SpanContextInterface { /** - * @param TracerInterface $tracer + * @inheritDoc */ - public function send(\DDTrace\Contracts\Tracer $tracer); + public function getTraceId() : string + { + } + public function getTraceIdBinary() : string + { + } /** - * @param string $key - * @param string $value - * @return void + * @inheritDoc */ - public function setHeader($key, $value); -} -namespace DDTrace\Transport; - -final class Internal implements \DDTrace\Transport -{ - public function send(\DDTrace\Contracts\Tracer $tracer) + public function getSpanId() : string { } - public function setHeader($key, $value) + public function getSpanIdBinary() : string + { + } + public function getTraceState() : ?\OpenTelemetry\API\Trace\TraceStateInterface + { + } + public function isSampled() : bool + { + } + public function isValid() : bool + { + } + public function isRemote() : bool + { + } + public function getTraceFlags() : int + { + } + /** @inheritDoc */ + public static function createFromRemoteParent(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function create(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function getInvalid() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public static function createFromLocalSpan(\DDTrace\SpanData $span, bool $sampled, ?string $traceId = null, ?string $spanId = null) { } } -namespace DDTrace\Contracts; +namespace DDTrace\Processing; /** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Span.php + * A span processor in charge of adding the trace analytics client config metric when appropriate. + * + * NOTE: this may be transformer into a filter for consistency with other tracers, but for now we did not implement + * any filtering functionality so giving it such name as of now might be misleading. */ -interface Span +final class TraceAnalyticsProcessor { /** - * @return string - */ - public function getOperationName(); - /** - * Yields the SpanContext for this Span. Note that the return value of - * Span::getContext() is still valid after a call to Span::finish(), as is - * a call to Span::getContext() after a call to Span::finish(). - * - * @return SpanContext - */ - public function getContext(); - /** - * Sets the end timestamp and finalizes Span state. - * - * With the exception of calls to getContext() (which are always allowed), - * finish() must be the last call made to any span instance, and to do - * otherwise leads to undefined behavior but not returning an exception. - * - * As an implementor, make sure you call {@see Tracer::deactivate()} - * otherwise new spans might try to be child of this one. - * - * If the span is already finished, a warning should be logged. - * - * @param float|int|\DateTimeInterface|null $finishTime if passing float or int - * it should represent the timestamp (including as many decimal places as you need) - * @return void - */ - public function finish($finishTime = null); - /** - * If the span is already finished, a warning should be logged. - * - * @param string $newOperationName - */ - public function overwriteOperationName($newOperationName); - /** - * Sets the span's resource name. - * - * @param string $resource - */ - public function setResource($resource); - /** - * Adds a tag to the span. - * - * If there is a pre-existing tag set for key, it is overwritten. - * - * As an implementor, consider using "standard tags" listed in {@see \DDTrace\Tags} - * - * If the span is already finished, a warning should be logged. - * - * @param string $key - * @param mixed $value - * @param boolean $setIfFinished - * @return void - */ - public function setTag($key, $value, $setIfFinished = false); - /** - * @param string $key - * @return string|null + * @param array $metrics + * @param bool|float $value */ - public function getTag($key); + public static function normalizeAnalyticsValue(&$metrics, $value) + { + } +} +namespace DDTrace; + +/** + * Propagator implementations should be able to inject and extract + * SpanContexts into an implementation specific carrier. + */ +interface Propagator +{ + const DEFAULT_BAGGAGE_HEADER_PREFIX = 'ot-baggage-'; + const DEFAULT_TRACE_ID_HEADER = 'x-datadog-trace-id'; + const DEFAULT_PARENT_ID_HEADER = 'x-datadog-parent-id'; + const DEFAULT_SAMPLING_PRIORITY_HEADER = 'x-datadog-sampling-priority'; + const DEFAULT_ORIGIN_HEADER = 'x-datadog-origin'; /** - * Adds a log record to the span in key => value format, key must be a string and tag must be either - * a string, a boolean value, or a numeric type. - * - * If the span is already finished, a warning should be logged. + * Inject takes the SpanContext and injects it into the carrier using + * an implementation specific method. * - * @param array $fields - * @param int|float|\DateTimeInterface $timestamp + * @param SpanContextInterface $spanContext + * @param array|\ArrayAccess $carrier * @return void */ - public function log(array $fields = [], $timestamp = null); + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier); /** - * Adds a baggage item to the SpanContext which is immutable so it is required to use - * SpanContext::withBaggageItem to get a new one. - * - * If the span is already finished, a warning should be logged. + * Extract returns the SpanContext from the given carrier using an + * implementation specific method. * - * @param string $key - * @param string $value - * @return void - */ - public function addBaggageItem($key, $value); - /** - * @param string $key - * @return string|null returns null when there is not a item under the provided key - */ - public function getBaggageItem($key); - /** - * @return array + * @param array|\ArrayAccess $carrier + * @return SpanContextInterface */ - public function getAllBaggageItems(); + public function extract($carrier); +} +namespace DDTrace\Log; + +trait LoggingTrait +{ /** - * Stores a Throwable object within the span tags. The error status is - * updated and the error.Error() string is included with a default tag key. - * If the Span has been finished, it will not be modified by this method. + * Emits a log message at debug level. * - * @param \Throwable|\Exception|bool|null $error - * @throws \InvalidArgumentException + * @param string $message + * @param array $context */ - public function setError($error); + protected static function logDebug($message, array $context = []) + { + } /** - * Stores an error message and type in the Span. + * Emits a log message at warning level. * * @param string $message - * @param string $type + * @param array $context */ - public function setRawError($message, $type); + protected static function logWarning($message, array $context = []) + { + } /** - * Tells whether or not this Span contains errors. + * Emits a log message at error level. * - * @return bool - */ - public function hasError(); - /** - * @return int - */ - public function getStartTime(); - /** - * @return int - */ - public function getDuration(); - /** - * @return string - */ - public function getTraceId(); - /** - * @return string - */ - public function getSpanId(); - /** - * @return null|string - */ - public function getParentId(); - /** - * @return string - */ - public function getResource(); - /** - * @return string - */ - public function getService(); - /** - * @return string|null + * @param string $message + * @param array $context */ - public function getType(); + protected static function logError($message, array $context = []) + { + } /** * @return bool */ - public function isFinished(); - /** - * @return array - */ - public function getAllTags(); + protected static function isLogDebugActive() + { + } +} +namespace DDTrace\Propagators; + +final class TextMap implements \DDTrace\Propagator +{ + use \DDTrace\Log\LoggingTrait; /** - * Tells whether or not the span has the provided tag. Note that there are no guarantees that the tag value is - * not empty. - * - * @param string $name - * @return bool + * @param Tracer $tracer */ - public function hasTag($name); + public function __construct(\DDTrace\Contracts\Tracer $tracer) + { + } /** - * Set a DD metric. - * - * @param string $key - * @param mixed $value + * {@inheritdoc} */ - public function setMetric($key, $value); + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier) + { + } /** - * @return array All the currently set metrics. + * {@inheritdoc} */ - public function getMetrics(); + public function extract($carrier) + { + } } -namespace DDTrace\Data; +namespace DDTrace\Contracts; /** - * Class Span - * @property string $operationName - * @property string $resource - * @property string $service - * @property string $type - * @property int $startTime - * @property int $duration - * @property array $tags - * @property array $metrics + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Scope.php */ -abstract class Span implements \DDTrace\Contracts\Span +/** + * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint. + * + * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a + * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an + * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given + * {@link Span} is scheduled and on the path. + */ +interface Scope { /** - * @var SpanContextData - */ - public $context; - /** - * @var bool + * Mark the end of the active period for the current thread and {@link Scope}, + * updating the {@link ScopeManager#active()} in the process. + * + * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined + * behavior. */ - public $hasError = false; + public function close(); /** - * @var \DDTrace\SpanData + * @return Span the {@link Span} that's been scoped by this {@link Scope} */ - protected $internalSpan; - public function &__get($name) - { - } - public function __set($name, $value) - { - } - public function __isset($name) - { - } + public function getSpan(); } namespace DDTrace; -class Span extends \DDTrace\Data\Span +final class Scope implements \DDTrace\Contracts\Scope { - use \DDTrace\Log\LoggingTrait; - public $internalSpan; - /** - * Span constructor. - * @param SpanData $internalSpan - * @param SpanContext $context - */ - public function __construct(\DDTrace\SpanData $internalSpan, \DDTrace\SpanContext $context) + public function __construct(\DDTrace\ScopeManager $scopeManager, \DDTrace\Contracts\Span $span, $finishSpanOnClose) { } /** * {@inheritdoc} */ - public function getTraceId() + public function close() { } /** * {@inheritdoc} + * + * @return SpanInterface */ - public function getSpanId() + public function getSpan() { } +} +namespace DDTrace\Contracts; + +/** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/ScopeManager.php + */ +/** + * Keeps track of the current active `Span`. + */ +interface ScopeManager +{ + const DEFAULT_FINISH_SPAN_ON_CLOSE = true; /** - * {@inheritdoc} + * Activates an `Span`, so that it is used as a parent when creating new spans. + * The implementation must keep track of the active spans sequence, so + * that previous spans can be resumed after a deactivation. + * + * @param Span $span the {@link Span} that should become the {@link #active()} + * @param bool $finishSpanOnClose whether span should automatically be finished + * when {@link Scope#close()} is called. Its default value is true. + * + * @return Scope instance to control the end of the active period for the {@link Span}. It is a + * programming error to neglect to call {@link Scope#close()} on the returned instance. */ - public function getParentId() - { - } + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE); /** - * {@inheritdoc} + * Return the currently active {@link Scope} which can be used to access the + * currently active {@link Scope#getSpan()}. + * + * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent + * (as {@link References#CHILD_OF} reference) of any + * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()} + * time rather than at {@link Tracer#buildSpan(String)} time. + * + * @return Scope|null */ - public function overwriteOperationName($operationName) - { - } + public function getActive(); /** - * {@inheritdoc} + * Closes all the current request root spans. Typically there only will be one. */ - public function getResource() + public function close(); +} +namespace DDTrace; + +final class ScopeManager implements \DDTrace\Contracts\ScopeManager +{ + public function __construct(\DDTrace\SpanContext $rootContext = null) { } /** * {@inheritdoc} + * @param Span|SpanInterface $span */ - public function getService() + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE) { } /** * {@inheritdoc} */ - public function getType() + public function getActive() { } - /** - * {@inheritdoc} - */ - public function getStartTime() + public function deactivate(\DDTrace\Scope $scope) { } - /** - * {@inheritdoc} - */ - public function getDuration() + /** @internal */ + public function getPrimaryRoot() { } - /** - * {@inheritdoc} - */ - public function setTag($key, $value, $setIfFinished = false) + /** @internal */ + public function getTopScope() { } /** - * {@inheritdoc} + * Closes all the current request root spans. Typically there only will be one. */ - public function getTag($key) + public function close() { } +} +namespace DDTrace\Contracts; + +/** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Span.php + */ +interface Span +{ /** - * {@inheritdoc} + * @return string */ - public function getAllTags() - { - } + public function getOperationName(); /** - * {@inheritdoc} + * Yields the SpanContext for this Span. Note that the return value of + * Span::getContext() is still valid after a call to Span::finish(), as is + * a call to Span::getContext() after a call to Span::finish(). + * + * @return SpanContext */ - public function hasTag($name) - { - } + public function getContext(); /** - * @param string $key - * @param mixed $value + * Sets the end timestamp and finalizes Span state. + * + * With the exception of calls to getContext() (which are always allowed), + * finish() must be the last call made to any span instance, and to do + * otherwise leads to undefined behavior but not returning an exception. + * + * As an implementor, make sure you call {@see Tracer::deactivate()} + * otherwise new spans might try to be child of this one. + * + * If the span is already finished, a warning should be logged. + * + * @param float|int|\DateTimeInterface|null $finishTime if passing float or int + * it should represent the timestamp (including as many decimal places as you need) + * @return void */ - public function setMetric($key, $value) - { - } + public function finish($finishTime = null); /** - * @return array + * If the span is already finished, a warning should be logged. + * + * @param string $newOperationName */ - public function getMetrics() - { - } + public function overwriteOperationName($newOperationName); /** - * {@inheritdoc} + * Sets the span's resource name. + * + * @param string $resource */ - public function setResource($resource) - { - } + public function setResource($resource); /** - * Stores a Throwable object within the span tags. The error status is - * updated and the error.Error() string is included with a default tag key. - * If the Span has been finished, it will not be modified by this method. + * Adds a tag to the span. * - * @param Throwable|Exception|bool|null $error - * @throws InvalidArgumentException + * If there is a pre-existing tag set for key, it is overwritten. + * + * As an implementor, consider using "standard tags" listed in {@see \DDTrace\Tags} + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param mixed $value + * @param boolean $setIfFinished + * @return void */ - public function setError($error) - { - } + public function setTag($key, $value, $setIfFinished = false); /** - * @param string $message - * @param string $type + * @param string $key + * @return string|null */ - public function setRawError($message, $type) - { - } - public function hasError() - { - } + public function getTag($key); /** - * {@inheritdoc} + * Adds a log record to the span in key => value format, key must be a string and tag must be either + * a string, a boolean value, or a numeric type. + * + * If the span is already finished, a warning should be logged. + * + * @param array $fields + * @param int|float|\DateTimeInterface $timestamp + * @return void */ - public function finish($finishTime = null) - { - } + public function log(array $fields = [], $timestamp = null); /** - * {@inheritdoc} + * Adds a baggage item to the SpanContext which is immutable so it is required to use + * SpanContext::withBaggageItem to get a new one. + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param string $value + * @return void */ - public function isFinished() - { - } + public function addBaggageItem($key, $value); /** - * {@inheritdoc} + * @param string $key + * @return string|null returns null when there is not a item under the provided key */ - public function getOperationName() - { - } + public function getBaggageItem($key); /** - * {@inheritdoc} + * @return array */ - public function getContext() - { - } + public function getAllBaggageItems(); /** - * {@inheritdoc} + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param \Throwable|\Exception|bool|null $error + * @throws \InvalidArgumentException */ - public function log(array $fields = [], $timestamp = null) - { - } + public function setError($error); + /** + * Stores an error message and type in the Span. + * + * @param string $message + * @param string $type + */ + public function setRawError($message, $type); /** - * {@inheritdoc} + * Tells whether or not this Span contains errors. + * + * @return bool */ - public function addBaggageItem($key, $value) - { - } + public function hasError(); /** - * {@inheritdoc} + * @return int */ - public function getBaggageItem($key) - { - } + public function getStartTime(); /** - * {@inheritdoc} + * @return int */ - public function getAllBaggageItems() - { - } - public function __destruct() - { - } -} -namespace DDTrace\Processing; - -/** - * A span processor in charge of adding the trace analytics client config metric when appropriate. - * - * NOTE: this may be transformer into a filter for consistency with other tracers, but for now we did not implement - * any filtering functionality so giving it such name as of now might be misleading. - */ -final class TraceAnalyticsProcessor -{ + public function getDuration(); /** - * @param array $metrics - * @param bool|float $value + * @return string */ - public static function normalizeAnalyticsValue(&$metrics, $value) - { - } -} -namespace OpenTelemetry\SDK\Trace; - -final class SpanBuilder implements \OpenTelemetry\API\Trace\SpanBuilderInterface -{ - /** @param non-empty-string $spanName */ - public function __construct(string $spanName, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, \OpenTelemetry\SDK\Trace\TracerSharedState $tracerSharedState) - { - } + public function getTraceId(); /** - * @inheritDoc + * @return string */ - public function setParent($context) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** @inheritDoc */ - public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** @inheritDoc */ - public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } + public function getSpanId(); /** - * @inheritDoc + * @return null|string */ - public function setStartTimestamp(int $timestampNanos) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } + public function getParentId(); /** - * @inheritDoc + * @return string */ - public function setSpanKind(int $spanKind) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } + public function getResource(); /** - * @inheritDoc + * @return string */ - public function startSpan() : \OpenTelemetry\API\Trace\SpanInterface - { - } -} -final class Span extends \OpenTelemetry\API\Trace\Span implements \OpenTelemetry\SDK\Trace\ReadWriteSpanInterface -{ + public function getService(); /** - * This method _MUST_ not be used directly. - * End users should use a {@see API\TracerInterface} in order to create spans. - * - * @param non-empty-string $name - * @psalm-param API\SpanKind::KIND_* $kind - * @param list $links - * - * @internal - * @psalm-internal OpenTelemetry + * @return string|null */ - public static function startSpan(\DDTrace\SpanData $span, \OpenTelemetry\API\Trace\SpanContextInterface $context, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, int $kind, \OpenTelemetry\API\Trace\SpanInterface $parentSpan, \OpenTelemetry\Context\ContextInterface $parentContext, \OpenTelemetry\SDK\Trace\SpanProcessorInterface $spanProcessor, \OpenTelemetry\SDK\Resource\ResourceInfo $resource, array $attributes, array $links, int $totalRecordedLinks, array $events, bool $isRemapped = true) : self - { - } - public function getName() : string - { - } + public function getType(); /** - * @inheritDoc + * @return bool */ - public function getContext() : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - public function getParentContext() : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - public function getInstrumentationScope() : \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface - { - } - public function hasEnded() : bool - { - } + public function isFinished(); /** - * @inheritDoc + * @return array */ - public function toSpanData() : \OpenTelemetry\SDK\Trace\SpanDataInterface - { - } + public function getAllTags(); /** - * @inheritDoc + * Tells whether or not the span has the provided tag. Note that there are no guarantees that the tag value is + * not empty. + * + * @param string $name + * @return bool */ - public function getDuration() : int - { - } + public function hasTag($name); /** - * @inheritDoc + * Set a DD metric. + * + * @param string $key + * @param mixed $value */ - public function getKind() : int - { - } + public function setMetric($key, $value); /** - * @inheritDoc + * @return array All the currently set metrics. */ - public function getAttribute(string $key) - { - } - public function getStartEpochNanos() : int - { - } - public function getTotalRecordedLinks() : int - { - } - public function getTotalRecordedEvents() : int - { - } + public function getMetrics(); +} +namespace DDTrace\Data; + +/** + * Class Span + * @property string $operationName + * @property string $resource + * @property string $service + * @property string $type + * @property int $startTime + * @property int $duration + * @property array $tags + * @property array $metrics + */ +abstract class Span implements \DDTrace\Contracts\Span +{ /** - * @inheritDoc + * @var SpanContextData */ - public function isRecording() : bool - { - } + public $context; /** - * @inheritDoc + * @var bool */ - public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanInterface - { - } + public $hasError = false; /** - * @inheritDoc + * @var \DDTrace\SpanData */ - public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanInterface + protected $internalSpan; + public function &__get($name) { } - /** - * @inheritDoc - */ - public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + public function __set($name, $value) { } - /** - * @inheritDoc - */ - public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanInterface + public function __isset($name) { } +} +namespace DDTrace; + +class Span extends \DDTrace\Data\Span +{ + use \DDTrace\Log\LoggingTrait; + public $internalSpan; /** - * @inheritDoc + * Span constructor. + * @param SpanData $internalSpan + * @param SpanContext $context */ - public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + public function __construct(\DDTrace\SpanData $internalSpan, \DDTrace\SpanContext $context) { } /** - * @inheritDoc + * {@inheritdoc} */ - public function updateName(string $name) : \OpenTelemetry\API\Trace\SpanInterface + public function getTraceId() { } /** - * @inheritDoc + * {@inheritdoc} */ - public function setStatus(string $code, string $description = null) : \OpenTelemetry\API\Trace\SpanInterface + public function getSpanId() { } /** - * @inheritDoc + * {@inheritdoc} */ - public function end(int $endEpochNanos = null) : void - { - } - public function endOTelSpan(int $endEpochNanos = null) : void - { - } - public function getResource() : \OpenTelemetry\SDK\Resource\ResourceInfo + public function getParentId() { } /** - * @internal - * @return SpanData + * {@inheritdoc} */ - public function getDDSpan() : \DDTrace\SpanData + public function overwriteOperationName($operationName) { } -} -namespace OpenTelemetry\Context; - -/** - * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#context - */ -final class Context implements \OpenTelemetry\Context\ContextInterface -{ - public static function createKey(string $key) : \OpenTelemetry\Context\ContextKeyInterface + /** + * {@inheritdoc} + */ + public function getResource() { } /** - * @param ContextStorageInterface&ExecutionContextAwareInterface $storage + * {@inheritdoc} */ - public static function setStorage(\OpenTelemetry\Context\ContextStorageInterface $storage) : void + public function getService() { } /** - * @return ContextStorageInterface&ExecutionContextAwareInterface + * {@inheritdoc} */ - public static function storage() : \OpenTelemetry\Context\ContextStorageInterface + public function getType() { } /** - * @param ContextInterface|false|null $context - * - * @internal OpenTelemetry + * {@inheritdoc} */ - public static function resolve($context, ?\OpenTelemetry\Context\ContextStorageInterface $contextStorage = null) : \OpenTelemetry\Context\ContextInterface + public function getStartTime() { } /** - * @internal + * {@inheritdoc} */ - public static function getRoot() : \OpenTelemetry\Context\ContextInterface + public function getDuration() { } - public static function getCurrent() : \OpenTelemetry\Context\ContextInterface + /** + * {@inheritdoc} + */ + public function setTag($key, $value, $setIfFinished = false) { } - public function activate() : \OpenTelemetry\Context\ScopeInterface + /** + * {@inheritdoc} + */ + public function getTag($key) { } - public function withContextValue(\OpenTelemetry\Context\ImplicitContextKeyedInterface $value) : \OpenTelemetry\Context\ContextInterface + /** + * {@inheritdoc} + */ + public function getAllTags() { } - public function with(\OpenTelemetry\Context\ContextKeyInterface $key, $value) : self + /** + * {@inheritdoc} + */ + public function hasTag($name) { } - public function get(\OpenTelemetry\Context\ContextKeyInterface $key) + /** + * @param string $key + * @param mixed $value + */ + public function setMetric($key, $value) { } -} -namespace DDTrace\OpenTelemetry; - -// Operation Name Conventions -class Convention -{ - public static function defaultOperationName(\DDTrace\SpanData $span) : string + /** + * @return array + */ + public function getMetrics() { } -} -namespace DDTrace\OpenTelemetry\API\Trace; - -final class SpanContext implements \OpenTelemetry\API\Trace\SpanContextInterface -{ /** - * @inheritDoc + * {@inheritdoc} */ - public function getTraceId() : string + public function setResource($resource) { } - public function getTraceIdBinary() : string + /** + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param Throwable|Exception|bool|null $error + * @throws InvalidArgumentException + */ + public function setError($error) { } /** - * @inheritDoc + * @param string $message + * @param string $type */ - public function getSpanId() : string + public function setRawError($message, $type) { } - public function getSpanIdBinary() : string + public function hasError() { } - public function getTraceState() : ?\OpenTelemetry\API\Trace\TraceStateInterface + /** + * {@inheritdoc} + */ + public function finish($finishTime = null) { } - public function isSampled() : bool + /** + * {@inheritdoc} + */ + public function isFinished() { } - public function isValid() : bool + /** + * {@inheritdoc} + */ + public function getOperationName() { } - public function isRemote() : bool + /** + * {@inheritdoc} + */ + public function getContext() { } - public function getTraceFlags() : int + /** + * {@inheritdoc} + */ + public function log(array $fields = [], $timestamp = null) { } - /** @inheritDoc */ - public static function createFromRemoteParent(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + /** + * {@inheritdoc} + */ + public function addBaggageItem($key, $value) { } - /** @inheritDoc */ - public static function create(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + /** + * {@inheritdoc} + */ + public function getBaggageItem($key) { } - /** @inheritDoc */ - public static function getInvalid() : \OpenTelemetry\API\Trace\SpanContextInterface + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() { } - public static function createFromLocalSpan(\DDTrace\SpanData $span, bool $sampled, ?string $traceId = null, ?string $spanId = null) + public function __destruct() { } } namespace DDTrace\Contracts; /** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Scope.php - */ -/** - * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint. + * SpanContext must be immutable in order to avoid complicated lifetime + * issues around Span finish and references. * - * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a - * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an - * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given - * {@link Span} is scheduled and on the path. + * Baggage items are key => value string pairs that apply to the given Span, + * its SpanContext, and all Spans which directly or transitively reference + * the local Span. That is, baggage items propagate in-band along with the + * trace itself. */ -interface Scope +interface SpanContext extends \IteratorAggregate { /** - * Mark the end of the active period for the current thread and {@link Scope}, - * updating the {@link ScopeManager#active()} in the process. + * Returns the value of a baggage item based on its key. If there is no + * value with such key it will return null. * - * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined - * behavior. + * @param string $key + * @return string|null */ - public function close(); + public function getBaggageItem($key); /** - * @return Span the {@link Span} that's been scoped by this {@link Scope} + * Creates a new SpanContext out of the existing one and the new key => value pair. + * + * @param string $key + * @param string $value + * @return SpanContext */ - public function getSpan(); + public function withBaggageItem($key, $value); + /** + * @return array + */ + public function getAllBaggageItems(); + /** + * Gets initial priority sampling, upon span creation + * + * @return int + */ + public function getPropagatedPrioritySampling(); + /** + * Sets initial priority sampling, to be consumed upon span creation + * + * @param int $propagatedPrioritySampling + */ + public function setPropagatedPrioritySampling($propagatedPrioritySampling); + /** + * Returns whether or not this context represents the root span for a specific host. + * + * @return bool + */ + public function isHostRoot(); + /** + * @return string + */ + public function getTraceId(); + /** + * @return string + */ + public function getSpanId(); + /** + * @return string|null + */ + public function getParentId(); + /** + * @return bool + */ + public function isDistributedTracingActivationContext(); } -namespace DDTrace; +namespace DDTrace\Data; -final class Scope implements \DDTrace\Contracts\Scope +abstract class SpanContext implements \DDTrace\Contracts\SpanContext { - public function __construct(\DDTrace\ScopeManager $scopeManager, \DDTrace\Contracts\Span $span, $finishSpanOnClose) - { - } /** - * {@inheritdoc} + * The unique integer (63-bit unsigned) ID of the trace containing this span. + * It is stored in decimal representation. + * + * @var string */ - public function close() - { - } + public $traceId; /** - * {@inheritdoc} + * The span integer (63-bit unsigned) ID. + * It is stored in devimal representation. * - * @return SpanInterface + * @var string */ - public function getSpan() - { - } -} -/** - * Propagator implementations should be able to inject and extract - * SpanContexts into an implementation specific carrier. - */ -interface Propagator -{ - const DEFAULT_BAGGAGE_HEADER_PREFIX = 'ot-baggage-'; - const DEFAULT_TRACE_ID_HEADER = 'x-datadog-trace-id'; - const DEFAULT_PARENT_ID_HEADER = 'x-datadog-parent-id'; - const DEFAULT_SAMPLING_PRIORITY_HEADER = 'x-datadog-sampling-priority'; - const DEFAULT_ORIGIN_HEADER = 'x-datadog-origin'; + public $spanId; /** - * Inject takes the SpanContext and injects it into the carrier using - * an implementation specific method. + * The span integer ID of the parent span. + * It is stored in decimal representation. + * + * @var string|null + */ + public $parentId; + /** + * Whether or not this SpanContext represent a distributed tracing remote context. + * When the Tracer::extract() extracts a span context because of distributed tracing then this property is true, + * otherwise is false. + * + * @var bool + */ + public $isDistributedTracingActivationContext; + /** + * Initial priority sampling, upon span creation * - * @param SpanContextInterface $spanContext - * @param array|\ArrayAccess $carrier - * @return void + * @var int */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier); + public $propagatedPrioritySampling; /** - * Extract returns the SpanContext from the given carrier using an - * implementation specific method. + * The origin of the distributed trace. * - * @param array|\ArrayAccess $carrier - * @return SpanContextInterface + * @var string|null */ - public function extract($carrier); + public $origin; + /** + * @var SpanContextInterface + */ + public $parentContext; + /** + * @var array + */ + public $baggageItems; } -namespace DDTrace\Propagators; +namespace DDTrace; -final class TextMap implements \DDTrace\Propagator +final class SpanContext extends \DDTrace\Data\SpanContext { - use \DDTrace\Log\LoggingTrait; + public function __construct($traceId, $spanId, $parentId = null, array $baggageItems = [], $isDistributedTracingActivationContext = false) + { + } + public static function createAsChild(\DDTrace\Contracts\SpanContext $parentContext, $startTime = null) + { + } + public static function createAsRoot(array $baggageItems = [], $startTime = null) + { + } /** - * @param Tracer $tracer + * {@inheritdoc} */ - public function __construct(\DDTrace\Contracts\Tracer $tracer) + public function getTraceId() { } /** * {@inheritdoc} */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier) + public function getSpanId() { } /** * {@inheritdoc} */ - public function extract($carrier) + public function getParentId() { } -} -namespace DDTrace\Contracts; - -/** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/ScopeManager.php - */ -/** - * Keeps track of the current active `Span`. - */ -interface ScopeManager -{ - const DEFAULT_FINISH_SPAN_ON_CLOSE = true; /** - * Activates an `Span`, so that it is used as a parent when creating new spans. - * The implementation must keep track of the active spans sequence, so - * that previous spans can be resumed after a deactivation. - * - * @param Span $span the {@link Span} that should become the {@link #active()} - * @param bool $finishSpanOnClose whether span should automatically be finished - * when {@link Scope#close()} is called. Its default value is true. - * - * @return Scope instance to control the end of the active period for the {@link Span}. It is a - * programming error to neglect to call {@link Scope#close()} on the returned instance. + * {@inheritdoc} */ - public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE); + #[\ReturnTypeWillChange] + public function getIterator() + { + } /** - * Return the currently active {@link Scope} which can be used to access the - * currently active {@link Scope#getSpan()}. - * - * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent - * (as {@link References#CHILD_OF} reference) of any - * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()} - * time rather than at {@link Tracer#buildSpan(String)} time. - * - * @return Scope|null + * {@inheritdoc} */ - public function getActive(); + public function getPropagatedPrioritySampling() + { + } /** - * Closes all the current request root spans. Typically there only will be one. + * {@inheritdoc} */ - public function close(); -} -namespace DDTrace; - -final class ScopeManager implements \DDTrace\Contracts\ScopeManager -{ - public function __construct(\DDTrace\SpanContext $rootContext = null) + public function setPropagatedPrioritySampling($propagatedPrioritySampling) { } /** * {@inheritdoc} - * @param Span|SpanInterface $span */ - public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE) + public function getBaggageItem($key) { } /** * {@inheritdoc} */ - public function getActive() + public function withBaggageItem($key, $value) { } - public function deactivate(\DDTrace\Scope $scope) + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() { } - /** @internal */ - public function getPrimaryRoot() + public function isEqual(\DDTrace\Contracts\SpanContext $spanContext) { } - /** @internal */ - public function getTopScope() + /** + * {@inheritdoc} + */ + public function isDistributedTracingActivationContext() { } /** - * Closes all the current request root spans. Typically there only will be one. + * {@inheritdoc} */ - public function close() + public function isHostRoot() { } } -namespace DDTrace\Contracts; - /** - * SpanContext must be immutable in order to avoid complicated lifetime - * issues around Span finish and references. - * - * Baggage items are key => value string pairs that apply to the given Span, - * its SpanContext, and all Spans which directly or transitively reference - * the local Span. That is, baggage items propagate in-band along with the - * trace itself. + * Although DataDog uses nanotime to report spans PHP does not support nanotime + * plus, nanotime is a uint64 which is not supported either. Microtime will be used + * and there will be transformations in reporting in order to send nanotime. */ -interface SpanContext extends \IteratorAggregate +class Time { /** - * Returns the value of a baggage item based on its key. If there is no - * value with such key it will return null. - * - * @param string $key - * @return string|null + * @return int */ - public function getBaggageItem($key); + public static function now() + { + } /** - * Creates a new SpanContext out of the existing one and the new key => value pair. - * - * @param string $key - * @param string $value - * @return SpanContext + * @return int */ - public function withBaggageItem($key, $value); + public static function fromMicrotime($microtime) + { + } /** - * @return array + * @param mixed $time + * @return bool */ - public function getAllBaggageItems(); + public static function isValid($time) + { + } +} +namespace DDTrace\Contracts; + +interface Tracer +{ /** - * Gets initial priority sampling, upon span creation + * Checks if Tracer is in limited mode. * - * @return int - */ - public function getPropagatedPrioritySampling(); - /** - * Sets initial priority sampling, to be consumed upon span creation + * Tracer needs to handle any operation even if its in limited mode, + * however users can opt not to use tracer when its in limited mode. * - * @param int $propagatedPrioritySampling + * @return bool */ - public function setPropagatedPrioritySampling($propagatedPrioritySampling); + public function limited(); /** - * Returns whether or not this context represents the root span for a specific host. + * Returns the current {@link ScopeManager}, which may be a noop but may not be null. * - * @return bool + * @return ScopeManager */ - public function isHostRoot(); + public function getScopeManager(); /** - * @return string + * Returns the active {@link Span}. This is a shorthand for + * Tracer::getScopeManager()->getActive()->getSpan(), + * and null will be returned if {@link Scope#active()} is null. + * + * @return Span|null */ - public function getTraceId(); + public function getActiveSpan(); /** - * @return string + * Starts a new span that is activated on a scope manager. + * + * It's also possible to not finish the {@see \DDTrace\Contracts\Span} when + * {@see \DDTrace\Contracts\Scope} context expires: + * + * $scope = $tracer->startActiveSpan('...', [ + * 'finish_span_on_close' => false, + * ]); + * $span = $scope->getSpan(); + * try { + * $span->setTag(Tags\HTTP_METHOD, 'GET'); + * // ... + * } finally { + * $scope->close(); + * } + * // $span->finish() is not called as part of Scope deactivation as + * // finish_span_on_close is false + * + * @param string $operationName + * @param array|StartSpanOptions $options Same as for startSpan() with + * aditional option of `finish_span_on_close` that enables finishing + * of span whenever a scope is closed. It is true by default. + * + * @return Scope A Scope that holds newly created Span and is activated on + * a ScopeManager. */ - public function getSpanId(); + public function startActiveSpan($operationName, $options = []); /** - * @return string|null + * Starts and returns a new span representing a unit of work. + * + * Whenever `child_of` reference is not passed then + * {@see \DDTrace\Contracts\ScopeManager::getActive()} span is used as `child_of` + * reference. In order to ignore implicit parent span pass in + * `ignore_active_span` option set to true. + * + * Starting a span with explicit parent: + * + * $tracer->startSpan('...', [ + * 'child_of' => $parentSpan, + * ]); + * + * @see \DDTrace\StartSpanOptions + * + * @param string $operationName + * @param array|StartSpanOptions $options See StartSpanOptions for + * available options. + * + * @return Span + * + * @throws InvalidSpanOption for invalid option + * @throws InvalidReferencesSet for invalid references set */ - public function getParentId(); + public function startSpan($operationName, $options = []); /** - * @return bool + * @param SpanContext $spanContext + * @param string $format + * @param mixed $carrier + * + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation */ - public function isDistributedTracingActivationContext(); -} -namespace DDTrace\Data; - -abstract class SpanContext implements \DDTrace\Contracts\SpanContext -{ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier); /** - * The unique integer (63-bit unsigned) ID of the trace containing this span. - * It is stored in decimal representation. + * @param string $format + * @param mixed $carrier + * @return SpanContext|null * - * @var string + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation */ - public $traceId; + public function extract($format, $carrier); /** - * The span integer (63-bit unsigned) ID. - * It is stored in devimal representation. + * Allow tracer to send span data to be instrumented. * - * @var string + * This method might not be needed depending on the tracing implementation + * but one should make sure this method is called after the request is delivered + * to the client. + * + * As an implementor, a good idea would be to use {@see register_shutdown_function} + * or {@see fastcgi_finish_request} in order to not to delay the end of the request + * to the client. */ - public $spanId; + public function flush(); /** - * The span integer ID of the parent span. - * It is stored in decimal representation. - * - * @var string|null + * @param mixed $prioritySampling */ - public $parentId; + public function setPrioritySampling($prioritySampling); /** - * Whether or not this SpanContext represent a distributed tracing remote context. - * When the Tracer::extract() extracts a span context because of distributed tracing then this property is true, - * otherwise is false. - * - * @var bool + * @return int|null */ - public $isDistributedTracingActivationContext; + public function getPrioritySampling(); /** - * Initial priority sampling, upon span creation + * This behaves just like Tracer::startActiveSpan(), but it saves the Scope instance + * on the tracer to be accessed later by Tracer::getRootScope(). * - * @var int + * @param string $operationName + * @param array $options + * @return Scope */ - public $propagatedPrioritySampling; + public function startRootSpan($operationName, $options = []); /** - * The origin of the distributed trace. + * @return Scope|null + */ + public function getRootScope(); + /** + * Returns the root span or null and never throws an exception. * - * @var string|null + * @return Span|null */ - public $origin; + public function getSafeRootSpan(); /** - * @var SpanContextInterface + * Returns the entire trace encoded as a plain-old PHP array. + * + * @return array */ - public $parentContext; + public function getTracesAsArray(); /** - * @var array + * Returns the count of currently stored traces + * + * @return int */ - public $baggageItems; + public function getTracesCount(); } namespace DDTrace; -final class SpanContext extends \DDTrace\Data\SpanContext +final class Tracer implements \DDTrace\Contracts\Tracer { - public function __construct($traceId, $spanId, $parentId = null, array $baggageItems = [], $isDistributedTracingActivationContext = false) + use \DDTrace\Log\LoggingTrait; + /** + * @param Transport $transport + * @param Propagator[] $propagators + * @param array $config + */ + public function __construct(\DDTrace\Transport $transport = null, array $propagators = null, array $config = []) { } - public static function createAsChild(\DDTrace\Contracts\SpanContext $parentContext, $startTime = null) + public function limited() { } - public static function createAsRoot(array $baggageItems = [], $startTime = null) + /** + * Resets this tracer to its original state. + */ + public function reset() { } /** - * {@inheritdoc} + * @return Tracer */ - public function getTraceId() + public static function noop() { } /** * {@inheritdoc} */ - public function getSpanId() + public function startSpan($operationName, $options = []) { } /** * {@inheritdoc} */ - public function getParentId() + public function startRootSpan($operationName, $options = []) { } /** * {@inheritdoc} */ - #[\ReturnTypeWillChange] - public function getIterator() + public function getRootScope() { } /** * {@inheritdoc} */ - public function getPropagatedPrioritySampling() + public function startActiveSpan($operationName, $options = []) { } /** * {@inheritdoc} */ - public function setPropagatedPrioritySampling($propagatedPrioritySampling) + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier) { } /** * {@inheritdoc} */ - public function getBaggageItem($key) + public function extract($format, $carrier) { } /** - * {@inheritdoc} + * @return void */ - public function withBaggageItem($key, $value) + public function flush() { } /** * {@inheritdoc} */ - public function getAllBaggageItems() - { - } - public function isEqual(\DDTrace\Contracts\SpanContext $spanContext) + public function getScopeManager() { } /** - * {@inheritdoc} + * @return null|Span */ - public function isDistributedTracingActivationContext() + public function getActiveSpan() { } /** * {@inheritdoc} */ - public function isHostRoot() + public function getTracesAsArray() + { + } + public function addUrlAsResourceNameToSpan(\DDTrace\Contracts\Span $span) { } -} -class Type -{ - const CACHE = 'cache'; - const HTTP_CLIENT = 'http'; - const WEB_SERVLET = 'web'; - const CLI = 'cli'; - const SQL = 'sql'; - const MESSAGE_CONSUMER = 'queue'; - const MESSAGE_PRODUCER = 'queue'; - const CASSANDRA = 'cassandra'; - const ELASTICSEARCH = 'elasticsearch'; - const MEMCACHED = 'memcached'; - const MONGO = 'mongodb'; - const OPENAI = 'openai'; - const REDIS = 'redis'; - const SYSTEM = 'system'; -} -class Tag -{ - // Generic - const ENV = 'env'; - const SPAN_TYPE = 'span.type'; - const SPAN_KIND = 'span.kind'; - const SPAN_KIND_VALUE_SERVER = 'server'; - const SPAN_KIND_VALUE_CLIENT = 'client'; - const SPAN_KIND_VALUE_PRODUCER = 'producer'; - const SPAN_KIND_VALUE_CONSUMER = 'consumer'; - const SPAN_KIND_VALUE_INTERNAL = 'internal'; - const COMPONENT = 'component'; - const SERVICE_NAME = 'service.name'; - const MANUAL_KEEP = 'manual.keep'; - const MANUAL_DROP = 'manual.drop'; - const PID = 'process_id'; - const RESOURCE_NAME = 'resource.name'; - const DB_STATEMENT = 'sql.query'; - const ERROR = 'error'; - const ERROR_MSG = 'error.message'; - // string representing the error message - const ERROR_TYPE = 'error.type'; - // string representing the type of the error - const ERROR_STACK = 'error.stack'; - // human readable version of the stack - const HTTP_METHOD = 'http.method'; - const HTTP_ROUTE = 'http.route'; - const HTTP_STATUS_CODE = 'http.status_code'; - const HTTP_URL = 'http.url'; - const HTTP_VERSION = 'http.version'; - const LOG_EVENT = 'event'; - const LOG_ERROR = 'error'; - const LOG_ERROR_OBJECT = 'error.object'; - const LOG_MESSAGE = 'message'; - const LOG_STACK = 'stack'; - const NETWORK_DESTINATION_NAME = 'network.destination.name'; - const TARGET_HOST = 'out.host'; - const TARGET_PORT = 'out.port'; - const BYTES_OUT = 'net.out.bytes'; - const ANALYTICS_KEY = '_dd1.sr.eausr'; - const HOSTNAME = '_dd.hostname'; - const ORIGIN = '_dd.origin'; - const VERSION = 'version'; - const SERVICE_VERSION = 'service.version'; - // OpenTelemetry compatible tag - // Elasticsearch - const ELASTICSEARCH_BODY = 'elasticsearch.body'; - const ELASTICSEARCH_METHOD = 'elasticsearch.method'; - const ELASTICSEARCH_PARAMS = 'elasticsearch.params'; - const ELASTICSEARCH_URL = 'elasticsearch.url'; - // Database - const DB_NAME = 'db.name'; - const DB_CHARSET = 'db.charset'; - const DB_INSTANCE = 'db.instance'; - const DB_TYPE = 'db.type'; - const DB_SYSTEM = 'db.system'; - const DB_ROW_COUNT = 'db.row_count'; - const DB_STMT = 'db.statement'; - const DB_USER = 'db.user'; - // Laravel Queue - const LARAVELQ_ATTEMPTS = 'messaging.laravel.attempts'; - const LARAVELQ_BATCH_ID = 'messaging.laravel.batch_id'; - const LARAVELQ_CONNECTION = 'messaging.laravel.connection'; - const LARAVELQ_MAX_TRIES = 'messaging.laravel.max_tries'; - const LARAVELQ_NAME = 'messaging.laravel.name'; - const LARAVELQ_TIMEOUT = 'messaging.laravel.timeout'; - // MongoDB - const MONGODB_BSON_ID = 'mongodb.bson.id'; - const MONGODB_COLLECTION = 'mongodb.collection'; - const MONGODB_DATABASE = 'mongodb.db'; - const MONGODB_PROFILING_LEVEL = 'mongodb.profiling_level'; - const MONGODB_READ_PREFERENCE = 'mongodb.read_preference'; - const MONGODB_SERVER = 'mongodb.server'; - const MONGODB_TIMEOUT = 'mongodb.timeout'; - const MONGODB_QUERY = 'mongodb.query'; - // REDIS - const REDIS_RAW_COMMAND = 'redis.raw_command'; - // Message Queue - const MQ_SYSTEM = 'messaging.system'; - const MQ_DESTINATION = 'messaging.destination'; - const MQ_DESTINATION_KIND = 'messaging.destination_kind'; - const MQ_TEMP_DESTINATION = 'messaging.temp_destination'; - const MQ_PROTOCOL = 'messaging.protocol'; - const MQ_PROTOCOL_VERSION = 'messaging.protocol_version'; - const MQ_URL = 'messaging.url'; - const MQ_MESSAGE_ID = 'messaging.message_id'; - const MQ_CONVERSATION_ID = 'messaging.conversation_id'; - const MQ_MESSAGE_PAYLOAD_SIZE = 'messaging.message_payload_size_bytes'; - const MQ_OPERATION = 'messaging.operation'; - const MQ_CONSUMER_ID = 'messaging.consumer_id'; - // RabbitMQ - const RABBITMQ_DELIVERY_MODE = 'messaging.rabbitmq.delivery_mode'; - const RABBITMQ_EXCHANGE = 'messaging.rabbitmq.exchange'; - const RABBITMQ_ROUTING_KEY = 'messaging.rabbitmq.routing_key'; - // Exec - const EXEC_CMDLINE_EXEC = 'cmd.exec'; - const EXEC_CMDLINE_SHELL = 'cmd.shell'; - const EXEC_TRUNCATED = 'cmd.truncated'; - const EXEC_EXIT_CODE = 'cmd.exit_code'; -} -final class Reference -{ /** - * A Span may be the ChildOf a parent Span. In a ChildOf reference, - * the parent Span depends on the child Span in some capacity. + * @param mixed $prioritySampling */ - const CHILD_OF = 'child_of'; + public function setPrioritySampling($prioritySampling) + { + } /** - * Some parent Spans do not depend in any way on the result of their - * child Spans. In these cases, we say merely that the child Span - * FollowsFrom the parent Span in a causal sense. + * {@inheritdoc} */ - const FOLLOWS_FROM = 'follows_from'; + public function getPrioritySampling() + { + } /** - * @param SpanContextInterface|SpanInterface $context - * @param string $type - * @throws InvalidReferenceArgument on empty type - * @return Reference when context is invalid + * Returns the root span or null and never throws an exception. + * + * @return SpanInterface|null */ - public static function create($type, $context) + public function getSafeRootSpan() { } /** - * @return SpanContextInterface + * @return string */ - public function getContext() + public static function version() { } /** - * Checks whether a Reference is of one type. - * - * @param string $type the type for the reference - * @return bool + * {@inheritdoc} */ - public function isType($type) + public function getTracesCount() { } } -namespace DDTrace\Sampling; - -class PrioritySampling +interface Transport { - // The Agent will drop the trace, as instructed by any mechanism that is not the sampler. - const USER_REJECT = -1; - // Automatic sampling decision. The Agent should drop the trace. - const AUTO_REJECT = 0; - // Automatic sampling decision. The Agent should keep the trace. - const AUTO_KEEP = 1; - // The Agent should keep the trace, as instructed by any mechanism that is not the sampler. - // The backend will only apply sampling if above maximum volume allowed. - const USER_KEEP = 2; - // It was not possible to parse - const UNKNOWN = null; /** - * @param mixed|string $value - * @return int|null + * @param TracerInterface $tracer */ - public static function parse($value) + public function send(\DDTrace\Contracts\Tracer $tracer); + /** + * @param string $key + * @param string $value + * @return void + */ + public function setHeader($key, $value); +} +namespace DDTrace\Transport; + +final class Internal implements \DDTrace\Transport +{ + public function send(\DDTrace\Contracts\Tracer $tracer) + { + } + public function setHeader($key, $value) { } } @@ -1677,28 +1501,6 @@ public static function forInvalidContext($context) { } } -/** - * Thrown when trying to inject or extract in an invalid format - */ -final class UnsupportedFormat extends \UnexpectedValueException -{ - /** - * @param string $format - * @return UnsupportedFormat - */ - public static function forFormat($format) - { - } -} -final class InvalidSpanArgument extends \InvalidArgumentException -{ - public static function forTagKey($key) - { - } - public static function forError($error) - { - } -} /** * Thrown when a reference has more than one parent in the SpanOptions */ @@ -1718,6 +1520,15 @@ public static function forMoreThanOneParent() { } } +final class InvalidSpanArgument extends \InvalidArgumentException +{ + public static function forTagKey($key) + { + } + public static function forError($error) + { + } +} /** * Thrown when passing an invalid option on Span creation */ @@ -1795,8 +1606,65 @@ public static function forIgnoreActiveSpan($value) { } } +/** + * Thrown when trying to inject or extract in an invalid format + */ +final class UnsupportedFormat extends \UnexpectedValueException +{ + /** + * @param string $format + * @return UnsupportedFormat + */ + public static function forFormat($format) + { + } +} namespace DDTrace; +class Format +{ + /** + * Used a (single) arbitrary binary blob representing a SpanContext + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `string`. + */ + const BINARY = 'binary'; + /** + * Used for an arbitrary string-to-string map with an unrestricted character set for both keys and values + * + * Unlike `HTTP_HEADERS`, the `TEXT_MAP` format does not restrict the key or + * value character sets in any way. + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + */ + const TEXT_MAP = 'text_map'; + /** + * Used for a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. + * In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly + * recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. + * + * Unlike `TEXT_MAP`, the `HTTP_HEADERS` format requires that the keys and values be valid as HTTP headers as-is + * (i.e., character casing may be unstable and special characters are disallowed in keys, values should be + * URL-escaped, etc). + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + * + * For example, Tracer::inject(): + * + * $headers = [] + * $tracer->inject($span->getContext(), Format::HTTP_HEADERS, $headers) + * $request = new GuzzleHttp\Psr7\Request($uri, $body, $headers); + * + * Or Tracer::extract(): + * + * $headers = $request->getHeaders() + * $clientContext = $tracer->extract(Formats::HTTP_HEADERS, $headers) + * + * @see http://www.php-fig.org/psr/psr-7/#12-http-headers + * @see http://php.net/manual/en/function.getallheaders.php + */ + const HTTP_HEADERS = 'http_headers'; +} final class GlobalTracer { /** @@ -1884,55 +1752,59 @@ public function normalize($url) namespace DDTrace\Log; /** - * A global logger holder. Can be configured to use a specific logger. If not configured, it returns a NullLogger. + * Defines logging methods as used in DDTrace code. */ -final class Logger +interface LoggerInterface { /** - * Sets the global logger instance. + * Logs a message at the debug level. * - * @param LoggerInterface $logger + * @param string $message + * @param array $context + * + * @return void */ - public static function set(\DDTrace\Log\LoggerInterface $logger) - { - } + public function debug($message, array $context = array()); /** - * Retrieves the global logger instance. If not set, it falls back to a NullLogger. + * Logs a warning at the debug level. * - * @return LoggerInterface + * @param string $message + * @param array $context + * + * @return void */ - public static function get() - { - } + public function warning($message, array $context = []); /** - * Reset the logger. + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void */ - public static function reset() - { - } + public function error($message, array $context = array()); + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level); } /** - * Known log levels. + * An abstract logger. */ -final class LogLevel +abstract class AbstractLogger implements \DDTrace\Log\LoggerInterface { /** - * Const list from https://www.php-fig.org/psr/psr-3/ + * @param string $level */ - const EMERGENCY = 'emergency'; - const ALERT = 'alert'; - const CRITICAL = 'critical'; - const ERROR = 'error'; - const WARNING = 'warning'; - const NOTICE = 'notice'; - const INFO = 'info'; - const DEBUG = 'debug'; + public function __construct($level) + { + } /** - * All the log levels. - * - * @return string[] + * @param string $level + * @return bool */ - public static function all() + public function isLevelActive($level) { } } @@ -2043,98 +1915,94 @@ public function customErrorHandler(int $code, string $msg) : bool } } /** - * Defines logging methods as used in DDTrace code. + * An implementation of the DDTrace\LoggerInterface that logs to the error_log. */ -interface LoggerInterface +class ErrorLogLogger extends \DDTrace\Log\AbstractLogger { + use \DDTrace\Log\InterpolateTrait; /** - * Logs a message at the debug level. + * Logs a debug message. Substitution is provided as specified in: + * https://www.php-fig.org/psr/psr-3/ * * @param string $message - * @param array $context - * - * @return void + * @param array $context */ - public function debug($message, array $context = array()); + public function debug($message, array $context = []) + { + } /** * Logs a warning at the debug level. * * @param string $message - * @param array $context + * @param array $context * * @return void */ - public function warning($message, array $context = []); + public function warning($message, array $context = []) + { + } /** * Logs a error at the debug level. * * @param string $message - * @param array $context + * @param array $context * * @return void */ - public function error($message, array $context = array()); - /** - * @param string $level - * @return bool - */ - public function isLevelActive($level); + public function error($message, array $context = []) + { + } } /** - * An abstract logger. + * Known log levels. */ -abstract class AbstractLogger implements \DDTrace\Log\LoggerInterface +final class LogLevel { /** - * @param string $level + * Const list from https://www.php-fig.org/psr/psr-3/ */ - public function __construct($level) - { - } + const EMERGENCY = 'emergency'; + const ALERT = 'alert'; + const CRITICAL = 'critical'; + const ERROR = 'error'; + const WARNING = 'warning'; + const NOTICE = 'notice'; + const INFO = 'info'; + const DEBUG = 'debug'; /** - * @param string $level - * @return bool + * All the log levels. + * + * @return string[] */ - public function isLevelActive($level) + public static function all() { } } /** - * An implementation of the DDTrace\LoggerInterface that logs to the error_log. + * A global logger holder. Can be configured to use a specific logger. If not configured, it returns a NullLogger. */ -class ErrorLogLogger extends \DDTrace\Log\AbstractLogger +final class Logger { - use \DDTrace\Log\InterpolateTrait; /** - * Logs a debug message. Substitution is provided as specified in: - * https://www.php-fig.org/psr/psr-3/ + * Sets the global logger instance. * - * @param string $message - * @param array $context + * @param LoggerInterface $logger */ - public function debug($message, array $context = []) + public static function set(\DDTrace\Log\LoggerInterface $logger) { } /** - * Logs a warning at the debug level. - * - * @param string $message - * @param array $context + * Retrieves the global logger instance. If not set, it falls back to a NullLogger. * - * @return void + * @return LoggerInterface */ - public function warning($message, array $context = []) + public static function get() { } /** - * Logs a error at the debug level. - * - * @param string $message - * @param array $context - * - * @return void + * Reset the logger. */ - public function error($message, array $context = []) + public static function reset() { } } @@ -2209,50 +2077,69 @@ public static function convert($wildcardPattern) } namespace DDTrace; -class Format +final class Reference { /** - * Used a (single) arbitrary binary blob representing a SpanContext - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `string`. + * A Span may be the ChildOf a parent Span. In a ChildOf reference, + * the parent Span depends on the child Span in some capacity. */ - const BINARY = 'binary'; + const CHILD_OF = 'child_of'; /** - * Used for an arbitrary string-to-string map with an unrestricted character set for both keys and values - * - * Unlike `HTTP_HEADERS`, the `TEXT_MAP` format does not restrict the key or - * value character sets in any way. - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + * Some parent Spans do not depend in any way on the result of their + * child Spans. In these cases, we say merely that the child Span + * FollowsFrom the parent Span in a causal sense. */ - const TEXT_MAP = 'text_map'; + const FOLLOWS_FROM = 'follows_from'; /** - * Used for a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. - * In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly - * recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. - * - * Unlike `TEXT_MAP`, the `HTTP_HEADERS` format requires that the keys and values be valid as HTTP headers as-is - * (i.e., character casing may be unstable and special characters are disallowed in keys, values should be - * URL-escaped, etc). - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. - * - * For example, Tracer::inject(): - * - * $headers = [] - * $tracer->inject($span->getContext(), Format::HTTP_HEADERS, $headers) - * $request = new GuzzleHttp\Psr7\Request($uri, $body, $headers); - * - * Or Tracer::extract(): - * - * $headers = $request->getHeaders() - * $clientContext = $tracer->extract(Formats::HTTP_HEADERS, $headers) + * @param SpanContextInterface|SpanInterface $context + * @param string $type + * @throws InvalidReferenceArgument on empty type + * @return Reference when context is invalid + */ + public static function create($type, $context) + { + } + /** + * @return SpanContextInterface + */ + public function getContext() + { + } + /** + * Checks whether a Reference is of one type. * - * @see http://www.php-fig.org/psr/psr-7/#12-http-headers - * @see http://php.net/manual/en/function.getallheaders.php + * @param string $type the type for the reference + * @return bool */ - const HTTP_HEADERS = 'http_headers'; + public function isType($type) + { + } +} +namespace DDTrace\Sampling; + +class PrioritySampling +{ + // The Agent will drop the trace, as instructed by any mechanism that is not the sampler. + const USER_REJECT = -1; + // Automatic sampling decision. The Agent should drop the trace. + const AUTO_REJECT = 0; + // Automatic sampling decision. The Agent should keep the trace. + const AUTO_KEEP = 1; + // The Agent should keep the trace, as instructed by any mechanism that is not the sampler. + // The backend will only apply sampling if above maximum volume allowed. + const USER_KEEP = 2; + // It was not possible to parse + const UNKNOWN = null; + /** + * @param mixed|string $value + * @return int|null + */ + public static function parse($value) + { + } } +namespace DDTrace; + final class StartSpanOptions { /** @@ -2302,4 +2189,121 @@ public function shouldFinishSpanOnClose() public function shouldIgnoreActiveSpan() { } +} +class Tag +{ + // Generic + const ENV = 'env'; + const SPAN_TYPE = 'span.type'; + const SPAN_KIND = 'span.kind'; + const SPAN_KIND_VALUE_SERVER = 'server'; + const SPAN_KIND_VALUE_CLIENT = 'client'; + const SPAN_KIND_VALUE_PRODUCER = 'producer'; + const SPAN_KIND_VALUE_CONSUMER = 'consumer'; + const SPAN_KIND_VALUE_INTERNAL = 'internal'; + const COMPONENT = 'component'; + const SERVICE_NAME = 'service.name'; + const MANUAL_KEEP = 'manual.keep'; + const MANUAL_DROP = 'manual.drop'; + const PID = 'process_id'; + const RESOURCE_NAME = 'resource.name'; + const DB_STATEMENT = 'sql.query'; + const ERROR = 'error'; + const ERROR_MSG = 'error.message'; + // string representing the error message + const ERROR_TYPE = 'error.type'; + // string representing the type of the error + const ERROR_STACK = 'error.stack'; + // human readable version of the stack + const HTTP_METHOD = 'http.method'; + const HTTP_ROUTE = 'http.route'; + const HTTP_STATUS_CODE = 'http.status_code'; + const HTTP_URL = 'http.url'; + const HTTP_VERSION = 'http.version'; + const LOG_EVENT = 'event'; + const LOG_ERROR = 'error'; + const LOG_ERROR_OBJECT = 'error.object'; + const LOG_MESSAGE = 'message'; + const LOG_STACK = 'stack'; + const NETWORK_DESTINATION_NAME = 'network.destination.name'; + const TARGET_HOST = 'out.host'; + const TARGET_PORT = 'out.port'; + const BYTES_OUT = 'net.out.bytes'; + const ANALYTICS_KEY = '_dd1.sr.eausr'; + const HOSTNAME = '_dd.hostname'; + const ORIGIN = '_dd.origin'; + const VERSION = 'version'; + const SERVICE_VERSION = 'service.version'; + // OpenTelemetry compatible tag + // Elasticsearch + const ELASTICSEARCH_BODY = 'elasticsearch.body'; + const ELASTICSEARCH_METHOD = 'elasticsearch.method'; + const ELASTICSEARCH_PARAMS = 'elasticsearch.params'; + const ELASTICSEARCH_URL = 'elasticsearch.url'; + // Database + const DB_NAME = 'db.name'; + const DB_CHARSET = 'db.charset'; + const DB_INSTANCE = 'db.instance'; + const DB_TYPE = 'db.type'; + const DB_SYSTEM = 'db.system'; + const DB_ROW_COUNT = 'db.row_count'; + const DB_STMT = 'db.statement'; + const DB_USER = 'db.user'; + // Laravel Queue + const LARAVELQ_ATTEMPTS = 'messaging.laravel.attempts'; + const LARAVELQ_BATCH_ID = 'messaging.laravel.batch_id'; + const LARAVELQ_CONNECTION = 'messaging.laravel.connection'; + const LARAVELQ_MAX_TRIES = 'messaging.laravel.max_tries'; + const LARAVELQ_NAME = 'messaging.laravel.name'; + const LARAVELQ_TIMEOUT = 'messaging.laravel.timeout'; + // MongoDB + const MONGODB_BSON_ID = 'mongodb.bson.id'; + const MONGODB_COLLECTION = 'mongodb.collection'; + const MONGODB_DATABASE = 'mongodb.db'; + const MONGODB_PROFILING_LEVEL = 'mongodb.profiling_level'; + const MONGODB_READ_PREFERENCE = 'mongodb.read_preference'; + const MONGODB_SERVER = 'mongodb.server'; + const MONGODB_TIMEOUT = 'mongodb.timeout'; + const MONGODB_QUERY = 'mongodb.query'; + // REDIS + const REDIS_RAW_COMMAND = 'redis.raw_command'; + // Message Queue + const MQ_SYSTEM = 'messaging.system'; + const MQ_DESTINATION = 'messaging.destination'; + const MQ_DESTINATION_KIND = 'messaging.destination_kind'; + const MQ_TEMP_DESTINATION = 'messaging.temp_destination'; + const MQ_PROTOCOL = 'messaging.protocol'; + const MQ_PROTOCOL_VERSION = 'messaging.protocol_version'; + const MQ_URL = 'messaging.url'; + const MQ_MESSAGE_ID = 'messaging.message_id'; + const MQ_CONVERSATION_ID = 'messaging.conversation_id'; + const MQ_MESSAGE_PAYLOAD_SIZE = 'messaging.message_payload_size_bytes'; + const MQ_OPERATION = 'messaging.operation'; + const MQ_CONSUMER_ID = 'messaging.consumer_id'; + // RabbitMQ + const RABBITMQ_DELIVERY_MODE = 'messaging.rabbitmq.delivery_mode'; + const RABBITMQ_EXCHANGE = 'messaging.rabbitmq.exchange'; + const RABBITMQ_ROUTING_KEY = 'messaging.rabbitmq.routing_key'; + // Exec + const EXEC_CMDLINE_EXEC = 'cmd.exec'; + const EXEC_CMDLINE_SHELL = 'cmd.shell'; + const EXEC_TRUNCATED = 'cmd.truncated'; + const EXEC_EXIT_CODE = 'cmd.exit_code'; +} +class Type +{ + const CACHE = 'cache'; + const HTTP_CLIENT = 'http'; + const WEB_SERVLET = 'web'; + const CLI = 'cli'; + const SQL = 'sql'; + const MESSAGE_CONSUMER = 'queue'; + const MESSAGE_PRODUCER = 'queue'; + const CASSANDRA = 'cassandra'; + const ELASTICSEARCH = 'elasticsearch'; + const MEMCACHED = 'memcached'; + const MONGO = 'mongodb'; + const OPENAI = 'openai'; + const REDIS = 'redis'; + const SYSTEM = 'system'; } \ No newline at end of file From bca7adb3c1cc144dcefb0296bb82ca382bdaa5fe Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Tue, 12 Nov 2024 16:11:38 +0100 Subject: [PATCH 18/23] style: naming consistency --- tooling/bin/generate-final-artifact.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index 5cbf982b77..476395052c 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -170,7 +170,7 @@ for architecture in "${architectures[@]}"; do done stub=" "$packages_build_dir/datadog_tracer.stubs.php" + echo -e "$stub" > "$packages_build_dir/datadog-tracer.stubs.php" ######################## # Final archives From 6cbcae814fcb618282a8001e252f280c2c329c6a Mon Sep 17 00:00:00 2001 From: Alexandre Choura <42672104+PROFeNoM@users.noreply.github.com> Date: Wed, 13 Nov 2024 14:34:01 +0100 Subject: [PATCH 19/23] fix: string interpretation Co-authored-by: Bob Weinand --- tooling/bin/generate-final-artifact.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tooling/bin/generate-final-artifact.sh b/tooling/bin/generate-final-artifact.sh index 476395052c..55565536d4 100755 --- a/tooling/bin/generate-final-artifact.sh +++ b/tooling/bin/generate-final-artifact.sh @@ -169,8 +169,8 @@ for architecture in "${architectures[@]}"; do mergedStubs+="$content" done - stub=" "$packages_build_dir/datadog-tracer.stubs.php" + stub=$' "$packages_build_dir/datadog-tracer.stubs.php" ######################## # Final archives From 71b4409c356e5c6a1fe1a374276d553f113dec41 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Thu, 14 Nov 2024 09:01:35 +0100 Subject: [PATCH 20/23] fix: Don't use semicolon namespaces --- src/ddtrace_php_api.stubs.php | 4502 +++++++++++++++--------------- tooling/stubs/CustomPrinter.php | 13 + tooling/stubs/generate-stubs.php | 3 +- 3 files changed, 2266 insertions(+), 2252 deletions(-) create mode 100644 tooling/stubs/CustomPrinter.php diff --git a/src/ddtrace_php_api.stubs.php b/src/ddtrace_php_api.stubs.php index 7f47753c13..63511f1e50 100644 --- a/src/ddtrace_php_api.stubs.php +++ b/src/ddtrace_php_api.stubs.php @@ -1,2309 +1,2309 @@ $links - * - * @internal - * @psalm-internal OpenTelemetry - */ - public static function startSpan(\DDTrace\SpanData $span, \OpenTelemetry\API\Trace\SpanContextInterface $context, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, int $kind, \OpenTelemetry\API\Trace\SpanInterface $parentSpan, \OpenTelemetry\Context\ContextInterface $parentContext, \OpenTelemetry\SDK\Trace\SpanProcessorInterface $spanProcessor, \OpenTelemetry\SDK\Resource\ResourceInfo $resource, array $attributes, array $links, int $totalRecordedLinks, array $events, bool $isRemapped = true) : self - { - } - public function getName() : string - { - } - /** - * @inheritDoc - */ - public function getContext() : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - public function getParentContext() : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - public function getInstrumentationScope() : \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface - { - } - public function hasEnded() : bool - { - } - /** - * @inheritDoc - */ - public function toSpanData() : \OpenTelemetry\SDK\Trace\SpanDataInterface - { - } - /** - * @inheritDoc - */ - public function getDuration() : int - { - } - /** - * @inheritDoc - */ - public function getKind() : int - { - } - /** - * @inheritDoc - */ - public function getAttribute(string $key) - { - } - public function getStartEpochNanos() : int - { - } - public function getTotalRecordedLinks() : int - { - } - public function getTotalRecordedEvents() : int - { - } - /** - * @inheritDoc - */ - public function isRecording() : bool - { - } - /** - * @inheritDoc - */ - public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function updateName(string $name) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function setStatus(string $code, string $description = null) : \OpenTelemetry\API\Trace\SpanInterface - { - } - /** - * @inheritDoc - */ - public function end(int $endEpochNanos = null) : void - { - } - public function endOTelSpan(int $endEpochNanos = null) : void - { - } - public function getResource() : \OpenTelemetry\SDK\Resource\ResourceInfo - { - } - /** - * @internal - * @return SpanData - */ - public function getDDSpan() : \DDTrace\SpanData - { - } -} -final class SpanBuilder implements \OpenTelemetry\API\Trace\SpanBuilderInterface -{ - /** @param non-empty-string $spanName */ - public function __construct(string $spanName, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, \OpenTelemetry\SDK\Trace\TracerSharedState $tracerSharedState) - { - } - /** - * @inheritDoc - */ - public function setParent($context) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** @inheritDoc */ - public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** @inheritDoc */ - public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** - * @inheritDoc - */ - public function setStartTimestamp(int $timestampNanos) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** - * @inheritDoc - */ - public function setSpanKind(int $spanKind) : \OpenTelemetry\API\Trace\SpanBuilderInterface - { - } - /** - * @inheritDoc - */ - public function startSpan() : \OpenTelemetry\API\Trace\SpanInterface - { - } -} -namespace DDTrace\OpenTelemetry\API\Trace; - -final class SpanContext implements \OpenTelemetry\API\Trace\SpanContextInterface -{ - /** - * @inheritDoc - */ - public function getTraceId() : string - { - } - public function getTraceIdBinary() : string - { - } - /** - * @inheritDoc - */ - public function getSpanId() : string - { - } - public function getSpanIdBinary() : string - { - } - public function getTraceState() : ?\OpenTelemetry\API\Trace\TraceStateInterface - { - } - public function isSampled() : bool - { - } - public function isValid() : bool - { - } - public function isRemote() : bool - { - } - public function getTraceFlags() : int - { - } - /** @inheritDoc */ - public static function createFromRemoteParent(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - /** @inheritDoc */ - public static function create(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - /** @inheritDoc */ - public static function getInvalid() : \OpenTelemetry\API\Trace\SpanContextInterface - { - } - public static function createFromLocalSpan(\DDTrace\SpanData $span, bool $sampled, ?string $traceId = null, ?string $spanId = null) - { - } -} -namespace DDTrace\Processing; - -/** - * A span processor in charge of adding the trace analytics client config metric when appropriate. - * - * NOTE: this may be transformer into a filter for consistency with other tracers, but for now we did not implement - * any filtering functionality so giving it such name as of now might be misleading. - */ -final class TraceAnalyticsProcessor -{ - /** - * @param array $metrics - * @param bool|float $value - */ - public static function normalizeAnalyticsValue(&$metrics, $value) - { - } -} -namespace DDTrace; - -/** - * Propagator implementations should be able to inject and extract - * SpanContexts into an implementation specific carrier. - */ -interface Propagator -{ - const DEFAULT_BAGGAGE_HEADER_PREFIX = 'ot-baggage-'; - const DEFAULT_TRACE_ID_HEADER = 'x-datadog-trace-id'; - const DEFAULT_PARENT_ID_HEADER = 'x-datadog-parent-id'; - const DEFAULT_SAMPLING_PRIORITY_HEADER = 'x-datadog-sampling-priority'; - const DEFAULT_ORIGIN_HEADER = 'x-datadog-origin'; - /** - * Inject takes the SpanContext and injects it into the carrier using - * an implementation specific method. - * - * @param SpanContextInterface $spanContext - * @param array|\ArrayAccess $carrier - * @return void - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier); - /** - * Extract returns the SpanContext from the given carrier using an - * implementation specific method. - * - * @param array|\ArrayAccess $carrier - * @return SpanContextInterface - */ - public function extract($carrier); -} -namespace DDTrace\Log; - -trait LoggingTrait -{ - /** - * Emits a log message at debug level. - * - * @param string $message - * @param array $context - */ - protected static function logDebug($message, array $context = []) - { - } - /** - * Emits a log message at warning level. - * - * @param string $message - * @param array $context - */ - protected static function logWarning($message, array $context = []) - { - } - /** - * Emits a log message at error level. - * - * @param string $message - * @param array $context - */ - protected static function logError($message, array $context = []) - { - } - /** - * @return bool - */ - protected static function isLogDebugActive() - { - } -} -namespace DDTrace\Propagators; - -final class TextMap implements \DDTrace\Propagator -{ - use \DDTrace\Log\LoggingTrait; - /** - * @param Tracer $tracer - */ - public function __construct(\DDTrace\Contracts\Tracer $tracer) - { - } - /** - * {@inheritdoc} - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier) - { - } - /** - * {@inheritdoc} - */ - public function extract($carrier) - { - } -} -namespace DDTrace\Contracts; - -/** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Scope.php - */ -/** - * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint. - * - * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a - * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an - * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given - * {@link Span} is scheduled and on the path. - */ -interface Scope -{ - /** - * Mark the end of the active period for the current thread and {@link Scope}, - * updating the {@link ScopeManager#active()} in the process. - * - * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined - * behavior. - */ - public function close(); - /** - * @return Span the {@link Span} that's been scoped by this {@link Scope} - */ - public function getSpan(); -} -namespace DDTrace; - -final class Scope implements \DDTrace\Contracts\Scope -{ - public function __construct(\DDTrace\ScopeManager $scopeManager, \DDTrace\Contracts\Span $span, $finishSpanOnClose) - { - } - /** - * {@inheritdoc} - */ - public function close() - { - } - /** - * {@inheritdoc} - * - * @return SpanInterface - */ - public function getSpan() - { - } -} -namespace DDTrace\Contracts; - -/** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/ScopeManager.php - */ -/** - * Keeps track of the current active `Span`. - */ -interface ScopeManager -{ - const DEFAULT_FINISH_SPAN_ON_CLOSE = true; - /** - * Activates an `Span`, so that it is used as a parent when creating new spans. - * The implementation must keep track of the active spans sequence, so - * that previous spans can be resumed after a deactivation. - * - * @param Span $span the {@link Span} that should become the {@link #active()} - * @param bool $finishSpanOnClose whether span should automatically be finished - * when {@link Scope#close()} is called. Its default value is true. - * - * @return Scope instance to control the end of the active period for the {@link Span}. It is a - * programming error to neglect to call {@link Scope#close()} on the returned instance. - */ - public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE); - /** - * Return the currently active {@link Scope} which can be used to access the - * currently active {@link Scope#getSpan()}. - * - * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent - * (as {@link References#CHILD_OF} reference) of any - * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()} - * time rather than at {@link Tracer#buildSpan(String)} time. - * - * @return Scope|null - */ - public function getActive(); - /** - * Closes all the current request root spans. Typically there only will be one. - */ - public function close(); -} -namespace DDTrace; - -final class ScopeManager implements \DDTrace\Contracts\ScopeManager -{ - public function __construct(\DDTrace\SpanContext $rootContext = null) - { - } - /** - * {@inheritdoc} - * @param Span|SpanInterface $span - */ - public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE) - { - } - /** - * {@inheritdoc} - */ - public function getActive() - { - } - public function deactivate(\DDTrace\Scope $scope) - { - } - /** @internal */ - public function getPrimaryRoot() - { - } - /** @internal */ - public function getTopScope() - { - } - /** - * Closes all the current request root spans. Typically there only will be one. - */ - public function close() - { - } -} -namespace DDTrace\Contracts; - -/** - * Ported from opentracing/opentracing - * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Span.php - */ -interface Span -{ - /** - * @return string - */ - public function getOperationName(); - /** - * Yields the SpanContext for this Span. Note that the return value of - * Span::getContext() is still valid after a call to Span::finish(), as is - * a call to Span::getContext() after a call to Span::finish(). - * - * @return SpanContext - */ - public function getContext(); - /** - * Sets the end timestamp and finalizes Span state. - * - * With the exception of calls to getContext() (which are always allowed), - * finish() must be the last call made to any span instance, and to do - * otherwise leads to undefined behavior but not returning an exception. - * - * As an implementor, make sure you call {@see Tracer::deactivate()} - * otherwise new spans might try to be child of this one. - * - * If the span is already finished, a warning should be logged. - * - * @param float|int|\DateTimeInterface|null $finishTime if passing float or int - * it should represent the timestamp (including as many decimal places as you need) - * @return void - */ - public function finish($finishTime = null); - /** - * If the span is already finished, a warning should be logged. - * - * @param string $newOperationName - */ - public function overwriteOperationName($newOperationName); - /** - * Sets the span's resource name. - * - * @param string $resource - */ - public function setResource($resource); - /** - * Adds a tag to the span. - * - * If there is a pre-existing tag set for key, it is overwritten. - * - * As an implementor, consider using "standard tags" listed in {@see \DDTrace\Tags} - * - * If the span is already finished, a warning should be logged. - * - * @param string $key - * @param mixed $value - * @param boolean $setIfFinished - * @return void - */ - public function setTag($key, $value, $setIfFinished = false); - /** - * @param string $key - * @return string|null - */ - public function getTag($key); - /** - * Adds a log record to the span in key => value format, key must be a string and tag must be either - * a string, a boolean value, or a numeric type. - * - * If the span is already finished, a warning should be logged. - * - * @param array $fields - * @param int|float|\DateTimeInterface $timestamp - * @return void - */ - public function log(array $fields = [], $timestamp = null); - /** - * Adds a baggage item to the SpanContext which is immutable so it is required to use - * SpanContext::withBaggageItem to get a new one. - * - * If the span is already finished, a warning should be logged. - * - * @param string $key - * @param string $value - * @return void - */ - public function addBaggageItem($key, $value); - /** - * @param string $key - * @return string|null returns null when there is not a item under the provided key - */ - public function getBaggageItem($key); - /** - * @return array - */ - public function getAllBaggageItems(); - /** - * Stores a Throwable object within the span tags. The error status is - * updated and the error.Error() string is included with a default tag key. - * If the Span has been finished, it will not be modified by this method. - * - * @param \Throwable|\Exception|bool|null $error - * @throws \InvalidArgumentException - */ - public function setError($error); - /** - * Stores an error message and type in the Span. - * - * @param string $message - * @param string $type - */ - public function setRawError($message, $type); - /** - * Tells whether or not this Span contains errors. - * - * @return bool - */ - public function hasError(); - /** - * @return int - */ - public function getStartTime(); - /** - * @return int - */ - public function getDuration(); - /** - * @return string - */ - public function getTraceId(); - /** - * @return string - */ - public function getSpanId(); - /** - * @return null|string - */ - public function getParentId(); - /** - * @return string - */ - public function getResource(); - /** - * @return string - */ - public function getService(); - /** - * @return string|null - */ - public function getType(); - /** - * @return bool - */ - public function isFinished(); - /** - * @return array - */ - public function getAllTags(); - /** - * Tells whether or not the span has the provided tag. Note that there are no guarantees that the tag value is - * not empty. - * - * @param string $name - * @return bool - */ - public function hasTag($name); - /** - * Set a DD metric. - * - * @param string $key - * @param mixed $value - */ - public function setMetric($key, $value); - /** - * @return array All the currently set metrics. - */ - public function getMetrics(); -} -namespace DDTrace\Data; - -/** - * Class Span - * @property string $operationName - * @property string $resource - * @property string $service - * @property string $type - * @property int $startTime - * @property int $duration - * @property array $tags - * @property array $metrics - */ -abstract class Span implements \DDTrace\Contracts\Span -{ - /** - * @var SpanContextData - */ - public $context; - /** - * @var bool - */ - public $hasError = false; - /** - * @var \DDTrace\SpanData - */ - protected $internalSpan; - public function &__get($name) - { - } - public function __set($name, $value) - { - } - public function __isset($name) - { - } -} -namespace DDTrace; - -class Span extends \DDTrace\Data\Span -{ - use \DDTrace\Log\LoggingTrait; - public $internalSpan; - /** - * Span constructor. - * @param SpanData $internalSpan - * @param SpanContext $context - */ - public function __construct(\DDTrace\SpanData $internalSpan, \DDTrace\SpanContext $context) - { - } - /** - * {@inheritdoc} - */ - public function getTraceId() - { - } - /** - * {@inheritdoc} - */ - public function getSpanId() - { - } - /** - * {@inheritdoc} - */ - public function getParentId() - { - } - /** - * {@inheritdoc} - */ - public function overwriteOperationName($operationName) - { - } - /** - * {@inheritdoc} - */ - public function getResource() - { - } - /** - * {@inheritdoc} - */ - public function getService() - { - } - /** - * {@inheritdoc} - */ - public function getType() - { - } - /** - * {@inheritdoc} - */ - public function getStartTime() - { - } - /** - * {@inheritdoc} - */ - public function getDuration() - { - } - /** - * {@inheritdoc} - */ - public function setTag($key, $value, $setIfFinished = false) - { - } - /** - * {@inheritdoc} - */ - public function getTag($key) - { - } - /** - * {@inheritdoc} - */ - public function getAllTags() - { - } - /** - * {@inheritdoc} - */ - public function hasTag($name) - { - } - /** - * @param string $key - * @param mixed $value - */ - public function setMetric($key, $value) - { - } - /** - * @return array - */ - public function getMetrics() - { - } - /** - * {@inheritdoc} - */ - public function setResource($resource) - { - } - /** - * Stores a Throwable object within the span tags. The error status is - * updated and the error.Error() string is included with a default tag key. - * If the Span has been finished, it will not be modified by this method. - * - * @param Throwable|Exception|bool|null $error - * @throws InvalidArgumentException - */ - public function setError($error) - { - } - /** - * @param string $message - * @param string $type - */ - public function setRawError($message, $type) - { - } - public function hasError() - { - } - /** - * {@inheritdoc} - */ - public function finish($finishTime = null) - { - } - /** - * {@inheritdoc} - */ - public function isFinished() - { - } - /** - * {@inheritdoc} - */ - public function getOperationName() - { - } - /** - * {@inheritdoc} - */ - public function getContext() - { - } - /** - * {@inheritdoc} - */ - public function log(array $fields = [], $timestamp = null) - { - } - /** - * {@inheritdoc} - */ - public function addBaggageItem($key, $value) - { - } - /** - * {@inheritdoc} - */ - public function getBaggageItem($key) - { - } - /** - * {@inheritdoc} - */ - public function getAllBaggageItems() - { - } - public function __destruct() - { - } -} -namespace DDTrace\Contracts; - -/** - * SpanContext must be immutable in order to avoid complicated lifetime - * issues around Span finish and references. - * - * Baggage items are key => value string pairs that apply to the given Span, - * its SpanContext, and all Spans which directly or transitively reference - * the local Span. That is, baggage items propagate in-band along with the - * trace itself. - */ -interface SpanContext extends \IteratorAggregate -{ - /** - * Returns the value of a baggage item based on its key. If there is no - * value with such key it will return null. - * - * @param string $key - * @return string|null - */ - public function getBaggageItem($key); - /** - * Creates a new SpanContext out of the existing one and the new key => value pair. - * - * @param string $key - * @param string $value - * @return SpanContext - */ - public function withBaggageItem($key, $value); - /** - * @return array - */ - public function getAllBaggageItems(); - /** - * Gets initial priority sampling, upon span creation - * - * @return int - */ - public function getPropagatedPrioritySampling(); - /** - * Sets initial priority sampling, to be consumed upon span creation - * - * @param int $propagatedPrioritySampling - */ - public function setPropagatedPrioritySampling($propagatedPrioritySampling); - /** - * Returns whether or not this context represents the root span for a specific host. - * - * @return bool - */ - public function isHostRoot(); - /** - * @return string - */ - public function getTraceId(); - /** - * @return string - */ - public function getSpanId(); - /** - * @return string|null - */ - public function getParentId(); - /** - * @return bool - */ - public function isDistributedTracingActivationContext(); -} -namespace DDTrace\Data; - -abstract class SpanContext implements \DDTrace\Contracts\SpanContext -{ - /** - * The unique integer (63-bit unsigned) ID of the trace containing this span. - * It is stored in decimal representation. - * - * @var string - */ - public $traceId; - /** - * The span integer (63-bit unsigned) ID. - * It is stored in devimal representation. - * - * @var string - */ - public $spanId; - /** - * The span integer ID of the parent span. - * It is stored in decimal representation. - * - * @var string|null - */ - public $parentId; - /** - * Whether or not this SpanContext represent a distributed tracing remote context. - * When the Tracer::extract() extracts a span context because of distributed tracing then this property is true, - * otherwise is false. - * - * @var bool - */ - public $isDistributedTracingActivationContext; - /** - * Initial priority sampling, upon span creation - * - * @var int - */ - public $propagatedPrioritySampling; - /** - * The origin of the distributed trace. - * - * @var string|null - */ - public $origin; - /** - * @var SpanContextInterface - */ - public $parentContext; - /** - * @var array - */ - public $baggageItems; -} -namespace DDTrace; - -final class SpanContext extends \DDTrace\Data\SpanContext -{ - public function __construct($traceId, $spanId, $parentId = null, array $baggageItems = [], $isDistributedTracingActivationContext = false) - { - } - public static function createAsChild(\DDTrace\Contracts\SpanContext $parentContext, $startTime = null) - { - } - public static function createAsRoot(array $baggageItems = [], $startTime = null) - { - } - /** - * {@inheritdoc} - */ - public function getTraceId() - { - } - /** - * {@inheritdoc} - */ - public function getSpanId() - { - } - /** - * {@inheritdoc} - */ - public function getParentId() - { - } - /** - * {@inheritdoc} - */ - #[\ReturnTypeWillChange] - public function getIterator() - { - } - /** - * {@inheritdoc} - */ - public function getPropagatedPrioritySampling() - { - } - /** - * {@inheritdoc} - */ - public function setPropagatedPrioritySampling($propagatedPrioritySampling) - { - } - /** - * {@inheritdoc} - */ - public function getBaggageItem($key) - { - } - /** - * {@inheritdoc} - */ - public function withBaggageItem($key, $value) - { - } - /** - * {@inheritdoc} - */ - public function getAllBaggageItems() - { - } - public function isEqual(\DDTrace\Contracts\SpanContext $spanContext) - { - } - /** - * {@inheritdoc} - */ - public function isDistributedTracingActivationContext() - { - } - /** - * {@inheritdoc} - */ - public function isHostRoot() - { - } -} -/** - * Although DataDog uses nanotime to report spans PHP does not support nanotime - * plus, nanotime is a uint64 which is not supported either. Microtime will be used - * and there will be transformations in reporting in order to send nanotime. - */ -class Time -{ - /** - * @return int - */ - public static function now() - { - } - /** - * @return int - */ - public static function fromMicrotime($microtime) - { - } - /** - * @param mixed $time - * @return bool - */ - public static function isValid($time) - { - } -} -namespace DDTrace\Contracts; - -interface Tracer -{ - /** - * Checks if Tracer is in limited mode. - * - * Tracer needs to handle any operation even if its in limited mode, - * however users can opt not to use tracer when its in limited mode. - * - * @return bool - */ - public function limited(); - /** - * Returns the current {@link ScopeManager}, which may be a noop but may not be null. - * - * @return ScopeManager - */ - public function getScopeManager(); - /** - * Returns the active {@link Span}. This is a shorthand for - * Tracer::getScopeManager()->getActive()->getSpan(), - * and null will be returned if {@link Scope#active()} is null. - * - * @return Span|null - */ - public function getActiveSpan(); - /** - * Starts a new span that is activated on a scope manager. - * - * It's also possible to not finish the {@see \DDTrace\Contracts\Span} when - * {@see \DDTrace\Contracts\Scope} context expires: - * - * $scope = $tracer->startActiveSpan('...', [ - * 'finish_span_on_close' => false, - * ]); - * $span = $scope->getSpan(); - * try { - * $span->setTag(Tags\HTTP_METHOD, 'GET'); - * // ... - * } finally { - * $scope->close(); - * } - * // $span->finish() is not called as part of Scope deactivation as - * // finish_span_on_close is false - * - * @param string $operationName - * @param array|StartSpanOptions $options Same as for startSpan() with - * aditional option of `finish_span_on_close` that enables finishing - * of span whenever a scope is closed. It is true by default. - * - * @return Scope A Scope that holds newly created Span and is activated on - * a ScopeManager. - */ - public function startActiveSpan($operationName, $options = []); - /** - * Starts and returns a new span representing a unit of work. - * - * Whenever `child_of` reference is not passed then - * {@see \DDTrace\Contracts\ScopeManager::getActive()} span is used as `child_of` - * reference. In order to ignore implicit parent span pass in - * `ignore_active_span` option set to true. - * - * Starting a span with explicit parent: - * - * $tracer->startSpan('...', [ - * 'child_of' => $parentSpan, - * ]); - * - * @see \DDTrace\StartSpanOptions - * - * @param string $operationName - * @param array|StartSpanOptions $options See StartSpanOptions for - * available options. - * - * @return Span - * - * @throws InvalidSpanOption for invalid option - * @throws InvalidReferencesSet for invalid references set - */ - public function startSpan($operationName, $options = []); - /** - * @param SpanContext $spanContext - * @param string $format - * @param mixed $carrier - * - * @see Formats - * - * @throws UnsupportedFormat when the format is not recognized by the tracer - * implementation - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier); - /** - * @param string $format - * @param mixed $carrier - * @return SpanContext|null - * - * @see Formats - * - * @throws UnsupportedFormat when the format is not recognized by the tracer - * implementation - */ - public function extract($format, $carrier); - /** - * Allow tracer to send span data to be instrumented. - * - * This method might not be needed depending on the tracing implementation - * but one should make sure this method is called after the request is delivered - * to the client. - * - * As an implementor, a good idea would be to use {@see register_shutdown_function} - * or {@see fastcgi_finish_request} in order to not to delay the end of the request - * to the client. - */ - public function flush(); - /** - * @param mixed $prioritySampling - */ - public function setPrioritySampling($prioritySampling); - /** - * @return int|null - */ - public function getPrioritySampling(); - /** - * This behaves just like Tracer::startActiveSpan(), but it saves the Scope instance - * on the tracer to be accessed later by Tracer::getRootScope(). - * - * @param string $operationName - * @param array $options - * @return Scope - */ - public function startRootSpan($operationName, $options = []); - /** - * @return Scope|null - */ - public function getRootScope(); - /** - * Returns the root span or null and never throws an exception. - * - * @return Span|null - */ - public function getSafeRootSpan(); - /** - * Returns the entire trace encoded as a plain-old PHP array. - * - * @return array - */ - public function getTracesAsArray(); - /** - * Returns the count of currently stored traces - * - * @return int - */ - public function getTracesCount(); -} -namespace DDTrace; - -final class Tracer implements \DDTrace\Contracts\Tracer -{ - use \DDTrace\Log\LoggingTrait; - /** - * @param Transport $transport - * @param Propagator[] $propagators - * @param array $config - */ - public function __construct(\DDTrace\Transport $transport = null, array $propagators = null, array $config = []) - { - } - public function limited() - { - } - /** - * Resets this tracer to its original state. - */ - public function reset() - { - } - /** - * @return Tracer - */ - public static function noop() - { - } - /** - * {@inheritdoc} - */ - public function startSpan($operationName, $options = []) - { - } - /** - * {@inheritdoc} - */ - public function startRootSpan($operationName, $options = []) - { - } - /** - * {@inheritdoc} - */ - public function getRootScope() - { - } - /** - * {@inheritdoc} - */ - public function startActiveSpan($operationName, $options = []) - { - } - /** - * {@inheritdoc} - */ - public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier) - { - } - /** - * {@inheritdoc} - */ - public function extract($format, $carrier) - { - } - /** - * @return void - */ - public function flush() - { - } - /** - * {@inheritdoc} - */ - public function getScopeManager() - { - } - /** - * @return null|Span - */ - public function getActiveSpan() - { - } - /** - * {@inheritdoc} - */ - public function getTracesAsArray() - { - } - public function addUrlAsResourceNameToSpan(\DDTrace\Contracts\Span $span) - { - } - /** - * @param mixed $prioritySampling - */ - public function setPrioritySampling($prioritySampling) - { - } - /** - * {@inheritdoc} - */ - public function getPrioritySampling() - { - } - /** - * Returns the root span or null and never throws an exception. - * - * @return SpanInterface|null - */ - public function getSafeRootSpan() - { - } - /** - * @return string - */ - public static function version() - { - } - /** - * {@inheritdoc} - */ - public function getTracesCount() - { - } -} -interface Transport -{ - /** - * @param TracerInterface $tracer - */ - public function send(\DDTrace\Contracts\Tracer $tracer); - /** - * @param string $key - * @param string $value - * @return void - */ - public function setHeader($key, $value); -} -namespace DDTrace\Transport; - -final class Internal implements \DDTrace\Transport -{ - public function send(\DDTrace\Contracts\Tracer $tracer) - { - } - public function setHeader($key, $value) - { - } -} -namespace DDTrace\Exceptions; - -/** - * Thrown when passing an invalid argument for a reference - */ -final class InvalidReferenceArgument extends \InvalidArgumentException -{ - /** - * @return InvalidReferenceArgument - */ - public static function forEmptyType() - { - } - /** - * @param mixed $context - * @return InvalidReferenceArgument - */ - public static function forInvalidContext($context) - { - } -} -/** - * Thrown when a reference has more than one parent in the SpanOptions - */ -final class InvalidReferencesSet extends \DomainException -{ - /** - * @param string $message - * @return InvalidReferencesSet - */ - public static function create($message) - { - } - /** - * @return InvalidReferencesSet - */ - public static function forMoreThanOneParent() - { - } -} -final class InvalidSpanArgument extends \InvalidArgumentException -{ - public static function forTagKey($key) - { - } - public static function forError($error) - { - } -} -/** - * Thrown when passing an invalid option on Span creation - */ -final class InvalidSpanOption extends \InvalidArgumentException -{ - /** - * @return InvalidSpanOption - */ - public static function forIncludingBothChildOfAndReferences() - { - } - /** - * @param mixed $reference - * @return InvalidSpanOption - */ - public static function forInvalidReference($reference) - { - } - /** - * @return InvalidSpanOption - */ - public static function forInvalidStartTime() - { - } - public static function forInvalidChildOf($childOfOption) - { - } - /** - * @param string $key - * @return InvalidSpanOption - */ - public static function forUnknownOption($key) - { - } - /** - * @param mixed $tag - * @return InvalidSpanOption - */ - public static function forInvalidTag($tag) - { - } - /** - * @param mixed $tagValue - * @return InvalidSpanOption - */ - public static function forInvalidTagValue($tagValue) - { - } - /** - * @param mixed $value - * @return InvalidSpanOption - */ - public static function forInvalidTags($value) - { - } - /** - * @param mixed $value - * @return InvalidSpanOption - */ - public static function forInvalidReferenceSet($value) - { - } - /** - * @param mixed $value - * @return InvalidSpanOption - */ - public static function forFinishSpanOnClose($value) - { - } - /** - * @param mixed $value - * @return InvalidSpanOption - */ - public static function forIgnoreActiveSpan($value) - { +namespace OpenTelemetry\Context { + /** + * @see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#context + */ + final class Context implements \OpenTelemetry\Context\ContextInterface + { + public static function createKey(string $key) : \OpenTelemetry\Context\ContextKeyInterface + { + } + /** + * @param ContextStorageInterface&ExecutionContextAwareInterface $storage + */ + public static function setStorage(\OpenTelemetry\Context\ContextStorageInterface $storage) : void + { + } + /** + * @return ContextStorageInterface&ExecutionContextAwareInterface + */ + public static function storage() : \OpenTelemetry\Context\ContextStorageInterface + { + } + /** + * @param ContextInterface|false|null $context + * + * @internal OpenTelemetry + */ + public static function resolve($context, ?\OpenTelemetry\Context\ContextStorageInterface $contextStorage = null) : \OpenTelemetry\Context\ContextInterface + { + } + /** + * @internal + */ + public static function getRoot() : \OpenTelemetry\Context\ContextInterface + { + } + public static function getCurrent() : \OpenTelemetry\Context\ContextInterface + { + } + public function activate() : \OpenTelemetry\Context\ScopeInterface + { + } + public function withContextValue(\OpenTelemetry\Context\ImplicitContextKeyedInterface $value) : \OpenTelemetry\Context\ContextInterface + { + } + public function with(\OpenTelemetry\Context\ContextKeyInterface $key, $value) : self + { + } + public function get(\OpenTelemetry\Context\ContextKeyInterface $key) + { + } } } -/** - * Thrown when trying to inject or extract in an invalid format - */ -final class UnsupportedFormat extends \UnexpectedValueException -{ - /** - * @param string $format - * @return UnsupportedFormat - */ - public static function forFormat($format) +namespace DDTrace\OpenTelemetry { + // Operation Name Conventions + class Convention { + public static function defaultOperationName(\DDTrace\SpanData $span) : string + { + } } } -namespace DDTrace; - -class Format -{ - /** - * Used a (single) arbitrary binary blob representing a SpanContext - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `string`. - */ - const BINARY = 'binary'; - /** - * Used for an arbitrary string-to-string map with an unrestricted character set for both keys and values - * - * Unlike `HTTP_HEADERS`, the `TEXT_MAP` format does not restrict the key or - * value character sets in any way. - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. - */ - const TEXT_MAP = 'text_map'; - /** - * Used for a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. - * In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly - * recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. - * - * Unlike `TEXT_MAP`, the `HTTP_HEADERS` format requires that the keys and values be valid as HTTP headers as-is - * (i.e., character casing may be unstable and special characters are disallowed in keys, values should be - * URL-escaped, etc). - * - * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. - * - * For example, Tracer::inject(): - * - * $headers = [] - * $tracer->inject($span->getContext(), Format::HTTP_HEADERS, $headers) - * $request = new GuzzleHttp\Psr7\Request($uri, $body, $headers); - * - * Or Tracer::extract(): - * - * $headers = $request->getHeaders() - * $clientContext = $tracer->extract(Formats::HTTP_HEADERS, $headers) - * - * @see http://www.php-fig.org/psr/psr-7/#12-http-headers - * @see http://php.net/manual/en/function.getallheaders.php - */ - const HTTP_HEADERS = 'http_headers'; -} -final class GlobalTracer -{ - /** - * GlobalTracer::set sets the [singleton] Tracer returned by get(). - * Those who use GlobalTracer (rather than directly manage a Tracer instance) - * should call GlobalTracer::set as early as possible in bootstrap, prior to - * start a new span. Prior to calling GlobalTracer::set, any Spans started - * via the `Tracer::startActiveSpan` (etc) globals are noops. - * - * @param TracerInterface $tracer - */ - public static function set(\DDTrace\Contracts\Tracer $tracer) - { - } - /** - * GlobalTracer::get returns the global singleton `Tracer` implementation. - * Before `GlobalTracer::set` is called, the `GlobalTracer::get` is a noop - * implementation that drops all data handed to it. - * - * @return TracerInterface - */ - public static function get() - { +namespace OpenTelemetry\SDK\Trace { + final class Span extends \OpenTelemetry\API\Trace\Span implements \OpenTelemetry\SDK\Trace\ReadWriteSpanInterface + { + /** + * This method _MUST_ not be used directly. + * End users should use a {@see API\TracerInterface} in order to create spans. + * + * @param non-empty-string $name + * @psalm-param API\SpanKind::KIND_* $kind + * @param list $links + * + * @internal + * @psalm-internal OpenTelemetry + */ + public static function startSpan(\DDTrace\SpanData $span, \OpenTelemetry\API\Trace\SpanContextInterface $context, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, int $kind, \OpenTelemetry\API\Trace\SpanInterface $parentSpan, \OpenTelemetry\Context\ContextInterface $parentContext, \OpenTelemetry\SDK\Trace\SpanProcessorInterface $spanProcessor, \OpenTelemetry\SDK\Resource\ResourceInfo $resource, array $attributes, array $links, int $totalRecordedLinks, array $events, bool $isRemapped = true) : self + { + } + public function getName() : string + { + } + /** + * @inheritDoc + */ + public function getContext() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public function getParentContext() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public function getInstrumentationScope() : \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface + { + } + public function hasEnded() : bool + { + } + /** + * @inheritDoc + */ + public function toSpanData() : \OpenTelemetry\SDK\Trace\SpanDataInterface + { + } + /** + * @inheritDoc + */ + public function getDuration() : int + { + } + /** + * @inheritDoc + */ + public function getKind() : int + { + } + /** + * @inheritDoc + */ + public function getAttribute(string $key) + { + } + public function getStartEpochNanos() : int + { + } + public function getTotalRecordedLinks() : int + { + } + public function getTotalRecordedEvents() : int + { + } + /** + * @inheritDoc + */ + public function isRecording() : bool + { + } + /** + * @inheritDoc + */ + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function updateName(string $name) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function setStatus(string $code, string $description = null) : \OpenTelemetry\API\Trace\SpanInterface + { + } + /** + * @inheritDoc + */ + public function end(int $endEpochNanos = null) : void + { + } + public function endOTelSpan(int $endEpochNanos = null) : void + { + } + public function getResource() : \OpenTelemetry\SDK\Resource\ResourceInfo + { + } + /** + * @internal + * @return SpanData + */ + public function getDDSpan() : \DDTrace\SpanData + { + } + } + final class SpanBuilder implements \OpenTelemetry\API\Trace\SpanBuilderInterface + { + /** @param non-empty-string $spanName */ + public function __construct(string $spanName, \OpenTelemetry\SDK\Common\Instrumentation\InstrumentationScopeInterface $instrumentationScope, \OpenTelemetry\SDK\Trace\TracerSharedState $tracerSharedState) + { + } + /** + * @inheritDoc + */ + public function setParent($context) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addLink(\OpenTelemetry\API\Trace\SpanContextInterface $context, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function addEvent(string $name, iterable $attributes = [], int $timestamp = null) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + public function recordException(\Throwable $exception, iterable $attributes = []) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttribute(string $key, $value) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** @inheritDoc */ + public function setAttributes(iterable $attributes) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function setStartTimestamp(int $timestampNanos) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function setSpanKind(int $spanKind) : \OpenTelemetry\API\Trace\SpanBuilderInterface + { + } + /** + * @inheritDoc + */ + public function startSpan() : \OpenTelemetry\API\Trace\SpanInterface + { + } } } -namespace DDTrace\Http; - -/** - * A utility class that provides methods to work on urls - */ -class Urls -{ - /** - * Inject URL replacement patterns using '*' and '$*' as wildcards - * The '*' wildcard will match one or more characters to be replaced with '?' - * The '$*' wildcard will match one or more characters without replacement - * - * @param string[] $patternsWithWildcards - */ - public function __construct(array $patternsWithWildcards = []) - { - } - /** - * Removes query string and fragment and user information from a url. - * - * @param string $url - * @param bool $dropUserInfo Optional. If `true`, removes the user information fragment instead of obfuscating it. - * Defaults to `false`. - */ - public static function sanitize($url, $dropUserInfo = false) - { - } - /** - * Extracts the hostname of a given URL - * - * @param string $url - * @return string - */ - public static function hostname($url) - { - } - /** - * Metadata keys must start with [a-zA-Z:] so IP addresses, - * for example, need to be prefixed with a valid character. - * - * Note: then name of this function is misleading, as it should actually be normalizeUrlForService(), but since this - * part of the public API, we keep it like this and discuss a future deprecation. - * - * @param string $url - * @return string - */ - public static function hostnameForTag($url) - { - } - /** - * Reduces cardinality of a url. - * - * @param string $url - * @return string - */ - public function normalize($url) - { +namespace DDTrace\OpenTelemetry\API\Trace { + final class SpanContext implements \OpenTelemetry\API\Trace\SpanContextInterface + { + /** + * @inheritDoc + */ + public function getTraceId() : string + { + } + public function getTraceIdBinary() : string + { + } + /** + * @inheritDoc + */ + public function getSpanId() : string + { + } + public function getSpanIdBinary() : string + { + } + public function getTraceState() : ?\OpenTelemetry\API\Trace\TraceStateInterface + { + } + public function isSampled() : bool + { + } + public function isValid() : bool + { + } + public function isRemote() : bool + { + } + public function getTraceFlags() : int + { + } + /** @inheritDoc */ + public static function createFromRemoteParent(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function create(string $traceId, string $spanId, int $traceFlags = \OpenTelemetry\API\Trace\TraceFlags::DEFAULT, ?\OpenTelemetry\API\Trace\TraceStateInterface $traceState = null) : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + /** @inheritDoc */ + public static function getInvalid() : \OpenTelemetry\API\Trace\SpanContextInterface + { + } + public static function createFromLocalSpan(\DDTrace\SpanData $span, bool $sampled, ?string $traceId = null, ?string $spanId = null) + { + } } } -namespace DDTrace\Log; - -/** - * Defines logging methods as used in DDTrace code. - */ -interface LoggerInterface -{ - /** - * Logs a message at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function debug($message, array $context = array()); - /** - * Logs a warning at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function warning($message, array $context = []); +namespace DDTrace\Processing { /** - * Logs a error at the debug level. - * - * @param string $message - * @param array $context + * A span processor in charge of adding the trace analytics client config metric when appropriate. * - * @return void - */ - public function error($message, array $context = array()); - /** - * @param string $level - * @return bool - */ - public function isLevelActive($level); -} -/** - * An abstract logger. - */ -abstract class AbstractLogger implements \DDTrace\Log\LoggerInterface -{ - /** - * @param string $level - */ - public function __construct($level) - { - } - /** - * @param string $level - * @return bool + * NOTE: this may be transformer into a filter for consistency with other tracers, but for now we did not implement + * any filtering functionality so giving it such name as of now might be misleading. */ - public function isLevelActive($level) + final class TraceAnalyticsProcessor { + /** + * @param array $metrics + * @param bool|float $value + */ + public static function normalizeAnalyticsValue(&$metrics, $value) + { + } } } -/** - * Provides methods to interpolate log messages. - */ -trait InterpolateTrait -{ - /** - * Interpolates context values into the message placeholders. Example code from: - * https://www.php-fig.org/psr/psr-3/ - * - * @param string $message - * @param array $context - * @return string - */ - public static function interpolate($message, array $context = []) - { +namespace DDTrace { + /** + * Propagator implementations should be able to inject and extract + * SpanContexts into an implementation specific carrier. + */ + interface Propagator + { + const DEFAULT_BAGGAGE_HEADER_PREFIX = 'ot-baggage-'; + const DEFAULT_TRACE_ID_HEADER = 'x-datadog-trace-id'; + const DEFAULT_PARENT_ID_HEADER = 'x-datadog-parent-id'; + const DEFAULT_SAMPLING_PRIORITY_HEADER = 'x-datadog-sampling-priority'; + const DEFAULT_ORIGIN_HEADER = 'x-datadog-origin'; + /** + * Inject takes the SpanContext and injects it into the carrier using + * an implementation specific method. + * + * @param SpanContextInterface $spanContext + * @param array|\ArrayAccess $carrier + * @return void + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier); + /** + * Extract returns the SpanContext from the given carrier using an + * implementation specific method. + * + * @param array|\ArrayAccess $carrier + * @return SpanContextInterface + */ + public function extract($carrier); } } -/** - * JSON logger that writes to a stream, with simple logs correlation support. - * Heavily inspired from Monolog's StreamHandler. - * @internal This logger is internal and can be removed without prior notice - */ -final class DatadogLogger -{ - use \DDTrace\Log\InterpolateTrait; - const DEFAULT_JSON_FLAGS = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRESERVE_ZERO_FRACTION | JSON_PARTIAL_OUTPUT_ON_ERROR; - public function __construct($stream = null, $mode = 'a') - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function emergency($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function alert($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function critical($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function error($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function warning($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function notice($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function info($message, array $context = []) - { - } - /** - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function debug($message, array $context = []) - { - } - /** - * @param string $level - * @param string|\Stringable $message - * @param array $context - * @return void - */ - public function log(string $level, $message, array $context = []) - { - } - public function customErrorHandler(int $code, string $msg) : bool - { +namespace DDTrace\Log { + trait LoggingTrait + { + /** + * Emits a log message at debug level. + * + * @param string $message + * @param array $context + */ + protected static function logDebug($message, array $context = []) + { + } + /** + * Emits a log message at warning level. + * + * @param string $message + * @param array $context + */ + protected static function logWarning($message, array $context = []) + { + } + /** + * Emits a log message at error level. + * + * @param string $message + * @param array $context + */ + protected static function logError($message, array $context = []) + { + } + /** + * @return bool + */ + protected static function isLogDebugActive() + { + } } } -/** - * An implementation of the DDTrace\LoggerInterface that logs to the error_log. - */ -class ErrorLogLogger extends \DDTrace\Log\AbstractLogger -{ - use \DDTrace\Log\InterpolateTrait; - /** - * Logs a debug message. Substitution is provided as specified in: - * https://www.php-fig.org/psr/psr-3/ - * - * @param string $message - * @param array $context - */ - public function debug($message, array $context = []) - { - } - /** - * Logs a warning at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function warning($message, array $context = []) - { - } - /** - * Logs a error at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function error($message, array $context = []) - { +namespace DDTrace\Propagators { + final class TextMap implements \DDTrace\Propagator + { + use \DDTrace\Log\LoggingTrait; + /** + * @param Tracer $tracer + */ + public function __construct(\DDTrace\Contracts\Tracer $tracer) + { + } + /** + * {@inheritdoc} + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, &$carrier) + { + } + /** + * {@inheritdoc} + */ + public function extract($carrier) + { + } } } -/** - * Known log levels. - */ -final class LogLevel -{ +namespace DDTrace\Contracts { /** - * Const list from https://www.php-fig.org/psr/psr-3/ + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Scope.php */ - const EMERGENCY = 'emergency'; - const ALERT = 'alert'; - const CRITICAL = 'critical'; - const ERROR = 'error'; - const WARNING = 'warning'; - const NOTICE = 'notice'; - const INFO = 'info'; - const DEBUG = 'debug'; /** - * All the log levels. + * A {@link Scope} formalizes the activation and deactivation of a {@link Span}, usually from a CPU standpoint. * - * @return string[] + * Many times a {@link Span} will be extant (in that {@link Span#finish()} has not been called) despite being in a + * non-runnable state from a CPU/scheduler standpoint. For instance, a {@link Span} representing the client side of an + * RPC will be unfinished but blocked on IO while the RPC is still outstanding. A {@link Scope} defines when a given + * {@link Span} is scheduled and on the path. */ - public static function all() + interface Scope { + /** + * Mark the end of the active period for the current thread and {@link Scope}, + * updating the {@link ScopeManager#active()} in the process. + * + * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined + * behavior. + */ + public function close(); + /** + * @return Span the {@link Span} that's been scoped by this {@link Scope} + */ + public function getSpan(); } } -/** - * A global logger holder. Can be configured to use a specific logger. If not configured, it returns a NullLogger. - */ -final class Logger -{ - /** - * Sets the global logger instance. - * - * @param LoggerInterface $logger - */ - public static function set(\DDTrace\Log\LoggerInterface $logger) - { - } - /** - * Retrieves the global logger instance. If not set, it falls back to a NullLogger. - * - * @return LoggerInterface - */ - public static function get() - { +namespace DDTrace { + final class Scope implements \DDTrace\Contracts\Scope + { + public function __construct(\DDTrace\ScopeManager $scopeManager, \DDTrace\Contracts\Span $span, $finishSpanOnClose) + { + } + /** + * {@inheritdoc} + */ + public function close() + { + } + /** + * {@inheritdoc} + * + * @return SpanInterface + */ + public function getSpan() + { + } } - /** - * Reset the logger. - */ - public static function reset() - { +} +namespace DDTrace\Contracts { + /** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/ScopeManager.php + */ + /** + * Keeps track of the current active `Span`. + */ + interface ScopeManager + { + const DEFAULT_FINISH_SPAN_ON_CLOSE = true; + /** + * Activates an `Span`, so that it is used as a parent when creating new spans. + * The implementation must keep track of the active spans sequence, so + * that previous spans can be resumed after a deactivation. + * + * @param Span $span the {@link Span} that should become the {@link #active()} + * @param bool $finishSpanOnClose whether span should automatically be finished + * when {@link Scope#close()} is called. Its default value is true. + * + * @return Scope instance to control the end of the active period for the {@link Span}. It is a + * programming error to neglect to call {@link Scope#close()} on the returned instance. + */ + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE); + /** + * Return the currently active {@link Scope} which can be used to access the + * currently active {@link Scope#getSpan()}. + * + * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent + * (as {@link References#CHILD_OF} reference) of any + * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()} + * time rather than at {@link Tracer#buildSpan(String)} time. + * + * @return Scope|null + */ + public function getActive(); + /** + * Closes all the current request root spans. Typically there only will be one. + */ + public function close(); } } -/** - * An implementation of the DDTrace\LoggerInterface that logs nothing. - */ -final class NullLogger extends \DDTrace\Log\AbstractLogger -{ - /** - * Logs a debug at the debug level. - * - * @param string $message - * @param array $context - */ - public function debug($message, array $context = array()) - { +namespace DDTrace { + final class ScopeManager implements \DDTrace\Contracts\ScopeManager + { + public function __construct(\DDTrace\SpanContext $rootContext = null) + { + } + /** + * {@inheritdoc} + * @param Span|SpanInterface $span + */ + public function activate(\DDTrace\Contracts\Span $span, $finishSpanOnClose = self::DEFAULT_FINISH_SPAN_ON_CLOSE) + { + } + /** + * {@inheritdoc} + */ + public function getActive() + { + } + public function deactivate(\DDTrace\Scope $scope) + { + } + /** @internal */ + public function getPrimaryRoot() + { + } + /** @internal */ + public function getTopScope() + { + } + /** + * Closes all the current request root spans. Typically there only will be one. + */ + public function close() + { + } } - /** - * Logs a warning at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function warning($message, array $context = []) - { +} +namespace DDTrace\Contracts { + /** + * Ported from opentracing/opentracing + * @see https://github.com/opentracing/opentracing-php/blob/master/src/OpenTracing/Span.php + */ + interface Span + { + /** + * @return string + */ + public function getOperationName(); + /** + * Yields the SpanContext for this Span. Note that the return value of + * Span::getContext() is still valid after a call to Span::finish(), as is + * a call to Span::getContext() after a call to Span::finish(). + * + * @return SpanContext + */ + public function getContext(); + /** + * Sets the end timestamp and finalizes Span state. + * + * With the exception of calls to getContext() (which are always allowed), + * finish() must be the last call made to any span instance, and to do + * otherwise leads to undefined behavior but not returning an exception. + * + * As an implementor, make sure you call {@see Tracer::deactivate()} + * otherwise new spans might try to be child of this one. + * + * If the span is already finished, a warning should be logged. + * + * @param float|int|\DateTimeInterface|null $finishTime if passing float or int + * it should represent the timestamp (including as many decimal places as you need) + * @return void + */ + public function finish($finishTime = null); + /** + * If the span is already finished, a warning should be logged. + * + * @param string $newOperationName + */ + public function overwriteOperationName($newOperationName); + /** + * Sets the span's resource name. + * + * @param string $resource + */ + public function setResource($resource); + /** + * Adds a tag to the span. + * + * If there is a pre-existing tag set for key, it is overwritten. + * + * As an implementor, consider using "standard tags" listed in {@see \DDTrace\Tags} + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param mixed $value + * @param boolean $setIfFinished + * @return void + */ + public function setTag($key, $value, $setIfFinished = false); + /** + * @param string $key + * @return string|null + */ + public function getTag($key); + /** + * Adds a log record to the span in key => value format, key must be a string and tag must be either + * a string, a boolean value, or a numeric type. + * + * If the span is already finished, a warning should be logged. + * + * @param array $fields + * @param int|float|\DateTimeInterface $timestamp + * @return void + */ + public function log(array $fields = [], $timestamp = null); + /** + * Adds a baggage item to the SpanContext which is immutable so it is required to use + * SpanContext::withBaggageItem to get a new one. + * + * If the span is already finished, a warning should be logged. + * + * @param string $key + * @param string $value + * @return void + */ + public function addBaggageItem($key, $value); + /** + * @param string $key + * @return string|null returns null when there is not a item under the provided key + */ + public function getBaggageItem($key); + /** + * @return array + */ + public function getAllBaggageItems(); + /** + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param \Throwable|\Exception|bool|null $error + * @throws \InvalidArgumentException + */ + public function setError($error); + /** + * Stores an error message and type in the Span. + * + * @param string $message + * @param string $type + */ + public function setRawError($message, $type); + /** + * Tells whether or not this Span contains errors. + * + * @return bool + */ + public function hasError(); + /** + * @return int + */ + public function getStartTime(); + /** + * @return int + */ + public function getDuration(); + /** + * @return string + */ + public function getTraceId(); + /** + * @return string + */ + public function getSpanId(); + /** + * @return null|string + */ + public function getParentId(); + /** + * @return string + */ + public function getResource(); + /** + * @return string + */ + public function getService(); + /** + * @return string|null + */ + public function getType(); + /** + * @return bool + */ + public function isFinished(); + /** + * @return array + */ + public function getAllTags(); + /** + * Tells whether or not the span has the provided tag. Note that there are no guarantees that the tag value is + * not empty. + * + * @param string $name + * @return bool + */ + public function hasTag($name); + /** + * Set a DD metric. + * + * @param string $key + * @param mixed $value + */ + public function setMetric($key, $value); + /** + * @return array All the currently set metrics. + */ + public function getMetrics(); } - /** - * Logs a error at the debug level. - * - * @param string $message - * @param array $context - * - * @return void - */ - public function error($message, array $context = array()) - { +} +namespace DDTrace\Data { + /** + * Class Span + * @property string $operationName + * @property string $resource + * @property string $service + * @property string $type + * @property int $startTime + * @property int $duration + * @property array $tags + * @property array $metrics + */ + abstract class Span implements \DDTrace\Contracts\Span + { + /** + * @var SpanContextData + */ + public $context; + /** + * @var bool + */ + public $hasError = false; + /** + * @var \DDTrace\SpanData + */ + protected $internalSpan; + public function &__get($name) + { + } + public function __set($name, $value) + { + } + public function __isset($name) + { + } } - /** - * @param string $level - * @return bool - */ - public function isLevelActive($level) - { +} +namespace DDTrace { + class Span extends \DDTrace\Data\Span + { + use \DDTrace\Log\LoggingTrait; + public $internalSpan; + /** + * Span constructor. + * @param SpanData $internalSpan + * @param SpanContext $context + */ + public function __construct(\DDTrace\SpanData $internalSpan, \DDTrace\SpanContext $context) + { + } + /** + * {@inheritdoc} + */ + public function getTraceId() + { + } + /** + * {@inheritdoc} + */ + public function getSpanId() + { + } + /** + * {@inheritdoc} + */ + public function getParentId() + { + } + /** + * {@inheritdoc} + */ + public function overwriteOperationName($operationName) + { + } + /** + * {@inheritdoc} + */ + public function getResource() + { + } + /** + * {@inheritdoc} + */ + public function getService() + { + } + /** + * {@inheritdoc} + */ + public function getType() + { + } + /** + * {@inheritdoc} + */ + public function getStartTime() + { + } + /** + * {@inheritdoc} + */ + public function getDuration() + { + } + /** + * {@inheritdoc} + */ + public function setTag($key, $value, $setIfFinished = false) + { + } + /** + * {@inheritdoc} + */ + public function getTag($key) + { + } + /** + * {@inheritdoc} + */ + public function getAllTags() + { + } + /** + * {@inheritdoc} + */ + public function hasTag($name) + { + } + /** + * @param string $key + * @param mixed $value + */ + public function setMetric($key, $value) + { + } + /** + * @return array + */ + public function getMetrics() + { + } + /** + * {@inheritdoc} + */ + public function setResource($resource) + { + } + /** + * Stores a Throwable object within the span tags. The error status is + * updated and the error.Error() string is included with a default tag key. + * If the Span has been finished, it will not be modified by this method. + * + * @param Throwable|Exception|bool|null $error + * @throws InvalidArgumentException + */ + public function setError($error) + { + } + /** + * @param string $message + * @param string $type + */ + public function setRawError($message, $type) + { + } + public function hasError() + { + } + /** + * {@inheritdoc} + */ + public function finish($finishTime = null) + { + } + /** + * {@inheritdoc} + */ + public function isFinished() + { + } + /** + * {@inheritdoc} + */ + public function getOperationName() + { + } + /** + * {@inheritdoc} + */ + public function getContext() + { + } + /** + * {@inheritdoc} + */ + public function log(array $fields = [], $timestamp = null) + { + } + /** + * {@inheritdoc} + */ + public function addBaggageItem($key, $value) + { + } + /** + * {@inheritdoc} + */ + public function getBaggageItem($key) + { + } + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() + { + } + public function __destruct() + { + } } } -namespace DDTrace\Obfuscation; - -/** - * Converts strings with wildcards into search/replace regex arrays - * The following is converted - * - * -> ? - * - $* -> ${n} - */ -// Examples: /api/v1/users/*,/api/v1/rooms/*/$*,/api/v1/bookings/*/guests -// - /api/v1/users/123 -> /api/v1/users/? -// - /api/v1/rooms/123/details -> /api/v1/rooms/?/details -// - /api/v1/rooms/foo-bar-room/gallery -> /api/v1/rooms/?/gallery -// - /api/v1/bookings/123/guests/ -> /api/v1/bookings/?/guests -final class WildcardToRegex -{ - const REPLACEMENT_CHARACTER = '?'; - /** - * @param string $wildcardPattern - * - * @return string[] - */ - public static function convert($wildcardPattern) - { +namespace DDTrace\Contracts { + /** + * SpanContext must be immutable in order to avoid complicated lifetime + * issues around Span finish and references. + * + * Baggage items are key => value string pairs that apply to the given Span, + * its SpanContext, and all Spans which directly or transitively reference + * the local Span. That is, baggage items propagate in-band along with the + * trace itself. + */ + interface SpanContext extends \IteratorAggregate + { + /** + * Returns the value of a baggage item based on its key. If there is no + * value with such key it will return null. + * + * @param string $key + * @return string|null + */ + public function getBaggageItem($key); + /** + * Creates a new SpanContext out of the existing one and the new key => value pair. + * + * @param string $key + * @param string $value + * @return SpanContext + */ + public function withBaggageItem($key, $value); + /** + * @return array + */ + public function getAllBaggageItems(); + /** + * Gets initial priority sampling, upon span creation + * + * @return int + */ + public function getPropagatedPrioritySampling(); + /** + * Sets initial priority sampling, to be consumed upon span creation + * + * @param int $propagatedPrioritySampling + */ + public function setPropagatedPrioritySampling($propagatedPrioritySampling); + /** + * Returns whether or not this context represents the root span for a specific host. + * + * @return bool + */ + public function isHostRoot(); + /** + * @return string + */ + public function getTraceId(); + /** + * @return string + */ + public function getSpanId(); + /** + * @return string|null + */ + public function getParentId(); + /** + * @return bool + */ + public function isDistributedTracingActivationContext(); } } -namespace DDTrace; - -final class Reference -{ - /** - * A Span may be the ChildOf a parent Span. In a ChildOf reference, - * the parent Span depends on the child Span in some capacity. - */ - const CHILD_OF = 'child_of'; - /** - * Some parent Spans do not depend in any way on the result of their - * child Spans. In these cases, we say merely that the child Span - * FollowsFrom the parent Span in a causal sense. - */ - const FOLLOWS_FROM = 'follows_from'; - /** - * @param SpanContextInterface|SpanInterface $context - * @param string $type - * @throws InvalidReferenceArgument on empty type - * @return Reference when context is invalid - */ - public static function create($type, $context) - { +namespace DDTrace\Data { + abstract class SpanContext implements \DDTrace\Contracts\SpanContext + { + /** + * The unique integer (63-bit unsigned) ID of the trace containing this span. + * It is stored in decimal representation. + * + * @var string + */ + public $traceId; + /** + * The span integer (63-bit unsigned) ID. + * It is stored in devimal representation. + * + * @var string + */ + public $spanId; + /** + * The span integer ID of the parent span. + * It is stored in decimal representation. + * + * @var string|null + */ + public $parentId; + /** + * Whether or not this SpanContext represent a distributed tracing remote context. + * When the Tracer::extract() extracts a span context because of distributed tracing then this property is true, + * otherwise is false. + * + * @var bool + */ + public $isDistributedTracingActivationContext; + /** + * Initial priority sampling, upon span creation + * + * @var int + */ + public $propagatedPrioritySampling; + /** + * The origin of the distributed trace. + * + * @var string|null + */ + public $origin; + /** + * @var SpanContextInterface + */ + public $parentContext; + /** + * @var array + */ + public $baggageItems; } - /** - * @return SpanContextInterface - */ - public function getContext() - { +} +namespace DDTrace { + final class SpanContext extends \DDTrace\Data\SpanContext + { + public function __construct($traceId, $spanId, $parentId = null, array $baggageItems = [], $isDistributedTracingActivationContext = false) + { + } + public static function createAsChild(\DDTrace\Contracts\SpanContext $parentContext, $startTime = null) + { + } + public static function createAsRoot(array $baggageItems = [], $startTime = null) + { + } + /** + * {@inheritdoc} + */ + public function getTraceId() + { + } + /** + * {@inheritdoc} + */ + public function getSpanId() + { + } + /** + * {@inheritdoc} + */ + public function getParentId() + { + } + /** + * {@inheritdoc} + */ + #[\ReturnTypeWillChange] + public function getIterator() + { + } + /** + * {@inheritdoc} + */ + public function getPropagatedPrioritySampling() + { + } + /** + * {@inheritdoc} + */ + public function setPropagatedPrioritySampling($propagatedPrioritySampling) + { + } + /** + * {@inheritdoc} + */ + public function getBaggageItem($key) + { + } + /** + * {@inheritdoc} + */ + public function withBaggageItem($key, $value) + { + } + /** + * {@inheritdoc} + */ + public function getAllBaggageItems() + { + } + public function isEqual(\DDTrace\Contracts\SpanContext $spanContext) + { + } + /** + * {@inheritdoc} + */ + public function isDistributedTracingActivationContext() + { + } + /** + * {@inheritdoc} + */ + public function isHostRoot() + { + } + } + /** + * Although DataDog uses nanotime to report spans PHP does not support nanotime + * plus, nanotime is a uint64 which is not supported either. Microtime will be used + * and there will be transformations in reporting in order to send nanotime. + */ + class Time + { + /** + * @return int + */ + public static function now() + { + } + /** + * @return int + */ + public static function fromMicrotime($microtime) + { + } + /** + * @param mixed $time + * @return bool + */ + public static function isValid($time) + { + } } - /** - * Checks whether a Reference is of one type. - * - * @param string $type the type for the reference - * @return bool - */ - public function isType($type) - { +} +namespace DDTrace\Contracts { + interface Tracer + { + /** + * Checks if Tracer is in limited mode. + * + * Tracer needs to handle any operation even if its in limited mode, + * however users can opt not to use tracer when its in limited mode. + * + * @return bool + */ + public function limited(); + /** + * Returns the current {@link ScopeManager}, which may be a noop but may not be null. + * + * @return ScopeManager + */ + public function getScopeManager(); + /** + * Returns the active {@link Span}. This is a shorthand for + * Tracer::getScopeManager()->getActive()->getSpan(), + * and null will be returned if {@link Scope#active()} is null. + * + * @return Span|null + */ + public function getActiveSpan(); + /** + * Starts a new span that is activated on a scope manager. + * + * It's also possible to not finish the {@see \DDTrace\Contracts\Span} when + * {@see \DDTrace\Contracts\Scope} context expires: + * + * $scope = $tracer->startActiveSpan('...', [ + * 'finish_span_on_close' => false, + * ]); + * $span = $scope->getSpan(); + * try { + * $span->setTag(Tags\HTTP_METHOD, 'GET'); + * // ... + * } finally { + * $scope->close(); + * } + * // $span->finish() is not called as part of Scope deactivation as + * // finish_span_on_close is false + * + * @param string $operationName + * @param array|StartSpanOptions $options Same as for startSpan() with + * aditional option of `finish_span_on_close` that enables finishing + * of span whenever a scope is closed. It is true by default. + * + * @return Scope A Scope that holds newly created Span and is activated on + * a ScopeManager. + */ + public function startActiveSpan($operationName, $options = []); + /** + * Starts and returns a new span representing a unit of work. + * + * Whenever `child_of` reference is not passed then + * {@see \DDTrace\Contracts\ScopeManager::getActive()} span is used as `child_of` + * reference. In order to ignore implicit parent span pass in + * `ignore_active_span` option set to true. + * + * Starting a span with explicit parent: + * + * $tracer->startSpan('...', [ + * 'child_of' => $parentSpan, + * ]); + * + * @see \DDTrace\StartSpanOptions + * + * @param string $operationName + * @param array|StartSpanOptions $options See StartSpanOptions for + * available options. + * + * @return Span + * + * @throws InvalidSpanOption for invalid option + * @throws InvalidReferencesSet for invalid references set + */ + public function startSpan($operationName, $options = []); + /** + * @param SpanContext $spanContext + * @param string $format + * @param mixed $carrier + * + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier); + /** + * @param string $format + * @param mixed $carrier + * @return SpanContext|null + * + * @see Formats + * + * @throws UnsupportedFormat when the format is not recognized by the tracer + * implementation + */ + public function extract($format, $carrier); + /** + * Allow tracer to send span data to be instrumented. + * + * This method might not be needed depending on the tracing implementation + * but one should make sure this method is called after the request is delivered + * to the client. + * + * As an implementor, a good idea would be to use {@see register_shutdown_function} + * or {@see fastcgi_finish_request} in order to not to delay the end of the request + * to the client. + */ + public function flush(); + /** + * @param mixed $prioritySampling + */ + public function setPrioritySampling($prioritySampling); + /** + * @return int|null + */ + public function getPrioritySampling(); + /** + * This behaves just like Tracer::startActiveSpan(), but it saves the Scope instance + * on the tracer to be accessed later by Tracer::getRootScope(). + * + * @param string $operationName + * @param array $options + * @return Scope + */ + public function startRootSpan($operationName, $options = []); + /** + * @return Scope|null + */ + public function getRootScope(); + /** + * Returns the root span or null and never throws an exception. + * + * @return Span|null + */ + public function getSafeRootSpan(); + /** + * Returns the entire trace encoded as a plain-old PHP array. + * + * @return array + */ + public function getTracesAsArray(); + /** + * Returns the count of currently stored traces + * + * @return int + */ + public function getTracesCount(); } } -namespace DDTrace\Sampling; - -class PrioritySampling -{ - // The Agent will drop the trace, as instructed by any mechanism that is not the sampler. - const USER_REJECT = -1; - // Automatic sampling decision. The Agent should drop the trace. - const AUTO_REJECT = 0; - // Automatic sampling decision. The Agent should keep the trace. - const AUTO_KEEP = 1; - // The Agent should keep the trace, as instructed by any mechanism that is not the sampler. - // The backend will only apply sampling if above maximum volume allowed. - const USER_KEEP = 2; - // It was not possible to parse - const UNKNOWN = null; - /** - * @param mixed|string $value - * @return int|null - */ - public static function parse($value) - { +namespace DDTrace { + final class Tracer implements \DDTrace\Contracts\Tracer + { + use \DDTrace\Log\LoggingTrait; + /** + * @param Transport $transport + * @param Propagator[] $propagators + * @param array $config + */ + public function __construct(\DDTrace\Transport $transport = null, array $propagators = null, array $config = []) + { + } + public function limited() + { + } + /** + * Resets this tracer to its original state. + */ + public function reset() + { + } + /** + * @return Tracer + */ + public static function noop() + { + } + /** + * {@inheritdoc} + */ + public function startSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function startRootSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function getRootScope() + { + } + /** + * {@inheritdoc} + */ + public function startActiveSpan($operationName, $options = []) + { + } + /** + * {@inheritdoc} + */ + public function inject(\DDTrace\Contracts\SpanContext $spanContext, $format, &$carrier) + { + } + /** + * {@inheritdoc} + */ + public function extract($format, $carrier) + { + } + /** + * @return void + */ + public function flush() + { + } + /** + * {@inheritdoc} + */ + public function getScopeManager() + { + } + /** + * @return null|Span + */ + public function getActiveSpan() + { + } + /** + * {@inheritdoc} + */ + public function getTracesAsArray() + { + } + public function addUrlAsResourceNameToSpan(\DDTrace\Contracts\Span $span) + { + } + /** + * @param mixed $prioritySampling + */ + public function setPrioritySampling($prioritySampling) + { + } + /** + * {@inheritdoc} + */ + public function getPrioritySampling() + { + } + /** + * Returns the root span or null and never throws an exception. + * + * @return SpanInterface|null + */ + public function getSafeRootSpan() + { + } + /** + * @return string + */ + public static function version() + { + } + /** + * {@inheritdoc} + */ + public function getTracesCount() + { + } + } + interface Transport + { + /** + * @param TracerInterface $tracer + */ + public function send(\DDTrace\Contracts\Tracer $tracer); + /** + * @param string $key + * @param string $value + * @return void + */ + public function setHeader($key, $value); } } -namespace DDTrace; - -final class StartSpanOptions -{ - /** - * @param array $options - * @throws InvalidSpanOption when one of the options is invalid - * @throws InvalidReferencesSet when there are inconsistencies about the references - * @return StartSpanOptions - */ - public static function create(array $options) +namespace DDTrace\Transport { + final class Internal implements \DDTrace\Transport { + public function send(\DDTrace\Contracts\Tracer $tracer) + { + } + public function setHeader($key, $value) + { + } } - /** - * @param SpanInterface|SpanContextInterface $parent - * @return StartSpanOptions - */ - public function withParent($parent) - { +} +namespace DDTrace\Exceptions { + /** + * Thrown when passing an invalid argument for a reference + */ + final class InvalidReferenceArgument extends \InvalidArgumentException + { + /** + * @return InvalidReferenceArgument + */ + public static function forEmptyType() + { + } + /** + * @param mixed $context + * @return InvalidReferenceArgument + */ + public static function forInvalidContext($context) + { + } + } + /** + * Thrown when a reference has more than one parent in the SpanOptions + */ + final class InvalidReferencesSet extends \DomainException + { + /** + * @param string $message + * @return InvalidReferencesSet + */ + public static function create($message) + { + } + /** + * @return InvalidReferencesSet + */ + public static function forMoreThanOneParent() + { + } + } + final class InvalidSpanArgument extends \InvalidArgumentException + { + public static function forTagKey($key) + { + } + public static function forError($error) + { + } + } + /** + * Thrown when passing an invalid option on Span creation + */ + final class InvalidSpanOption extends \InvalidArgumentException + { + /** + * @return InvalidSpanOption + */ + public static function forIncludingBothChildOfAndReferences() + { + } + /** + * @param mixed $reference + * @return InvalidSpanOption + */ + public static function forInvalidReference($reference) + { + } + /** + * @return InvalidSpanOption + */ + public static function forInvalidStartTime() + { + } + public static function forInvalidChildOf($childOfOption) + { + } + /** + * @param string $key + * @return InvalidSpanOption + */ + public static function forUnknownOption($key) + { + } + /** + * @param mixed $tag + * @return InvalidSpanOption + */ + public static function forInvalidTag($tag) + { + } + /** + * @param mixed $tagValue + * @return InvalidSpanOption + */ + public static function forInvalidTagValue($tagValue) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forInvalidTags($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forInvalidReferenceSet($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forFinishSpanOnClose($value) + { + } + /** + * @param mixed $value + * @return InvalidSpanOption + */ + public static function forIgnoreActiveSpan($value) + { + } + } + /** + * Thrown when trying to inject or extract in an invalid format + */ + final class UnsupportedFormat extends \UnexpectedValueException + { + /** + * @param string $format + * @return UnsupportedFormat + */ + public static function forFormat($format) + { + } } - /** - * @return Reference[] - */ - public function getReferences() - { +} +namespace DDTrace { + class Format + { + /** + * Used a (single) arbitrary binary blob representing a SpanContext + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `string`. + */ + const BINARY = 'binary'; + /** + * Used for an arbitrary string-to-string map with an unrestricted character set for both keys and values + * + * Unlike `HTTP_HEADERS`, the `TEXT_MAP` format does not restrict the key or + * value character sets in any way. + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + */ + const TEXT_MAP = 'text_map'; + /** + * Used for a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. + * In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly + * recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively. + * + * Unlike `TEXT_MAP`, the `HTTP_HEADERS` format requires that the keys and values be valid as HTTP headers as-is + * (i.e., character casing may be unstable and special characters are disallowed in keys, values should be + * URL-escaped, etc). + * + * For both Tracer::inject() and Tracer::extract() the carrier must be a `array|ArrayObject`. + * + * For example, Tracer::inject(): + * + * $headers = [] + * $tracer->inject($span->getContext(), Format::HTTP_HEADERS, $headers) + * $request = new GuzzleHttp\Psr7\Request($uri, $body, $headers); + * + * Or Tracer::extract(): + * + * $headers = $request->getHeaders() + * $clientContext = $tracer->extract(Formats::HTTP_HEADERS, $headers) + * + * @see http://www.php-fig.org/psr/psr-7/#12-http-headers + * @see http://php.net/manual/en/function.getallheaders.php + */ + const HTTP_HEADERS = 'http_headers'; + } + final class GlobalTracer + { + /** + * GlobalTracer::set sets the [singleton] Tracer returned by get(). + * Those who use GlobalTracer (rather than directly manage a Tracer instance) + * should call GlobalTracer::set as early as possible in bootstrap, prior to + * start a new span. Prior to calling GlobalTracer::set, any Spans started + * via the `Tracer::startActiveSpan` (etc) globals are noops. + * + * @param TracerInterface $tracer + */ + public static function set(\DDTrace\Contracts\Tracer $tracer) + { + } + /** + * GlobalTracer::get returns the global singleton `Tracer` implementation. + * Before `GlobalTracer::set` is called, the `GlobalTracer::get` is a noop + * implementation that drops all data handed to it. + * + * @return TracerInterface + */ + public static function get() + { + } } - /** - * @return array - */ - public function getTags() - { +} +namespace DDTrace\Http { + /** + * A utility class that provides methods to work on urls + */ + class Urls + { + /** + * Inject URL replacement patterns using '*' and '$*' as wildcards + * The '*' wildcard will match one or more characters to be replaced with '?' + * The '$*' wildcard will match one or more characters without replacement + * + * @param string[] $patternsWithWildcards + */ + public function __construct(array $patternsWithWildcards = []) + { + } + /** + * Removes query string and fragment and user information from a url. + * + * @param string $url + * @param bool $dropUserInfo Optional. If `true`, removes the user information fragment instead of obfuscating it. + * Defaults to `false`. + */ + public static function sanitize($url, $dropUserInfo = false) + { + } + /** + * Extracts the hostname of a given URL + * + * @param string $url + * @return string + */ + public static function hostname($url) + { + } + /** + * Metadata keys must start with [a-zA-Z:] so IP addresses, + * for example, need to be prefixed with a valid character. + * + * Note: then name of this function is misleading, as it should actually be normalizeUrlForService(), but since this + * part of the public API, we keep it like this and discuss a future deprecation. + * + * @param string $url + * @return string + */ + public static function hostnameForTag($url) + { + } + /** + * Reduces cardinality of a url. + * + * @param string $url + * @return string + */ + public function normalize($url) + { + } } - /** - * @return int|float|\DateTime|null if returning float or int it should represent - * the timestamp (including as many decimal places as you need) - */ - public function getStartTime() - { +} +namespace DDTrace\Log { + /** + * Defines logging methods as used in DDTrace code. + */ + interface LoggerInterface + { + /** + * Logs a message at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function debug($message, array $context = array()); + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []); + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = array()); + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level); + } + /** + * An abstract logger. + */ + abstract class AbstractLogger implements \DDTrace\Log\LoggerInterface + { + /** + * @param string $level + */ + public function __construct($level) + { + } + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level) + { + } + } + /** + * Provides methods to interpolate log messages. + */ + trait InterpolateTrait + { + /** + * Interpolates context values into the message placeholders. Example code from: + * https://www.php-fig.org/psr/psr-3/ + * + * @param string $message + * @param array $context + * @return string + */ + public static function interpolate($message, array $context = []) + { + } + } + /** + * JSON logger that writes to a stream, with simple logs correlation support. + * Heavily inspired from Monolog's StreamHandler. + * @internal This logger is internal and can be removed without prior notice + */ + final class DatadogLogger + { + use \DDTrace\Log\InterpolateTrait; + const DEFAULT_JSON_FLAGS = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRESERVE_ZERO_FRACTION | JSON_PARTIAL_OUTPUT_ON_ERROR; + public function __construct($stream = null, $mode = 'a') + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function emergency($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function alert($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function critical($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function error($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function notice($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function info($message, array $context = []) + { + } + /** + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function debug($message, array $context = []) + { + } + /** + * @param string $level + * @param string|\Stringable $message + * @param array $context + * @return void + */ + public function log(string $level, $message, array $context = []) + { + } + public function customErrorHandler(int $code, string $msg) : bool + { + } + } + /** + * An implementation of the DDTrace\LoggerInterface that logs to the error_log. + */ + class ErrorLogLogger extends \DDTrace\Log\AbstractLogger + { + use \DDTrace\Log\InterpolateTrait; + /** + * Logs a debug message. Substitution is provided as specified in: + * https://www.php-fig.org/psr/psr-3/ + * + * @param string $message + * @param array $context + */ + public function debug($message, array $context = []) + { + } + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = []) + { + } + } + /** + * Known log levels. + */ + final class LogLevel + { + /** + * Const list from https://www.php-fig.org/psr/psr-3/ + */ + const EMERGENCY = 'emergency'; + const ALERT = 'alert'; + const CRITICAL = 'critical'; + const ERROR = 'error'; + const WARNING = 'warning'; + const NOTICE = 'notice'; + const INFO = 'info'; + const DEBUG = 'debug'; + /** + * All the log levels. + * + * @return string[] + */ + public static function all() + { + } + } + /** + * A global logger holder. Can be configured to use a specific logger. If not configured, it returns a NullLogger. + */ + final class Logger + { + /** + * Sets the global logger instance. + * + * @param LoggerInterface $logger + */ + public static function set(\DDTrace\Log\LoggerInterface $logger) + { + } + /** + * Retrieves the global logger instance. If not set, it falls back to a NullLogger. + * + * @return LoggerInterface + */ + public static function get() + { + } + /** + * Reset the logger. + */ + public static function reset() + { + } + } + /** + * An implementation of the DDTrace\LoggerInterface that logs nothing. + */ + final class NullLogger extends \DDTrace\Log\AbstractLogger + { + /** + * Logs a debug at the debug level. + * + * @param string $message + * @param array $context + */ + public function debug($message, array $context = array()) + { + } + /** + * Logs a warning at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function warning($message, array $context = []) + { + } + /** + * Logs a error at the debug level. + * + * @param string $message + * @param array $context + * + * @return void + */ + public function error($message, array $context = array()) + { + } + /** + * @param string $level + * @return bool + */ + public function isLevelActive($level) + { + } } - /** - * @return bool - */ - public function shouldFinishSpanOnClose() - { +} +namespace DDTrace\Obfuscation { + /** + * Converts strings with wildcards into search/replace regex arrays + * The following is converted + * - * -> ? + * - $* -> ${n} + */ + // Examples: /api/v1/users/*,/api/v1/rooms/*/$*,/api/v1/bookings/*/guests + // - /api/v1/users/123 -> /api/v1/users/? + // - /api/v1/rooms/123/details -> /api/v1/rooms/?/details + // - /api/v1/rooms/foo-bar-room/gallery -> /api/v1/rooms/?/gallery + // - /api/v1/bookings/123/guests/ -> /api/v1/bookings/?/guests + final class WildcardToRegex + { + const REPLACEMENT_CHARACTER = '?'; + /** + * @param string $wildcardPattern + * + * @return string[] + */ + public static function convert($wildcardPattern) + { + } } - /** - * @return bool - */ - public function shouldIgnoreActiveSpan() - { +} +namespace DDTrace { + final class Reference + { + /** + * A Span may be the ChildOf a parent Span. In a ChildOf reference, + * the parent Span depends on the child Span in some capacity. + */ + const CHILD_OF = 'child_of'; + /** + * Some parent Spans do not depend in any way on the result of their + * child Spans. In these cases, we say merely that the child Span + * FollowsFrom the parent Span in a causal sense. + */ + const FOLLOWS_FROM = 'follows_from'; + /** + * @param SpanContextInterface|SpanInterface $context + * @param string $type + * @throws InvalidReferenceArgument on empty type + * @return Reference when context is invalid + */ + public static function create($type, $context) + { + } + /** + * @return SpanContextInterface + */ + public function getContext() + { + } + /** + * Checks whether a Reference is of one type. + * + * @param string $type the type for the reference + * @return bool + */ + public function isType($type) + { + } } } -class Tag -{ - // Generic - const ENV = 'env'; - const SPAN_TYPE = 'span.type'; - const SPAN_KIND = 'span.kind'; - const SPAN_KIND_VALUE_SERVER = 'server'; - const SPAN_KIND_VALUE_CLIENT = 'client'; - const SPAN_KIND_VALUE_PRODUCER = 'producer'; - const SPAN_KIND_VALUE_CONSUMER = 'consumer'; - const SPAN_KIND_VALUE_INTERNAL = 'internal'; - const COMPONENT = 'component'; - const SERVICE_NAME = 'service.name'; - const MANUAL_KEEP = 'manual.keep'; - const MANUAL_DROP = 'manual.drop'; - const PID = 'process_id'; - const RESOURCE_NAME = 'resource.name'; - const DB_STATEMENT = 'sql.query'; - const ERROR = 'error'; - const ERROR_MSG = 'error.message'; - // string representing the error message - const ERROR_TYPE = 'error.type'; - // string representing the type of the error - const ERROR_STACK = 'error.stack'; - // human readable version of the stack - const HTTP_METHOD = 'http.method'; - const HTTP_ROUTE = 'http.route'; - const HTTP_STATUS_CODE = 'http.status_code'; - const HTTP_URL = 'http.url'; - const HTTP_VERSION = 'http.version'; - const LOG_EVENT = 'event'; - const LOG_ERROR = 'error'; - const LOG_ERROR_OBJECT = 'error.object'; - const LOG_MESSAGE = 'message'; - const LOG_STACK = 'stack'; - const NETWORK_DESTINATION_NAME = 'network.destination.name'; - const TARGET_HOST = 'out.host'; - const TARGET_PORT = 'out.port'; - const BYTES_OUT = 'net.out.bytes'; - const ANALYTICS_KEY = '_dd1.sr.eausr'; - const HOSTNAME = '_dd.hostname'; - const ORIGIN = '_dd.origin'; - const VERSION = 'version'; - const SERVICE_VERSION = 'service.version'; - // OpenTelemetry compatible tag - // Elasticsearch - const ELASTICSEARCH_BODY = 'elasticsearch.body'; - const ELASTICSEARCH_METHOD = 'elasticsearch.method'; - const ELASTICSEARCH_PARAMS = 'elasticsearch.params'; - const ELASTICSEARCH_URL = 'elasticsearch.url'; - // Database - const DB_NAME = 'db.name'; - const DB_CHARSET = 'db.charset'; - const DB_INSTANCE = 'db.instance'; - const DB_TYPE = 'db.type'; - const DB_SYSTEM = 'db.system'; - const DB_ROW_COUNT = 'db.row_count'; - const DB_STMT = 'db.statement'; - const DB_USER = 'db.user'; - // Laravel Queue - const LARAVELQ_ATTEMPTS = 'messaging.laravel.attempts'; - const LARAVELQ_BATCH_ID = 'messaging.laravel.batch_id'; - const LARAVELQ_CONNECTION = 'messaging.laravel.connection'; - const LARAVELQ_MAX_TRIES = 'messaging.laravel.max_tries'; - const LARAVELQ_NAME = 'messaging.laravel.name'; - const LARAVELQ_TIMEOUT = 'messaging.laravel.timeout'; - // MongoDB - const MONGODB_BSON_ID = 'mongodb.bson.id'; - const MONGODB_COLLECTION = 'mongodb.collection'; - const MONGODB_DATABASE = 'mongodb.db'; - const MONGODB_PROFILING_LEVEL = 'mongodb.profiling_level'; - const MONGODB_READ_PREFERENCE = 'mongodb.read_preference'; - const MONGODB_SERVER = 'mongodb.server'; - const MONGODB_TIMEOUT = 'mongodb.timeout'; - const MONGODB_QUERY = 'mongodb.query'; - // REDIS - const REDIS_RAW_COMMAND = 'redis.raw_command'; - // Message Queue - const MQ_SYSTEM = 'messaging.system'; - const MQ_DESTINATION = 'messaging.destination'; - const MQ_DESTINATION_KIND = 'messaging.destination_kind'; - const MQ_TEMP_DESTINATION = 'messaging.temp_destination'; - const MQ_PROTOCOL = 'messaging.protocol'; - const MQ_PROTOCOL_VERSION = 'messaging.protocol_version'; - const MQ_URL = 'messaging.url'; - const MQ_MESSAGE_ID = 'messaging.message_id'; - const MQ_CONVERSATION_ID = 'messaging.conversation_id'; - const MQ_MESSAGE_PAYLOAD_SIZE = 'messaging.message_payload_size_bytes'; - const MQ_OPERATION = 'messaging.operation'; - const MQ_CONSUMER_ID = 'messaging.consumer_id'; - // RabbitMQ - const RABBITMQ_DELIVERY_MODE = 'messaging.rabbitmq.delivery_mode'; - const RABBITMQ_EXCHANGE = 'messaging.rabbitmq.exchange'; - const RABBITMQ_ROUTING_KEY = 'messaging.rabbitmq.routing_key'; - // Exec - const EXEC_CMDLINE_EXEC = 'cmd.exec'; - const EXEC_CMDLINE_SHELL = 'cmd.shell'; - const EXEC_TRUNCATED = 'cmd.truncated'; - const EXEC_EXIT_CODE = 'cmd.exit_code'; +namespace DDTrace\Sampling { + class PrioritySampling + { + // The Agent will drop the trace, as instructed by any mechanism that is not the sampler. + const USER_REJECT = -1; + // Automatic sampling decision. The Agent should drop the trace. + const AUTO_REJECT = 0; + // Automatic sampling decision. The Agent should keep the trace. + const AUTO_KEEP = 1; + // The Agent should keep the trace, as instructed by any mechanism that is not the sampler. + // The backend will only apply sampling if above maximum volume allowed. + const USER_KEEP = 2; + // It was not possible to parse + const UNKNOWN = null; + /** + * @param mixed|string $value + * @return int|null + */ + public static function parse($value) + { + } + } } -class Type -{ - const CACHE = 'cache'; - const HTTP_CLIENT = 'http'; - const WEB_SERVLET = 'web'; - const CLI = 'cli'; - const SQL = 'sql'; - const MESSAGE_CONSUMER = 'queue'; - const MESSAGE_PRODUCER = 'queue'; - const CASSANDRA = 'cassandra'; - const ELASTICSEARCH = 'elasticsearch'; - const MEMCACHED = 'memcached'; - const MONGO = 'mongodb'; - const OPENAI = 'openai'; - const REDIS = 'redis'; - const SYSTEM = 'system'; +namespace DDTrace { + final class StartSpanOptions + { + /** + * @param array $options + * @throws InvalidSpanOption when one of the options is invalid + * @throws InvalidReferencesSet when there are inconsistencies about the references + * @return StartSpanOptions + */ + public static function create(array $options) + { + } + /** + * @param SpanInterface|SpanContextInterface $parent + * @return StartSpanOptions + */ + public function withParent($parent) + { + } + /** + * @return Reference[] + */ + public function getReferences() + { + } + /** + * @return array + */ + public function getTags() + { + } + /** + * @return int|float|\DateTime|null if returning float or int it should represent + * the timestamp (including as many decimal places as you need) + */ + public function getStartTime() + { + } + /** + * @return bool + */ + public function shouldFinishSpanOnClose() + { + } + /** + * @return bool + */ + public function shouldIgnoreActiveSpan() + { + } + } + class Tag + { + // Generic + const ENV = 'env'; + const SPAN_TYPE = 'span.type'; + const SPAN_KIND = 'span.kind'; + const SPAN_KIND_VALUE_SERVER = 'server'; + const SPAN_KIND_VALUE_CLIENT = 'client'; + const SPAN_KIND_VALUE_PRODUCER = 'producer'; + const SPAN_KIND_VALUE_CONSUMER = 'consumer'; + const SPAN_KIND_VALUE_INTERNAL = 'internal'; + const COMPONENT = 'component'; + const SERVICE_NAME = 'service.name'; + const MANUAL_KEEP = 'manual.keep'; + const MANUAL_DROP = 'manual.drop'; + const PID = 'process_id'; + const RESOURCE_NAME = 'resource.name'; + const DB_STATEMENT = 'sql.query'; + const ERROR = 'error'; + const ERROR_MSG = 'error.message'; + // string representing the error message + const ERROR_TYPE = 'error.type'; + // string representing the type of the error + const ERROR_STACK = 'error.stack'; + // human readable version of the stack + const HTTP_METHOD = 'http.method'; + const HTTP_ROUTE = 'http.route'; + const HTTP_STATUS_CODE = 'http.status_code'; + const HTTP_URL = 'http.url'; + const HTTP_VERSION = 'http.version'; + const LOG_EVENT = 'event'; + const LOG_ERROR = 'error'; + const LOG_ERROR_OBJECT = 'error.object'; + const LOG_MESSAGE = 'message'; + const LOG_STACK = 'stack'; + const NETWORK_DESTINATION_NAME = 'network.destination.name'; + const TARGET_HOST = 'out.host'; + const TARGET_PORT = 'out.port'; + const BYTES_OUT = 'net.out.bytes'; + const ANALYTICS_KEY = '_dd1.sr.eausr'; + const HOSTNAME = '_dd.hostname'; + const ORIGIN = '_dd.origin'; + const VERSION = 'version'; + const SERVICE_VERSION = 'service.version'; + // OpenTelemetry compatible tag + // Elasticsearch + const ELASTICSEARCH_BODY = 'elasticsearch.body'; + const ELASTICSEARCH_METHOD = 'elasticsearch.method'; + const ELASTICSEARCH_PARAMS = 'elasticsearch.params'; + const ELASTICSEARCH_URL = 'elasticsearch.url'; + // Database + const DB_NAME = 'db.name'; + const DB_CHARSET = 'db.charset'; + const DB_INSTANCE = 'db.instance'; + const DB_TYPE = 'db.type'; + const DB_SYSTEM = 'db.system'; + const DB_ROW_COUNT = 'db.row_count'; + const DB_STMT = 'db.statement'; + const DB_USER = 'db.user'; + // Laravel Queue + const LARAVELQ_ATTEMPTS = 'messaging.laravel.attempts'; + const LARAVELQ_BATCH_ID = 'messaging.laravel.batch_id'; + const LARAVELQ_CONNECTION = 'messaging.laravel.connection'; + const LARAVELQ_MAX_TRIES = 'messaging.laravel.max_tries'; + const LARAVELQ_NAME = 'messaging.laravel.name'; + const LARAVELQ_TIMEOUT = 'messaging.laravel.timeout'; + // MongoDB + const MONGODB_BSON_ID = 'mongodb.bson.id'; + const MONGODB_COLLECTION = 'mongodb.collection'; + const MONGODB_DATABASE = 'mongodb.db'; + const MONGODB_PROFILING_LEVEL = 'mongodb.profiling_level'; + const MONGODB_READ_PREFERENCE = 'mongodb.read_preference'; + const MONGODB_SERVER = 'mongodb.server'; + const MONGODB_TIMEOUT = 'mongodb.timeout'; + const MONGODB_QUERY = 'mongodb.query'; + // REDIS + const REDIS_RAW_COMMAND = 'redis.raw_command'; + // Message Queue + const MQ_SYSTEM = 'messaging.system'; + const MQ_DESTINATION = 'messaging.destination'; + const MQ_DESTINATION_KIND = 'messaging.destination_kind'; + const MQ_TEMP_DESTINATION = 'messaging.temp_destination'; + const MQ_PROTOCOL = 'messaging.protocol'; + const MQ_PROTOCOL_VERSION = 'messaging.protocol_version'; + const MQ_URL = 'messaging.url'; + const MQ_MESSAGE_ID = 'messaging.message_id'; + const MQ_CONVERSATION_ID = 'messaging.conversation_id'; + const MQ_MESSAGE_PAYLOAD_SIZE = 'messaging.message_payload_size_bytes'; + const MQ_OPERATION = 'messaging.operation'; + const MQ_CONSUMER_ID = 'messaging.consumer_id'; + // RabbitMQ + const RABBITMQ_DELIVERY_MODE = 'messaging.rabbitmq.delivery_mode'; + const RABBITMQ_EXCHANGE = 'messaging.rabbitmq.exchange'; + const RABBITMQ_ROUTING_KEY = 'messaging.rabbitmq.routing_key'; + // Exec + const EXEC_CMDLINE_EXEC = 'cmd.exec'; + const EXEC_CMDLINE_SHELL = 'cmd.shell'; + const EXEC_TRUNCATED = 'cmd.truncated'; + const EXEC_EXIT_CODE = 'cmd.exit_code'; + } + class Type + { + const CACHE = 'cache'; + const HTTP_CLIENT = 'http'; + const WEB_SERVLET = 'web'; + const CLI = 'cli'; + const SQL = 'sql'; + const MESSAGE_CONSUMER = 'queue'; + const MESSAGE_PRODUCER = 'queue'; + const CASSANDRA = 'cassandra'; + const ELASTICSEARCH = 'elasticsearch'; + const MEMCACHED = 'memcached'; + const MONGO = 'mongodb'; + const OPENAI = 'openai'; + const REDIS = 'redis'; + const SYSTEM = 'system'; + } } \ No newline at end of file diff --git a/tooling/stubs/CustomPrinter.php b/tooling/stubs/CustomPrinter.php new file mode 100644 index 0000000000..a97e6a479a --- /dev/null +++ b/tooling/stubs/CustomPrinter.php @@ -0,0 +1,13 @@ +canUseSemicolonNamespaces = false; + return parent::pStmt_Namespace($node); + } +} diff --git a/tooling/stubs/generate-stubs.php b/tooling/stubs/generate-stubs.php index 3fbc9f8add..1354e0cf66 100644 --- a/tooling/stubs/generate-stubs.php +++ b/tooling/stubs/generate-stubs.php @@ -1,6 +1,7 @@ in($SRC_DIR)->path($files)->sortByName(); -$stubs = $generator->generate($finder)->prettyPrint(); +$stubs = $generator->generate($finder)->prettyPrint(new CustomPrinter()); $outputFile = $SRC_DIR . "ddtrace_php_api.stubs.php"; file_put_contents($outputFile, $stubs); From f19dbf36a795da47758d714904b161cb493aa7da Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Thu, 14 Nov 2024 09:20:36 +0100 Subject: [PATCH 21/23] fix: Type mixed cannot be marked as nullable --- ext/ddtrace.stub.php | 4 ++-- ext/ddtrace_arginfo.h | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/ddtrace.stub.php b/ext/ddtrace.stub.php index f10d16dd39..42ce7299e1 100644 --- a/ext/ddtrace.stub.php +++ b/ext/ddtrace.stub.php @@ -62,7 +62,7 @@ class ExceptionSpanEvent extends SpanEvent { * @param array $attributes Optional attributes for the event. */ public function __construct(\Throwable $exception, array $attributes = []) {} - + /** * @var \Throwable */ @@ -798,7 +798,7 @@ function has_listeners(): bool {} * @param string|resource|null $body the body of the request (a string or a seekable resource) * @return array|null an array with the keys 'status', 'headers' and 'body', or null */ - function notify_start(\DDTrace\RootSpanData $span, array $data, ?mixed $body = null): ?array {} + function notify_start(\DDTrace\RootSpanData $span, array $data, mixed $body = null): ?array {} /** * Notifies the user request listeners of the imminence of a commit, and allows for the replacement of the response. diff --git a/ext/ddtrace_arginfo.h b/ext/ddtrace_arginfo.h index 6ef23c7e21..7d670b1fe8 100644 --- a/ext/ddtrace_arginfo.h +++ b/ext/ddtrace_arginfo.h @@ -163,7 +163,7 @@ ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_notify_start, 0, 2, IS_ARRAY, 1) ZEND_ARG_OBJ_INFO(0, span, DDTrace\\RootSpanData, 0) ZEND_ARG_TYPE_INFO(0, data, IS_ARRAY, 0) - ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 1, "null") + ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 0, "null") ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_notify_commit, 0, 3, IS_ARRAY, 1) From 22378cc23b0595433d58f5e2a6d2e6bead79c085 Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Thu, 14 Nov 2024 09:25:01 +0100 Subject: [PATCH 22/23] fix: Type mixed cannot be marked as nullable --- ext/ddtrace.stub.php | 2 +- ext/ddtrace_arginfo.h | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/ddtrace.stub.php b/ext/ddtrace.stub.php index 42ce7299e1..8facdd633f 100644 --- a/ext/ddtrace.stub.php +++ b/ext/ddtrace.stub.php @@ -808,7 +808,7 @@ function notify_start(\DDTrace\RootSpanData $span, array $data, mixed $body = nu * @param string|resource|null $body the body of the response (a string or a seekable resource) * @return array|null an array with the keys 'status', 'headers' and 'body', or null */ - function notify_commit(\DDTrace\RootSpanData $span, int $status, array $headers, ?mixed $body = null): ?array {} + function notify_commit(\DDTrace\RootSpanData $span, int $status, array $headers, mixed $body = null): ?array {} /** * Sets a function to be called when blocking a request midway. diff --git a/ext/ddtrace_arginfo.h b/ext/ddtrace_arginfo.h index 7d670b1fe8..a68293da30 100644 --- a/ext/ddtrace_arginfo.h +++ b/ext/ddtrace_arginfo.h @@ -1,5 +1,5 @@ /* This is a generated file, edit the .stub.php file instead. - * Stub hash: fa4bda312fa3b405b09e09c6bc81a05d2a8e3372 */ + * Stub hash: 5eb7dd922aab52cab793bd947871d8ee8ee0c284 */ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_trace_method, 0, 3, _IS_BOOL, 0) ZEND_ARG_TYPE_INFO(0, className, IS_STRING, 0) @@ -170,7 +170,7 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_notify_commi ZEND_ARG_OBJ_INFO(0, span, DDTrace\\RootSpanData, 0) ZEND_ARG_TYPE_INFO(0, status, IS_LONG, 0) ZEND_ARG_TYPE_INFO(0, headers, IS_ARRAY, 0) - ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 1, "null") + ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 0, "null") ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_set_blocking_function, 0, 2, IS_VOID, 0) From 2a704316e9fc898c2aec410f5eb26f95ff5ad52b Mon Sep 17 00:00:00 2001 From: Alexandre Choura Date: Thu, 14 Nov 2024 09:37:48 +0100 Subject: [PATCH 23/23] fix: Bracket mix issues --- ext/hook/uhook.stub.php | 279 ++++++++++++++-------------- ext/hook/uhook_arginfo.h | 9 +- ext/hook/uhook_attributes.stub.php | 63 +++---- ext/hook/uhook_attributes_arginfo.h | 16 +- 4 files changed, 182 insertions(+), 185 deletions(-) diff --git a/ext/hook/uhook.stub.php b/ext/hook/uhook.stub.php index 39c8850775..a7143d52eb 100644 --- a/ext/hook/uhook.stub.php +++ b/ext/hook/uhook.stub.php @@ -2,157 +2,158 @@ /** @generate-class-entries */ -namespace DDTrace; +namespace DDTrace { + + class HookData { + /** + * Arbitrary data to be passed from a begin-hook to an end-hook + */ + public mixed $data; + + /** + * The hook id, which triggered that particular hook + */ + public int $id; + + /** + * A zero-indexed array of all arguments. + * On file inclusions, this will be an array with a single element containing the filename. + */ + public array $args; + + /** + * The returned value. This may be a reference, if the value was returned by reference. + * Uninitialized in a begin hook. + */ + public mixed $returned; + + /** + * The possible thrown exception within that function. + * Uninitialized in a begin hook. + */ + public ?\Throwable $exception; + + /** + * Creates a span if none exists yet, otherwise returns the span attached to the current function call. + * If called outside the pre-hook and no span is attached yet, it will return an empty span object. + * + * @param SpanStack|SpanData|null $parent May be specified to start a span on a specific stack. + * As an example, when instrumenting closures, it might conceptually make + * sense to attach the Closure to the current executing function instead of + * where it ends up called. In that case the initial call to span() needs to + * provide the proper stack. + * @return SpanData The new or existing span. + */ + public function span(SpanStack|SpanData|null $parent = null): SpanData {} + + /** + * Works similarly to self::spqn(), but always pushes the span onto the active span stack, even if running in + * limited mode. + * + * @param SpanStack|SpanData|null $parent See self::span(). + * @return SpanData The new or existing span. + */ + public function unlimitedSpan(SpanStack|SpanData|null $parent = null): SpanData {} + + /** + * Replaces the arguments of a function call. Must be called within a pre-hook. + * It is not allowed to pass more arguments to a function that currently on the stack or total number or arguments, + * whichever is greater. + * + * @param array $arguments An array of arguments, which will replace the hooked functions arguments. + * @return bool 'true' on success, otherwise 'false' + */ + public function overrideArguments(array $arguments): bool {} + + /** + * Replaces the return value of a function call. Must be called within a post-hook. + * Note that the return value is not checked. + * + * @prefer-ref $value + * @param mixed $value A value which will replace the original return value. + * @return bool 'true' on success, otherwise 'false' + */ + public function overrideReturnValue(mixed $value): bool {} + + /** + * Replaces the exception thrown by a function call. Must be called within a post-hook. + * + * @param \Throwable|null $exception An exception which will replace the original exception. + * @return bool 'true' on success, otherwise 'false' + */ + public function overrideException(\Throwable|null $exception): bool {} + + /** + * Disables inlining of this method. + * @return bool true iif we have a user function + */ + public function disableJitInlining(): bool {} + + /** + * Suppresses the call to the hooked function. Must be called within a pre-hook. + * The method disableJitInlining() should be called unconditionally in hooks using this method. + * @return bool always 'true' + */ + public function suppressCall(): bool {} + + /** + * By default, hooks are not called if the hooked function is called from the hook. + * This method can be used to override this behavior. The next recursive call will trigger the hook. + * @return bool 'true' if called from the hook, which should always be the case + */ + public function allowNestedHook(): bool {} + + /** + * The name of the file where the function/method call was made from. + * + * @return string The file name, or an empty string if the file name is not available. + */ + public function getSourceFile(): string {} + } -class HookData { /** - * Arbitrary data to be passed from a begin-hook to an end-hook + * @var string */ - public mixed $data; + const HOOK_ALL_FILES = ""; /** - * The hook id, which triggered that particular hook - */ - public int $id; - - /** - * A zero-indexed array of all arguments. - * On file inclusions, this will be an array with a single element containing the filename. - */ - public array $args; - - /** - * The returned value. This may be a reference, if the value was returned by reference. - * Uninitialized in a begin hook. - */ - public mixed $returned; - - /** - * The possible thrown exception within that function. - * Uninitialized in a begin hook. - */ - public ?\Throwable $exception; - - /** - * Creates a span if none exists yet, otherwise returns the span attached to the current function call. - * If called outside the pre-hook and no span is attached yet, it will return an empty span object. + * Only hooks the specific instance of the Closure, i.e. independent instantiations of the same Closure are not hooked. * - * @param SpanStack|SpanData|null $parent May be specified to start a span on a specific stack. - * As an example, when instrumenting closures, it might conceptually make - * sense to attach the Closure to the current executing function instead of - * where it ends up called. In that case the initial call to span() needs to - * provide the proper stack. - * @return SpanData The new or existing span. + * @var int + * @cvalue HOOK_INSTANCE */ - public function span(SpanStack|SpanData|null $parent = null): SpanData; + const HOOK_INSTANCE = UNKNOWN; /** - * Works similarly to self::spqn(), but always pushes the span onto the active span stack, even if running in - * limited mode. - * - * @param SpanStack|SpanData|null $parent See self::span(). - * @return SpanData The new or existing span. + * @param string|\Closure|\Generator $target The function to hook. + * If a string is passed, it must be either a function name or referencing + * a method in "Classname::methodname" format. Alternatively it may be a file + * name or the DDTrace\HOOK_ALL_FILES constant. Can be a relative path + * starting with ./ or ../ too. + * If a Closure is passed, the hook only applies to the current instance + * of that Closure. + * If a Generator is passed, the active function name or Closure is extracted + * and the hook applied to that. + * @param null|\Closure(\DDTrace\HookData) $begin Called before the hooked function is invoked. + * @param null|\Closure(\DDTrace\HookData) $end Called after the hooked function is invoked. + * @param int $flags The only accepted flag currently is DDTrace\HOOK_INSTANCE. + * @return int An integer which can be used to remove a hook via DDTrace\remove_hook. */ - public function unlimitedSpan(SpanStack|SpanData|null $parent = null): SpanData; + function install_hook( + string|callable|\Closure|\Generator $target, + ?\Closure $begin = null, + ?\Closure $end = null, + int $flags = 0 + ): int {} /** - * Replaces the arguments of a function call. Must be called within a pre-hook. - * It is not allowed to pass more arguments to a function that currently on the stack or total number or arguments, - * whichever is greater. + * Removes an installed hook by its id, as returned by install_hook or HookData->id. * - * @param array $arguments An array of arguments, which will replace the hooked functions arguments. - * @return bool 'true' on success, otherwise 'false' + * @param int $id The id to remove. + * @param string $location A class name (which inherits this hook through inheritance), which to specifically remove + * this hook from. + * @return void no return, not formally declared void because of a buggy debug assertion in PHP 7.1 + * ("return value must be of type void, null returned") */ - public function overrideArguments(array $arguments): bool; - - /** - * Replaces the return value of a function call. Must be called within a post-hook. - * Note that the return value is not checked. - * - * @prefer-ref $value - * @param mixed $value A value which will replace the original return value. - * @return bool 'true' on success, otherwise 'false' - */ - public function overrideReturnValue(mixed $value): bool; - - /** - * Replaces the exception thrown by a function call. Must be called within a post-hook. - * - * @param \Throwable|null $exception An exception which will replace the original exception. - * @return bool 'true' on success, otherwise 'false' - */ - public function overrideException(\Throwable|null $exception): bool; - - /** - * Disables inlining of this method. - * @return bool true iif we have a user function - */ - public function disableJitInlining(): bool; - - /** - * Suppresses the call to the hooked function. Must be called within a pre-hook. - * The method disableJitInlining() should be called unconditionally in hooks using this method. - * @return bool always 'true' - */ - public function suppressCall(): bool; - - /** - * By default, hooks are not called if the hooked function is called from the hook. - * This method can be used to override this behavior. The next recursive call will trigger the hook. - * @return bool 'true' if called from the hook, which should always be the case - */ - public function allowNestedHook(): bool; - - /** - * The name of the file where the function/method call was made from. - * - * @return string The file name, or an empty string if the file name is not available. - */ - public function getSourceFile(): string; + function remove_hook(int $id, string $location = "") {} } - -/** - * @var string - */ -const HOOK_ALL_FILES = ""; - -/** - * Only hooks the specific instance of the Closure, i.e. independent instantiations of the same Closure are not hooked. - * - * @var int - * @cvalue HOOK_INSTANCE - */ -const HOOK_INSTANCE = UNKNOWN; - -/** - * @param string|\Closure|\Generator $target The function to hook. - * If a string is passed, it must be either a function name or referencing - * a method in "Classname::methodname" format. Alternatively it may be a file - * name or the DDTrace\HOOK_ALL_FILES constant. Can be a relative path - * starting with ./ or ../ too. - * If a Closure is passed, the hook only applies to the current instance - * of that Closure. - * If a Generator is passed, the active function name or Closure is extracted - * and the hook applied to that. - * @param null|\Closure(\DDTrace\HookData) $begin Called before the hooked function is invoked. - * @param null|\Closure(\DDTrace\HookData) $end Called after the hooked function is invoked. - * @param int $flags The only accepted flag currently is DDTrace\HOOK_INSTANCE. - * @return int An integer which can be used to remove a hook via DDTrace\remove_hook. - */ -function install_hook( - string|callable|\Closure|\Generator $target, - ?\Closure $begin = null, - ?\Closure $end = null, - int $flags = 0 -): int {} - -/** - * Removes an installed hook by its id, as returned by install_hook or HookData->id. - * - * @param int $id The id to remove. - * @param string $location A class name (which inherits this hook through inheritance), which to specifically remove - * this hook from. - * @return void no return, not formally declared void because of a buggy debug assertion in PHP 7.1 - * ("return value must be of type void, null returned") - */ -function remove_hook(int $id, string $location = "") {} diff --git a/ext/hook/uhook_arginfo.h b/ext/hook/uhook_arginfo.h index 13b73c1e73..e0af7e161e 100644 --- a/ext/hook/uhook_arginfo.h +++ b/ext/hook/uhook_arginfo.h @@ -1,5 +1,5 @@ /* This is a generated file, edit the .stub.php file instead. - * Stub hash: eccfac3f3ffe92ae1390f729e053a3e161bdab4b */ + * Stub hash: 4b2f667462bc9e7bed94b2c9a479b85f3086b521 */ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_install_hook, 0, 1, IS_LONG, 0) ZEND_ARG_OBJ_TYPE_MASK(0, target, Closure|Generator, MAY_BE_STRING|MAY_BE_CALLABLE, NULL) @@ -41,7 +41,6 @@ ZEND_END_ARG_INFO() ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_class_DDTrace_HookData_getSourceFile, 0, 0, IS_STRING, 0) ZEND_END_ARG_INFO() - ZEND_FUNCTION(DDTrace_install_hook); ZEND_FUNCTION(DDTrace_remove_hook); ZEND_METHOD(DDTrace_HookData, span); @@ -54,14 +53,12 @@ ZEND_METHOD(DDTrace_HookData, suppressCall); ZEND_METHOD(DDTrace_HookData, allowNestedHook); ZEND_METHOD(DDTrace_HookData, getSourceFile); - static const zend_function_entry ext_functions[] = { - ZEND_NS_FALIAS("DDTrace", install_hook, DDTrace_install_hook, arginfo_DDTrace_install_hook) - ZEND_NS_FALIAS("DDTrace", remove_hook, DDTrace_remove_hook, arginfo_DDTrace_remove_hook) + ZEND_RAW_FENTRY(ZEND_NS_NAME("DDTrace", "install_hook"), zif_DDTrace_install_hook, arginfo_DDTrace_install_hook, 0, NULL, NULL) + ZEND_RAW_FENTRY(ZEND_NS_NAME("DDTrace", "remove_hook"), zif_DDTrace_remove_hook, arginfo_DDTrace_remove_hook, 0, NULL, NULL) ZEND_FE_END }; - static const zend_function_entry class_DDTrace_HookData_methods[] = { ZEND_ME(DDTrace_HookData, span, arginfo_class_DDTrace_HookData_span, ZEND_ACC_PUBLIC) ZEND_ME(DDTrace_HookData, unlimitedSpan, arginfo_class_DDTrace_HookData_unlimitedSpan, ZEND_ACC_PUBLIC) diff --git a/ext/hook/uhook_attributes.stub.php b/ext/hook/uhook_attributes.stub.php index 9259ef2e14..e8e699acbf 100644 --- a/ext/hook/uhook_attributes.stub.php +++ b/ext/hook/uhook_attributes.stub.php @@ -2,40 +2,41 @@ /** @generate-class-entries */ -namespace DDTrace; +namespace DDTrace { -require "Zend/zend_attributes.stub.php"; + require "Zend/zend_attributes.stub.php"; -// phpcs:disable Squiz.Functions.MultiLineFunctionDeclaration.Indent + // phpcs:disable Squiz.Functions.MultiLineFunctionDeclaration.Indent -/** - * If specified, this attribute ensures that all calls to that function are traced. - */ -#[\Attribute(\Attribute::TARGET_FUNCTION | \Attribute::TARGET_METHOD)] -final class Trace { /** - * @param string $name The operation name to be assigned to the span. Defaults to the function name. - * @param string $resource The resource to be assigned to the span. - * @param string $type The type to be assigned to the span. - * @param string $service The service to be assigned to the span. Defaults to default or inherited service name. - * @param array $tags The tags to be assigned to the span. - * @param bool|array $saveArgs Whether arguments shall be saved as tags on the span. True to save them all. - False to save none. An array with parameter names to save only select ones. - * @param bool $saveReturn Whether to save return values (including yielded values on generators) on the span. - * @param bool $recurse Whether recursive calls shall be traced. - * @param bool $run_if_limited Whether the function shall be traced in limited mode. (E.g. when span limit exceeded) + * If specified, this attribute ensures that all calls to that function are traced. */ - public function __construct( - string $name = "", - string $resource = "", - string $type = "", - string $service = "", - array $tags = [], -/* disable for now, until final decision on the API is taken - bool|array $saveArgs = false, - bool $saveReturn = false, -*/ - bool $recurse = true, - bool $run_if_limited = false - ) {} + #[\Attribute(\Attribute::TARGET_FUNCTION | \Attribute::TARGET_METHOD)] + final class Trace { + /** + * @param string $name The operation name to be assigned to the span. Defaults to the function name. + * @param string $resource The resource to be assigned to the span. + * @param string $type The type to be assigned to the span. + * @param string $service The service to be assigned to the span. Defaults to default or inherited service name. + * @param array $tags The tags to be assigned to the span. + * @param bool|array $saveArgs Whether arguments shall be saved as tags on the span. True to save them all. + * False to save none. An array with parameter names to save only select ones. + * @param bool $saveReturn Whether to save return values (including yielded values on generators) on the span. + * @param bool $recurse Whether recursive calls shall be traced. + * @param bool $run_if_limited Whether the function shall be traced in limited mode. (E.g. when span limit exceeded) + */ + public function __construct( + string $name = "", + string $resource = "", + string $type = "", + string $service = "", + array $tags = [], + /* disable for now, until final decision on the API is taken + bool|array $saveArgs = false, + bool $saveReturn = false, + */ + bool $recurse = true, + bool $run_if_limited = false + ) {} + } } diff --git a/ext/hook/uhook_attributes_arginfo.h b/ext/hook/uhook_attributes_arginfo.h index 8d1410faa2..4c64d765a8 100644 --- a/ext/hook/uhook_attributes_arginfo.h +++ b/ext/hook/uhook_attributes_arginfo.h @@ -1,5 +1,5 @@ /* This is a generated file, edit the .stub.php file instead. - * Stub hash: 6e695ec08c44692b1b361afd99a4521067cfb6de */ + * Stub hash: 90919c9c350e86acd6fe3c8d06753918d5e0572b */ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_DDTrace_Trace___construct, 0, 0, 0) ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, name, IS_STRING, 0, "\"\"") @@ -11,10 +11,8 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_class_DDTrace_Trace___construct, 0, 0, 0) ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, run_if_limited, _IS_BOOL, 0, "false") ZEND_END_ARG_INFO() - ZEND_METHOD(DDTrace_Trace, __construct); - static const zend_function_entry class_DDTrace_Trace_methods[] = { ZEND_ME(DDTrace_Trace, __construct, arginfo_class_DDTrace_Trace___construct, ZEND_ACC_PUBLIC) ZEND_FE_END @@ -28,12 +26,12 @@ static zend_class_entry *register_class_DDTrace_Trace(void) class_entry = zend_register_internal_class_ex(&ce, NULL); class_entry->ce_flags |= ZEND_ACC_FINAL; - zend_string *attribute_name_Attribute_class_DDTrace_Trace = zend_string_init_interned("Attribute", sizeof("Attribute") - 1, 1); - zend_attribute *attribute_Attribute_class_DDTrace_Trace = zend_add_class_attribute(class_entry, attribute_name_Attribute_class_DDTrace_Trace, 1); - zend_string_release(attribute_name_Attribute_class_DDTrace_Trace); - zval attribute_Attribute_class_DDTrace_Trace_arg0; - ZVAL_LONG(&attribute_Attribute_class_DDTrace_Trace_arg0, ZEND_ATTRIBUTE_TARGET_FUNCTION | ZEND_ATTRIBUTE_TARGET_METHOD); - ZVAL_COPY_VALUE(&attribute_Attribute_class_DDTrace_Trace->args[0].value, &attribute_Attribute_class_DDTrace_Trace_arg0); + zend_string *attribute_name_Attribute_class_DDTrace_Trace_0 = zend_string_init_interned("Attribute", sizeof("Attribute") - 1, 1); + zend_attribute *attribute_Attribute_class_DDTrace_Trace_0 = zend_add_class_attribute(class_entry, attribute_name_Attribute_class_DDTrace_Trace_0, 1); + zend_string_release(attribute_name_Attribute_class_DDTrace_Trace_0); + zval attribute_Attribute_class_DDTrace_Trace_0_arg0; + ZVAL_LONG(&attribute_Attribute_class_DDTrace_Trace_0_arg0, ZEND_ATTRIBUTE_TARGET_FUNCTION | ZEND_ATTRIBUTE_TARGET_METHOD); + ZVAL_COPY_VALUE(&attribute_Attribute_class_DDTrace_Trace_0->args[0].value, &attribute_Attribute_class_DDTrace_Trace_0_arg0); return class_entry; }