\
Drupal
strata
Access
Anomaly
Archive
Branch
Budget
Capture
Classifier
EventSubscriber
Cas
Chunker
Code
Codec
Dictionary
Compaction
Crypto
Delta
Diff
Drill
Drush
Commands
Estimate
Event
Webhook
Explore
File
Flush
Form
Health
Tripwire
Hook
Journal
Metrics
Plugin
QueueWorker
views
field
filter
Restore
Plugin
Strata
Restore
Segment
Site
Storage
Plugin
Strata
Storage
Telemetry
Tier
Timeline
Tree
Verify

\Drupal\strata\Telemetry Tracer

Opens and closes spans, and holds them until something exports them.

A tracer that posted each span as it closed would put an outbound HTTP call inside a flush, which is the thing telemetry is supposed to be measuring. So spans accumulate in memory and are drained by whoever is exporting; on a request that is the end of the request, and on cron it is the end of the run.

The buffer is capped. A long-running command that traced a million subjects would otherwise spend more memory on the measurement than on the work. Past the cap, spans are counted and dropped, and the count is exported as its own metric so the gap is visible rather than silent.

Summary

Methods
Properties
Constants
__construct
isEnabled
measure
start
close
spans
dropped
drain
No public properties found
MAX_SPANS
No protected methods found
No protected properties found
No protected constants found
No private methods found
spans
open
dropped
traceId
enabled
No private constants found

Constant

MAX_SPANS

MAX_SPANS = 2048

Spans held before further ones are counted and dropped.

Properties

$spans

$spans : list<\Drupal\strata\Telemetry\Span>

Closed spans waiting to be exported.

Type

array<int, Span> —

$open

$open : list

Ids of the spans currently open, innermost last.

Type

array<int, string> —

$dropped

$dropped : int

How many spans were dropped because the buffer was full.

Type

int

$traceId

$traceId : ?string

The trace every span in this process belongs to.

Type

string|null

$enabled

$enabled : bool

Type

bool

Methods

__construct()

__construct(bool  $enabled = true) : mixed

Constructs a tracer.

Parameters

bool $enabled

FALSE to make every method a no-op, which is the default a site without a collector runs in.

Returns

mixed —

isEnabled()

isEnabled() : bool

Whether spans are being recorded.

Returns

bool —

TRUE when tracing is on.

measure()

measure(string  $name, callable  $work, array  $attributes = []) : mixed

Times a callable and records a span around it.

An exception is recorded on the span and then rethrown. Telemetry never changes what the program does; a tracer that swallowed the failure it just measured would be worse than no tracer at all.

Parameters

string $name

What is being timed.
callable $work

The work.
array $attributes

What the operation is about.

Throws

\Throwable

Whatever the callable threw.

Returns

mixed —

Whatever the callable returned.

start()

start(string  $name, array  $attributes = []) : \Drupal\strata\Telemetry\Span

Opens a span.

Parameters

string $name

What is being timed.
array $attributes

What the operation is about.

Returns

\Drupal\strata\Telemetry\Span —

The open span, to be handed back to close().

close()

close(\Drupal\strata\Telemetry\Span  $span, int  $durationNanos, array  $attributes = [], int  $status = \Drupal\strata\Telemetry\Span::OK, string  $message = '') : void

Closes a span and buffers it.

Parameters

\Drupal\strata\Telemetry\Span $span

The span start() returned.
int $durationNanos

How long it took, from hrtime().
array $attributes

Attributes to add now the result is known.
int $status

Either Span::OK or Span::ERROR.
string $message

Why it failed, when it did.

Returns

void —

spans()

spans() : list<\Drupal\strata\Telemetry\Span>

The buffered spans.

Returns

list<\Drupal\strata\Telemetry\Span> —

The spans, in the order they closed.

dropped()

dropped() : int

How many spans were dropped because the buffer was full.

Returns

int —

The count.

drain()

drain() : list<\Drupal\strata\Telemetry\Span>

Takes the buffered spans and empties the buffer.

Returns

list<\Drupal\strata\Telemetry\Span> —

The spans.