DSL References

/**
 * Create a Baggage.
 *
 * @param array<string, string> $entries Initial key-value entries
 */
baggage(array $entries) : Baggage

/**
 * Create a Context.
 *
 * If no TraceId is provided, generates a new one.
 * If no Baggage is provided, creates an empty one.
 *
 * @param null|TraceId $traceId Optional TraceId to use
 * @param null|Baggage $baggage Optional Baggage to use
 */
context(?TraceId $traceId, ?Baggage $baggage) : Context

/**
 * Create an InstrumentationScope.
 *
 * @param string $name The instrumentation scope name
 * @param string $version The instrumentation scope version
 * @param null|string $schemaUrl Optional schema URL
 */
instrumentation_scope(string $name, string $version, ?string $schemaUrl, Attributes $attributes) : InstrumentationScope

/**
 * Create a PropagationContext.
 *
 * Value object containing both trace context (SpanContext) and application
 * data (Baggage) that can be propagated across process boundaries.
 *
 * @param null|SpanContext $spanContext Optional span context
 * @param null|Baggage $baggage Optional baggage
 */
propagation_context(?SpanContext $spanContext, ?Baggage $baggage) : PropagationContext

/**
 * Create a Resource.
 *
 * @param array<string, array<bool|float|int|string>|bool|float|int|string>|Attributes $attributes Resource attributes
 */
resource(Attributes|array $attributes) : Resource

/**
 * Create a SpanContext.
 *
 * @param TraceId $traceId The trace ID
 * @param SpanId $spanId The span ID
 * @param null|SpanId $parentSpanId Optional parent span ID
 */
span_context(TraceId $traceId, SpanId $spanId, ?SpanId $parentSpanId) : SpanContext

/**
 * Create a SpanEvent (GenericEvent) with an explicit timestamp.
 *
 * @param string $name Event name
 * @param \DateTimeImmutable $timestamp Event timestamp
 * @param array<string, array<bool|float|int|string>|bool|float|int|string>|Attributes $attributes Event attributes
 */
span_event(string $name, DateTimeImmutable $timestamp, Attributes|array $attributes) : GenericEvent

/**
 * Create a SpanId.
 *
 * If a hex string is provided, creates a SpanId from it.
 * Otherwise, generates a new random SpanId.
 *
 * @param null|string $hex Optional 16-character hexadecimal string
 *
 * @throws \InvalidArgumentException if the hex string is invalid
 */
span_id(?string $hex) : SpanId

/**
 * Create a SpanLink.
 *
 * @param SpanContext $context The linked span context
 * @param array<string, array<bool|float|int|string>|bool|float|int|string>|Attributes $attributes Link attributes
 */
span_link(SpanContext $context, Attributes|array $attributes) : SpanLink

/**
 * Create a TraceId.
 *
 * If a hex string is provided, creates a TraceId from it.
 * Otherwise, generates a new random TraceId.
 *
 * @param null|string $hex Optional 32-character hexadecimal string
 *
 * @throws \InvalidArgumentException if the hex string is invalid
 */
trace_id(?string $hex) : TraceId

/**
 * Create an AlwaysOffExemplarFilter.
 *
 * Never records exemplars. Use this filter to disable exemplar collection
 * entirely for performance optimization.
 */
always_off_exemplar_filter() : AlwaysOffExemplarFilter

/**
 * Create an AlwaysOnExemplarFilter.
 *
 * Records exemplars whenever a span context is present.
 * Use this filter for debugging or when complete trace context is important.
 */
always_on_exemplar_filter() : AlwaysOnExemplarFilter

/**
 * Create an ArrayCarrier.
 *
 * Carrier backed by an associative array with case-insensitive key lookup.
 *
 * @param array<string, string> $data Initial carrier data
 */
array_carrier(array $data) : ArrayCarrier

/**
 * Create a BatchingLogProcessor.
 *
 * Collects log records in memory and exports them in batches for efficiency.
 * Logs are exported when batch size is reached, flush() is called, or shutdown().
 *
 * @param LogExporter $exporter The exporter to send logs to
 * @param int $batchSize Number of logs to collect before exporting (default 512)
 */
batching_log_processor(LogExporter $exporter, int $batchSize) : BatchingLogProcessor

/**
 * Create a BatchingMetricProcessor.
 *
 * Collects metrics in memory and exports them in batches for efficiency.
 * Metrics are exported when batch size is reached, flush() is called, or shutdown().
 *
 * @param MetricExporter $exporter The exporter to send metrics to
 * @param int $batchSize Number of metrics to collect before exporting (default 512)
 */
batching_metric_processor(MetricExporter $exporter, int $batchSize) : BatchingMetricProcessor

/**
 * Create a BatchingSpanProcessor.
 *
 * Collects spans in memory and exports them in batches for efficiency.
 * Spans are exported when batch size is reached, flush() is called, or shutdown().
 *
 * @param SpanExporter $exporter The exporter to send spans to
 * @param int $batchSize Number of spans to collect before exporting (default 512)
 */
batching_span_processor(SpanExporter $exporter, int $batchSize) : BatchingSpanProcessor

/**
 * Create a CachingDetector.
 *
 * Wraps another detector and caches its results to a file. On subsequent
 * calls, returns the cached resource instead of running detection again.
 *
 * @param ResourceDetector $detector The detector to wrap
 * @param null|string $cachePath Cache file path (default: sys_get_temp_dir()/flow_telemetry_resource.cache)
 */
caching_detector(ResourceDetector $detector, ?string $cachePath) : CachingDetector

/**
 * Create a ChainDetector.
 *
 * Combines multiple resource detectors into a chain. Detectors are executed
 * in order and their results are merged. Later detectors take precedence
 * over earlier ones when there are conflicting attribute keys.
 *
 * @param ResourceDetector ...$detectors The detectors to chain
 */
chain_detector(ResourceDetector $detectors) : ChainDetector

/**
 * Create a ComposerDetector.
 *
 * Detects service.name and service.version from Composer's InstalledVersions
 * using the root package information.
 */
composer_detector() : ComposerDetector

/**
 * Create a CompositePropagator.
 *
 * Combines multiple propagators into one. On extract, all propagators are
 * invoked and their contexts are merged. On inject, all propagators are invoked.
 *
 * @param Propagator ...$propagators The propagators to combine
 */
composite_propagator(Propagator $propagators) : CompositePropagator

/**
 * Create a ConsoleLogExporter.
 *
 * Outputs log records to the console with severity-based coloring.
 * Useful for debugging and development.
 *
 * @param bool $colors Whether to use ANSI colors (default: true)
 * @param null|int $maxBodyLength Maximum length for body+attributes column (null = no limit, default: 100)
 * @param ConsoleLogOptions $options Display options for the exporter
 */
console_log_exporter(bool $colors, ?int $maxBodyLength, ConsoleLogOptions $options) : ConsoleLogExporter

/**
 * Create ConsoleLogOptions with all display options enabled (default behavior).
 */
console_log_options() : ConsoleLogOptions

/**
 * Create ConsoleLogOptions with minimal display (legacy compact format).
 */
console_log_options_minimal() : ConsoleLogOptions

/**
 * Create a ConsoleMetricExporter.
 *
 * Outputs metrics to the console with ASCII table formatting.
 * Useful for debugging and development.
 *
 * @param bool $colors Whether to use ANSI colors (default: true)
 * @param ConsoleMetricOptions $options Display options for the exporter
 */
console_metric_exporter(bool $colors, ConsoleMetricOptions $options) : ConsoleMetricExporter

/**
 * Create ConsoleMetricOptions with all display options enabled (default behavior).
 */
console_metric_options() : ConsoleMetricOptions

/**
 * Create ConsoleMetricOptions with minimal display (legacy compact format).
 */
console_metric_options_minimal() : ConsoleMetricOptions

/**
 * Create a ConsoleSpanExporter.
 *
 * Outputs spans to the console with ASCII table formatting.
 * Useful for debugging and development.
 *
 * @param bool $colors Whether to use ANSI colors (default: true)
 * @param ConsoleSpanOptions $options Display options for the exporter
 */
console_span_exporter(bool $colors, ConsoleSpanOptions $options) : ConsoleSpanExporter

/**
 * Create ConsoleSpanOptions with all display options enabled (default behavior).
 */
console_span_options() : ConsoleSpanOptions

/**
 * Create ConsoleSpanOptions with minimal display (legacy compact format).
 */
console_span_options_minimal() : ConsoleSpanOptions

/**
 * Create an EnvironmentDetector.
 *
 * Detects resource attributes from OpenTelemetry standard environment variables:
 * - OTEL_SERVICE_NAME: Sets service.name attribute
 * - OTEL_RESOURCE_ATTRIBUTES: Sets additional attributes in key=value,key2=value2 format
 */
environment_detector() : EnvironmentDetector

/**
 * Create a HostDetector.
 *
 * Detects host information including host.name, host.arch, and host.id
 * (from /etc/machine-id on Linux or IOPlatformUUID on macOS).
 */
host_detector() : HostDetector

/**
 * Create a LoggerProvider.
 *
 * Creates a provider that uses a LogProcessor for processing logs.
 * For void/disabled logging, pass void_processor().
 * For memory-based testing, pass memory_processor() with exporters.
 *
 * @param LogProcessor $processor The processor for logs
 * @param ClockInterface $clock The clock for timestamps
 * @param ContextStorage $contextStorage Storage for span correlation
 * @param LogRecordLimits $limits Limits for log record attributes
 */
logger_provider(LogProcessor $processor, ClockInterface $clock, ContextStorage $contextStorage, LogRecordLimits $limits) : LoggerProvider

/**
 * Create LogRecordLimits configuration.
 *
 * LogRecordLimits controls the maximum amount of data a log record can collect,
 * preventing unbounded memory growth and ensuring reasonable log record sizes.
 *
 * @param int $attributeCountLimit Maximum number of attributes per log record
 * @param null|int $attributeValueLengthLimit Maximum length for string attribute values (null = unlimited)
 */
log_record_limits(int $attributeCountLimit, ?int $attributeValueLengthLimit) : LogRecordLimits

/**
 * Create a ManualDetector.
 *
 * Returns manually specified resource attributes. Use this when you need
 * to set attributes explicitly rather than detecting them automatically.
 *
 * @param array<string, array<bool|float|int|string>|bool|float|int|string> $attributes Resource attributes
 */
manual_detector(array $attributes) : ManualDetector

/**
 * Create a MemoryContextStorage.
 *
 * In-memory context storage for storing and retrieving the current context.
 * A single instance should be shared across all providers within a request lifecycle.
 *
 * @param null|Context $context Optional initial context
 */
memory_context_storage(?Context $context) : MemoryContextStorage

/**
 * Create a MemoryLogExporter.
 *
 * Log exporter that stores data in memory.
 * Provides direct getter access to exported log entries.
 * Useful for testing and inspection without serialization.
 */
memory_log_exporter() : MemoryLogExporter

/**
 * Create a MemoryLogProcessor.
 *
 * Log processor that stores log records in memory and exports via configured exporter.
 * Useful for testing.
 *
 * @param LogExporter $exporter The exporter to send logs to
 */
memory_log_processor(LogExporter $exporter) : MemoryLogProcessor

/**
 * Create a MemoryMetricExporter.
 *
 * Metric exporter that stores data in memory.
 * Provides direct getter access to exported metrics.
 * Useful for testing and inspection without serialization.
 */
memory_metric_exporter() : MemoryMetricExporter

/**
 * Create a MemoryMetricProcessor.
 *
 * Metric processor that stores metrics in memory and exports via configured exporter.
 * Useful for testing.
 *
 * @param MetricExporter $exporter The exporter to send metrics to
 */
memory_metric_processor(MetricExporter $exporter) : MemoryMetricProcessor

/**
 * Create a MemorySpanExporter.
 *
 * Span exporter that stores data in memory.
 * Provides direct getter access to exported spans.
 * Useful for testing and inspection without serialization.
 */
memory_span_exporter() : MemorySpanExporter

/**
 * Create a MemorySpanProcessor.
 *
 * Span processor that stores spans in memory and exports via configured exporter.
 * Useful for testing.
 *
 * @param SpanExporter $exporter The exporter to send spans to
 */
memory_span_processor(SpanExporter $exporter) : MemorySpanProcessor

/**
 * Create a MeterProvider.
 *
 * Creates a provider that uses a MetricProcessor for processing metrics.
 * For void/disabled metrics, pass void_processor().
 * For memory-based testing, pass memory_processor() with exporters.
 *
 * @param MetricProcessor $processor The processor for metrics
 * @param ClockInterface $clock The clock for timestamps
 * @param AggregationTemporality $temporality Aggregation temporality for metrics
 * @param ExemplarFilter $exemplarFilter Filter for exemplar sampling (default: TraceBasedExemplarFilter)
 * @param MetricLimits $limits Cardinality limits for metric instruments
 */
meter_provider(MetricProcessor $processor, ClockInterface $clock, AggregationTemporality $temporality, ExemplarFilter $exemplarFilter, MetricLimits $limits) : MeterProvider

/**
 * Create MetricLimits configuration.
 *
 * MetricLimits controls the maximum cardinality (unique attribute combinations)
 * per metric instrument, preventing memory exhaustion from high-cardinality attributes.
 *
 * When the cardinality limit is exceeded, new attribute combinations are aggregated
 * into an overflow data point with `otel.metric.overflow: true` attribute.
 *
 * Note: Unlike spans and logs, metrics are EXEMPT from attribute count and value
 * length limits per the OpenTelemetry specification. Only cardinality is limited.
 *
 * @param int $cardinalityLimit Maximum number of unique attribute combinations per instrument
 */
metric_limits(int $cardinalityLimit) : MetricLimits

/**
 * Create an OsDetector.
 *
 * Detects operating system information including os.type, os.name, os.version,
 * and os.description using PHP's php_uname() function.
 */
os_detector() : OsDetector

/**
 * Create a PassThroughLogProcessor.
 *
 * Exports each log record immediately when processed.
 * Useful for debugging where immediate visibility is more important than performance.
 *
 * @param LogExporter $exporter The exporter to send logs to
 */
pass_through_log_processor(LogExporter $exporter) : PassThroughLogProcessor

/**
 * Create a PassThroughMetricProcessor.
 *
 * Exports each metric immediately when processed.
 * Useful for debugging where immediate visibility is more important than performance.
 *
 * @param MetricExporter $exporter The exporter to send metrics to
 */
pass_through_metric_processor(MetricExporter $exporter) : PassThroughMetricProcessor

/**
 * Create a PassThroughSpanProcessor.
 *
 * Exports each span immediately when it ends.
 * Useful for debugging where immediate visibility is more important than performance.
 *
 * @param SpanExporter $exporter The exporter to send spans to
 */
pass_through_span_processor(SpanExporter $exporter) : PassThroughSpanProcessor

/**
 * Create a ProcessDetector.
 *
 * Detects process information including process.pid, process.executable.path,
 * process.runtime.name (PHP), process.runtime.version, process.command,
 * and process.owner (on POSIX systems).
 */
process_detector() : ProcessDetector

/**
 * Create a resource detector chain.
 *
 * When no detectors are provided, uses the default detector chain:
 * 1. OsDetector - Operating system information
 * 2. HostDetector - Host information
 * 3. ProcessDetector - Process information
 * 4. ComposerDetector - Service information from Composer
 * 5. EnvironmentDetector - Environment variable overrides (highest precedence)
 *
 * When detectors are provided, uses only those detectors.
 *
 * @param array<ResourceDetector> $detectors Optional custom detectors (empty = use defaults)
 */
resource_detector(array $detectors) : ChainDetector

/**
 * Create a SeverityFilteringLogProcessor.
 *
 * Filters log entries based on minimum severity level. Only entries at or above
 * the configured threshold are passed to the wrapped processor.
 *
 * @param LogProcessor $processor The processor to wrap
 * @param Severity $minimumSeverity Minimum severity level (default: INFO)
 */
severity_filtering_log_processor(LogProcessor $processor, Severity $minimumSeverity) : SeverityFilteringLogProcessor

/**
 * Create SpanLimits configuration.
 *
 * SpanLimits controls the maximum amount of data a span can collect,
 * preventing unbounded memory growth and ensuring reasonable span sizes.
 *
 * @param int $attributeCountLimit Maximum number of attributes per span
 * @param int $eventCountLimit Maximum number of events per span
 * @param int $linkCountLimit Maximum number of links per span
 * @param int $attributePerEventCountLimit Maximum number of attributes per event
 * @param int $attributePerLinkCountLimit Maximum number of attributes per link
 * @param null|int $attributeValueLengthLimit Maximum length for string attribute values (null = unlimited)
 */
span_limits(int $attributeCountLimit, int $eventCountLimit, int $linkCountLimit, int $attributePerEventCountLimit, int $attributePerLinkCountLimit, ?int $attributeValueLengthLimit) : SpanLimits

/**
 * Create a SuperglobalCarrier.
 *
 * Read-only carrier that extracts context from PHP superglobals
 * ($_SERVER, $_GET, $_POST, $_COOKIE).
 */
superglobal_carrier() : SuperglobalCarrier

/**
 * Create a new Telemetry instance with the given providers.
 *
 * If providers are not specified, void providers (no-op) are used.
 *
 * @param resource $resource The resource describing the entity producing telemetry
 * @param null|TracerProvider $tracerProvider The tracer provider (null for void/disabled)
 * @param null|MeterProvider $meterProvider The meter provider (null for void/disabled)
 * @param null|LoggerProvider $loggerProvider The logger provider (null for void/disabled)
 */
telemetry(Resource $resource, ?TracerProvider $tracerProvider, ?MeterProvider $meterProvider, ?LoggerProvider $loggerProvider) : Telemetry

/**
 * Create a TracerProvider.
 *
 * Creates a provider that uses a SpanProcessor for processing spans.
 * For void/disabled tracing, pass void_processor().
 * For memory-based testing, pass memory_processor() with exporters.
 *
 * @param SpanProcessor $processor The processor for spans
 * @param ClockInterface $clock The clock for timestamps
 * @param ContextStorage $contextStorage Storage for context propagation
 * @param Sampler $sampler Sampling strategy for spans
 * @param SpanLimits $limits Limits for span attributes, events, and links
 */
tracer_provider(SpanProcessor $processor, ClockInterface $clock, ContextStorage $contextStorage, Sampler $sampler, SpanLimits $limits) : TracerProvider

/**
 * Create a TraceBasedExemplarFilter.
 *
 * Records exemplars only when the span is sampled (has SAMPLED trace flag).
 * This is the default filter, balancing exemplar collection with performance.
 */
trace_based_exemplar_filter() : TraceBasedExemplarFilter

/**
 * Create a VoidLogExporter.
 *
 * No-op log exporter that discards all data.
 * Use this when telemetry export is disabled to minimize overhead.
 */
void_log_exporter() : VoidLogExporter

/**
 * Create a VoidLogProcessor.
 *
 * No-op log processor that discards all data.
 * Use this when logging is disabled to minimize overhead.
 */
void_log_processor() : VoidLogProcessor

/**
 * Create a VoidMetricExporter.
 *
 * No-op metric exporter that discards all data.
 * Use this when telemetry export is disabled to minimize overhead.
 */
void_metric_exporter() : VoidMetricExporter

/**
 * Create a VoidMetricProcessor.
 *
 * No-op metric processor that discards all data.
 * Use this when metrics collection is disabled to minimize overhead.
 */
void_metric_processor() : VoidMetricProcessor

/**
 * Create a VoidSpanExporter.
 *
 * No-op span exporter that discards all data.
 * Use this when telemetry export is disabled to minimize overhead.
 */
void_span_exporter() : VoidSpanExporter

/**
 * Create a VoidSpanProcessor.
 *
 * No-op span processor that discards all data.
 * Use this when tracing is disabled to minimize overhead.
 */
void_span_processor() : VoidSpanProcessor

/**
 * Create a W3CBaggage propagator.
 *
 * Implements W3C Baggage specification for propagating application-specific
 * key-value pairs using the baggage header.
 */
w3c_baggage() : W3CBaggage

/**
 * Create a W3CTraceContext propagator.
 *
 * Implements W3C Trace Context specification for propagating trace context
 * using traceparent and tracestate headers.
 */
w3c_trace_context() : W3CTraceContext