From 0367d81e896c13a295896bfacf84726bb5d8f68f Mon Sep 17 00:00:00 2001 From: Alessandro Lai Date: Wed, 10 Jul 2024 09:01:26 +0200 Subject: [PATCH] Add DataDog tracing stub --- ddtrace/ddtrace.stub.php | 1051 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1051 insertions(+) create mode 100644 ddtrace/ddtrace.stub.php diff --git a/ddtrace/ddtrace.stub.php b/ddtrace/ddtrace.stub.php new file mode 100644 index 000000000..b03d25973 --- /dev/null +++ b/ddtrace/ddtrace.stub.php @@ -0,0 +1,1051 @@ +) applied to the 'meta' section of the root span + * @param bool|null $propagate If set to 'true', user's information will be propagated in distributed traces + */ + function set_user(string $userId, array $metadata = [], bool|null $propagate = null): void {} + + /** + * Close child spans of a parent span if a non-internal span is given, + * else if 'null' is given, close active, non-internal spans + * + * @param SpanData|null $span The parent span + * @return false|int 'false' if spans couldn't be closed, else the number of span closed + */ + function close_spans_until(?SpanData $span): false|int {} + + /** + * Get the active span + * + * @return SpanData|null 'null' if tracing isn't enabled or there isn't any active span, else the active span + */ + function active_span(): null|SpanData {} + + /** + * Get the root span + * + * @return SpanData|null 'null' if tracing isn't enabled or if the active stack doesn't have a root span, + * else the root span of the active stack + */ + function root_span(): null|RootSpanData {} + + /** + * Start a new custom user-span on the top of the stack. If no active span exists, the new created span will be a + * root span, on its own new span stack (i.e., it is equivalent to 'start_trace_span'). In that case, distributed + * tracing information will be applied if available. + * + * @param float $startTime Start time of the span in seconds. + * @return SpanData|false The newly started span, or 'false' if a wrong parameter was given. + */ + function start_span(float $startTime = 0): SpanData|false {} + + /** + * Close the currently active user-span on the top of the stack + * + * @param float $finishTime Finish time in seconds. Defaults to now if zero. + * @return false|null 'false' if unexpected parameters were given, else 'null' + */ + function close_span(float $finishTime = 0): false|null {} + + /** + * Update the duration of an already closed span + * + * Note that this API won't cause an update of a closed span if it's already sent. Its usage, particularly on + * root spans with datadog.trace.auto_flush_enabled may not yield the expected results. + * + * @param SpanData $span The span to update. + * @param float $finishTime Finish time in seconds. Defaults to now if zero. + * @return false|null 'false' if unexpected parameters were given, else 'null' + */ + function update_span_duration(SpanData $span, float $finishTime = 0): false|null {} + + /** + * Start a new trace + * + * More precisely, a new root span stack will be created and switched on to, and a new span started. + * + * @param float $startTime Start time of the span in seconds. + * @return SpanData The newly created root span + */ + function start_trace_span(float $startTime = 0): SpanData {} + + /** + * Get the active stack + * + * @return SpanStack|null A copy of the active stack, or 'null' if the tracer is disabled. Won't happen + * under normal operation. + */ + function active_stack(): SpanStack|null {} + + /** + * Initialize a new span stack and switch to it. If tracing isn't enabled, a root span stack will be created. + * + * @return SpanStack The newly created span stack + */ + function create_stack(): SpanStack {} + + /** + * Switch back to a specific stack (even if there is no active span on that stack), or to the parent of the active + * stack if no stack is given. + * + * @param SpanData|SpanStack|null $newStack Stack to switch to. If 'null' is given, switches to the parent of the + * active stack. If a SpanData object is given, it will switch to the stack of the latter. + * @return null|false|SpanStack The newly active stack, or 'null' if the tracer is disabled (Won't happen under + * normal operation), or 'false' if unexpected parameters were given. + */ + function switch_stack(SpanData|SpanStack|null $newStack = null): null|false|SpanStack {} + + /** + * Set the priority sampling level + * + * @param int $priority The priority level to be set to. + * @param bool|null $global If set to 'true' and if there is no active stack (or the active stack doesn't have a + * root span), then the default priority sampling will be set to the provided priority level. Otherwise, the root's + * priority sampling level will be updated with the new value. + */ + function set_priority_sampling(int $priority, bool $global = false): void {} + + /** + * Get the priority sampling level + * + * @param bool|null $global If set to 'true' and if there is no active stack (or the active stack doesn't have a + * root span), then the default priority sampling will be returned, else it will be fetched from the root. + * @return int|null The priority sampling level, or 'null' if an unexpected parameter was given. + */ + function get_priority_sampling(bool $global = false): int|null {} + + /** + * Sanitize an exception + * + * @param \Exception|\Throwable $exception + * @param int $skipFrames The number of frames to be dropped from the start. E.g. to hide the fact that we're + * in a hook function. + * @return string + */ + function get_sanitized_exception_trace(\Exception|\Throwable $exception, int $skipFrames = 0): string {} + + /** + * Update datadog headers for distributed tracing for new spans. Also applies this information to the current trace, + * if there is one, as well as the future ones if it isn't overwritten + * + * @param null|array|callable(string):mixed $headersOrCallback Either an array with a lowercase header to value mapping, + * or a callback, which given a header name for distributed tracing, returns the value it should be updated to. If null, + * this reads the headers directly from the $_SERVER superglobal. + */ + function consume_distributed_tracing_headers(null|array|callable $headersOrCallback): void {} + + /** + * Get information on the key-value pairs of the datadog headers for distributed tracing + * + * @param null|string[] $inject The types of sampling headers which shall be generated, equivalent to what + * DD_TRACE_PROPAGATION_STYLE_INJECT supports. Defaults to DD_TRACE_PROPAGATION_STYLE_INJECT if null. + * + * @return array{x-datadog-sampling-priority: string, + * x-datadog-origin: string, + * x-datadog-trace-id: string, + * x-datadog-parent-id: string, + * traceparent: string, + * tracestate: string + * } + */ + function generate_distributed_tracing_headers(array|null $inject = null): array {} + + /** + * Searches parent frames to see whether it's currently within a catch block and returns that exception. + * + * @return \Throwable|null The active exception if there is one, else 'null'. + */ + function find_active_exception(): \Throwable|null {} + + /** + * Retrieve IPs from the given array if valid headers are found, and return them in + * a metadata formatting + * + * @param string[] $headers + * @return array + */ + function extract_ip_from_headers(array $headers): array {} + + /** + * Get startup information in JSON format + * + * @return string Startup information + */ + function startup_logs(): string {} + + /** + * Return the id of the current trace + * + * @return string The id of the current trace + */ + function trace_id(): string {} + + /** + * Formatted trace id to be used for logs correlation. + * + * This function handles 128-bit trace ids and 64-bit trace ids. More specifically, if + * DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED is set to true and the current trace id is 128-bit, then the trace id + * will be returned as a 32-character hexadecimal string. Otherwise, the trace id will be returned as the + * decimal representation of the 64-bit trace id. + * + * @return string The formatted id of the current trace + */ + function logs_correlation_trace_id(): string {} + + /** + * Get information on the current context + * + * @return array{trace_id: string, span_id: string, version: string, env: string} + */ + function current_context(): array {} + + /** + * Apply the distributed tracing information on the current and future spans. That API can be called if there is no + * other currently active span. + * + * The distributed tracing context can be reset by calling 'set_distributed_tracing_context("0", "0")' + * + * @param string $traceId The unique integer (128-bit unsigned) ID of the trace containing this span + * @param string $parentId The span integer ID of the parent span + * @param string|null $origin The distributed tracing origin + * @param array|string|null $propagated_tags If provided, propagated tags from the root span will be cleared and + * replaced by the given tags and applied to existing spans + * @return bool 'true' if the distributed tracing context was properly set, else 'false' if an error occurred + */ + function set_distributed_tracing_context( + string $traceId, + string $parentId, + ?string $origin = null, + array|string|null $propagated_tags = null + ): bool {} + + /** + * Closes all spans and force-send finished traces to the agent + */ + function flush(): void {} + + /** + * Registers an array to be populated with spans for each request during the next curl_multi_exec() call. + * + * @internal + * @param list{\CurlHandle, SpanData}[] $array An array which will be populated with curl handles and spans. + */ + function curl_multi_exec_get_request_spans(&$array): void {} + + /** + * Update a DogStatsD counter + * + * @param string $metric The metric name + * @param int $value The metric value + * @param array $tags A list of tags associated to the metric + */ + function dogstatsd_count(string $metric, int $value, array $tags = []): void {} + + /** + * Update a DogStatsD distribution + * + * @param string $metric The metric name + * @param float $value The metric value + * @param array $tags A list of tags associated to the metric + */ + function dogstatsd_distribution(string $metric, float $value, array $tags = []): void {} + + /** + * Update a DogStatsD gauge + * + * @param string $metric The metric name + * @param float $value The metric value + * @param array $tags A list of tags associated to the metric + */ + function dogstatsd_gauge(string $metric, float $value, array $tags = []): void {} + + /** + * Update a DogStatsD histogram + * + * @param string $metric The metric name + * @param float $value The metric value + * @param array $tags A list of tags associated to the metric + */ + function dogstatsd_histogram(string $metric, float $value, array $tags = []): void {} + + /** + * Update a DogStatsD set + * + * @param string $metric The metric name + * @param int $value The metric value + * @param array $tags A list of tags associated to the metric + */ + function dogstatsd_set(string $metric, int $value, array $tags = []): void {} +} + +namespace DDTrace\System { + + /** + * Get the unique identifier of the container + * + * @return string|null The container id, or 'null' if no id was found + */ + function container_id(): string|null {} +} + +namespace DDTrace\Config { + + /** + * Check if the app analytics of an app is enabled for a given integration + * + * @param string $integrationName The name of the integration (e.g., mysqli) + * @return bool The status of the app analytics of the integration + */ + function integration_analytics_enabled(string $integrationName): bool {} + + /** + * Check the app analytics sample rate of a given integration + * + * @param string $integrationName The name of the integration (e.g., mysqli) + * @return float The sample rate of the app analytics of the integration + */ + function integration_analytics_sample_rate(string $integrationName): float {} +} + +namespace DDTrace\UserRequest { + /** + * If there are any listeners of user request events. + * @return bool true iif there are any listeners + */ + function has_listeners(): bool {} + + /** + * Notifies the user request listeners of the start of a user request. + * + * @param \DDTrace\Span $span the span associated with this user request. + * @param array $data an array with keys named '_GET', '_POST', '_SERVER', '_FILES', '_COOKIE' + * @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 {} + + /** + * Notifies the user request listeners of the imminence of a commit, and allows for the replacement of the response. + * @param \DDTrace\Span $span the span associated with this user request. + * @param int $status the HTTP status code of the response + * @param array $headers the HTTP headers of the response in the form name => array(values) + * @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 {} + + /** + * Sets a function to be called when blocking a request midway. + * + * @param \DDTrace\RootSpanData $span + * @param callable $blockingFunction a blocking function taking an array with the keys 'status', 'headers', 'body' + * @return void + */ + function set_blocking_function(\DDTrace\RootSpanData $span, callable $blockingFunction): void {} +} + +namespace DDTrace\Testing { + /** + * Overrides PHP's default error handling. + * + * @param string $message Error message + * @param int $errorType Error Type. Supported error types are: E_ERROR, E_WARNING, E_PARSE, E_NOTICE, E_CORE_ERROR, + * E_CORE_WARNING, E_COMPILE_ERROR, E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE, E_STRICT, E_RECOVERABLE_ERROR, + * E_DEPRECATED, E_USER_DEPRECATED + */ + function trigger_error(string $message, int $errorType): void {} +} + +namespace DDTrace\Internal { + /** + * @var int + * @cvalue DDTRACE_SPAN_FLAG_OPENTELEMETRY + */ + const SPAN_FLAG_OPENTELEMETRY = UNKNOWN; + + /** + * @var int + * @cvalue DDTRACE_SPAN_FLAG_OPENTRACING + */ + const SPAN_FLAG_OPENTRACING = UNKNOWN; + + /** + * Adds a flag to a span. + * + * @internal + * + * @param \DDTrace\SpanData $span the span to flag + * @param int $flag the flag to add to the span + */ + function add_span_flag(\DDTrace\SpanData $span, int $flag): void {} + + /** + * To be called when a fork is performed. + * + * @internal + */ + function handle_fork(): void {} +} + +namespace { + + /** + * @var string + * @cvalue PHP_DDTRACE_VERSION + */ + const DD_TRACE_VERSION = UNKNOWN; + + /** + * @var int + * @cvalue PRIORITY_SAMPLING_AUTO_KEEP + */ + const DD_TRACE_PRIORITY_SAMPLING_AUTO_KEEP = UNKNOWN; + + /** + * @var int + * @cvalue PRIORITY_SAMPLING_AUTO_REJECT + */ + const DD_TRACE_PRIORITY_SAMPLING_AUTO_REJECT = UNKNOWN; + + /** + * @var int + * @cvalue PRIORITY_SAMPLING_USER_KEEP + */ + const DD_TRACE_PRIORITY_SAMPLING_USER_KEEP = UNKNOWN; + + /** + * @var int + * @cvalue PRIORITY_SAMPLING_USER_REJECT + */ + const DD_TRACE_PRIORITY_SAMPLING_USER_REJECT = UNKNOWN; + + /** + * @var int + * @cvalue DDTRACE_PRIORITY_SAMPLING_UNKNOWN + */ + const DD_TRACE_PRIORITY_SAMPLING_UNKNOWN = UNKNOWN; + + /** + * @var int + * @cvalue DDTRACE_PRIORITY_SAMPLING_UNSET + */ + const DD_TRACE_PRIORITY_SAMPLING_UNSET = UNKNOWN; + + + /** + * Get the value of a DD environment variable + * + * @param string $envName Environment variable name + * @return mixed Value of the environment variable + */ + function dd_trace_env_config(string $envName): mixed {} + + /** + * Disable tracing in the current request + * + * @return bool + */ + function dd_trace_disable_in_request(): bool {} + + /** + * (Noop/To do) Untrace traced functions and methods + * + * @internal + * @return bool 'true' if reset was successful, else 'false' + */ + function dd_trace_reset(): bool {} + + /** + * If tracing is enabled, serialize the trace into a string to send to the agent + * + * @internal + * @param array $traceArray Serialize values must be of type array, string, int, float, bool or null + * @return bool|string The serialized array, else 'false' if an error was encountered + */ + function dd_trace_serialize_msgpack(array $traceArray): bool|string {} + + /** + * Null function to easily breakpoint the execution at specific PHP line in GDB + * + * @internal + * @return bool Return 'true' if tracing is enabled, else 'false' + */ + function dd_trace_noop(mixed ...$args): bool {} + + /** + * Get the parsed value of the memory limit DD_TRACE_MEMORY_LIMIT in binary bytes + * + * @return int The memory limit + */ + function dd_trace_dd_get_memory_limit(): int {} + + /** + * Check if the current memory usage is under the memory limit DD_TRACE_MEMORY_LIMIT + * + * @return bool 'true' if the current memory usage is under the memory limit, else 'false' + */ + function dd_trace_check_memory_under_limit(): bool {} + + /** + * Get the name of the app (DD_SERVICE) + * + * @param string|null $fallbackName Fallback name if the app's name wasn't set + * @return string|null The app name, else the fallback name. Return 'null' if the app name isn't set and no + * fallback name is provided. + */ + function ddtrace_config_app_name(?string $fallbackName = null): null|string {} + + /** + * Check if distributed tracing is enabled (DD_DISTRIBUTED_TRACING) + * + * @return bool 'true' if distributed tracing is enabled, else 'false' + */ + function ddtrace_config_distributed_tracing_enabled(): bool {} + + /** + * Check if tracing is enabled (DD_TRACE_ENABLED) + * + * @return bool 'true' is tracing is enabled, else 'false' + */ + function ddtrace_config_trace_enabled(): bool {} + + /** + * Check if a specific integration is enabled + * + * @param string $integrationName The name of the integration (e.g., mysqli) + * @return bool The status of the integration, or 'false' if tracing isn't enabled. + */ + function ddtrace_config_integration_enabled(string $integrationName): bool {} + + /** + * Send payload to background sender's buffer + * + * @internal + * @param int $numTraces Trace count. Note that at the moment, the background sender is only capable of sending + * exactly one trace + * @param array $curlHeaders HTTP Headers + * @param string $payload HTTP Body + * @return bool 'true' if tracers were successfully sent or if the tracer is disabled, and 'false' if not exactly + * one trace was sent or if the procedure was unsuccessful + */ + function dd_trace_send_traces_via_thread(int $numTraces, array $curlHeaders, string $payload): bool {} + + /** + * Serializes and sends traces to the agent (in the format dd_trace_serialize_closed_spans() returns spans). + * + * @internal + * @param array $traceArray Array in the format returned by dd_trace_serialize_closed_spans() + */ + function dd_trace_buffer_span(array $traceArray): bool {} + + /** + * Used to send any already buffered spans to the agent + * + * @internal + * @return int + */ + function dd_trace_coms_trigger_writer_flush(): int {} + + /** + * Execute a given internal function + * + * Internal functions are: init_and_start_writer, ddtrace_coms_next_group_id, ddtrace_coms_buffer_span, + * ddtrace_coms_buffer_data, shutdown_writer, set_writer_send_on_flush, test_consumer, test_writers, + * test_msgpack_consumer, synchronous_flush, and root_span_add_tag + * + * @internal + * @param string $functionName Internal function name + * @param mixed $args,... Arguments of the function + * @return mixed false if void function was properly executed, else the return value of it + */ + function dd_trace_internal_fn(string $functionName, mixed ...$args) {} + + /** + * Set the distributed trace id + * + * @param string|null $traceId New trace id + * @return bool 'true' if the change was properly applied, else 'false' + */ + function dd_trace_set_trace_id(?string $traceId = null): bool {} + + /** + * Tracks closed spans + * + * @return int Number of closed spans + */ + function dd_trace_closed_spans_count(): int {} + + /** + * Check if the tracer's current memory usage is higher than the set limits + * + * @return bool 'true' if memory is overused, else 'false' + */ + function dd_trace_tracer_is_limited(): bool {} + + /** + * Get the compiling time of all files compiled up to now (in µs) + * + * @return int Compile time + */ + function dd_trace_compile_time_microseconds(): int {} + + /** + * Get serialized information about closed spans as arrays. Note that calling this function will result in + * automatically closing unfinished spans (destroys the open span stack). + * + * @return array Closed spans data + */ + function dd_trace_serialize_closed_spans(): array {} + + /** + * Get the currently active span id, or the distributed parent trace id if there is no currently active span + * + * @return string Currently active span/trace unique identifier + */ + function dd_trace_peek_span_id(): string {} + + /** + * Force-finish all spans and force-send finished traces to the agent. Note that this function drops (resp. closes) + * all currently open spans if DD_AUTOFINISH_SPANS is set to 'false' (resp. 'true'). Dropped spans are not sent to + * the agent. + */ + function dd_trace_close_all_spans_and_flush(): void {} + + /** + * @alias DDTrace_trace_function + */ + function dd_trace_function(string $functionName, \Closure|array|null $tracingClosureOrConfigArray): bool {} + + /** + * @alias DDTrace_trace_method + */ + function dd_trace_method( + string $className, + string $methodName, + \Closure|array|null $tracingClosureOrConfigArray + ): bool {} + + /** + * Untrace a function or a method. + * + * @param string $functionName The name of the function or method to untrace + * @param string|null $className In the case of a method, its respective class should be provided as well + * @return bool 'true' if the un-tracing process was successful, else 'false' + */ + function dd_untrace(string $functionName, string|null $className = null): bool {} + + /** + * Blocking-call synchronously flushing all spans to the agent + * + * @param int $timeout Timeout in milliseconds to wait for the flush to complete + */ + function dd_trace_synchronous_flush(int $timeout = 100): void {} +}