Stackdriver Trace Client - Class Span (1.8.7)

Reference documentation and code samples for the Stackdriver Trace Client class Span.

This plain PHP class represents a Span resource.

A span represents a single timed event within a Trace. Spans can be nested and form a trace tree. Often, a trace contains a root span that describes the end-to-end latency of an operation and, optionally, one or more subspans for its suboperations. Spans do not need to be contiguous. There may be gaps between spans in a trace.

Example:

use Google\Cloud\Trace\TraceClient;

$traceClient = new TraceClient();
$trace = $traceClient->trace();
$span = $trace->span([
    'name' => 'span name',
    'attributes' => ['foo' => 'bar'],
    'stackTrace' => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)
]);
$span->setStartTime();
$span->setEndTime();

Namespace

Google \ Cloud \ Trace

Methods

__construct

Instantiate a new Span instance.

Parameters
Name Description
traceId string

A unique identifier for a trace within a project; it is a 32-character hexadecimal encoding of a 16-byte array.
options array

Configuration options.
↳ spanId string

The ID of the span. If not provided, one will be generated automatically for you.
↳ name string

The name of the span.
↳ startTime DateTimeInterface|int|float|string

Start time of the span in nanoseconds. If provided as a string, it must be in "Zulu" format. If provided as an int or float, it is expected to be a Unix timestamp.
↳ endTime DateTimeInterface|int|float|string

End time of the span in nanoseconds. If provided as a string, it must be in "Zulu" format. If provided as an int or float, it is expected to be a Unix timestamp.
↳ parentSpanId string

ID of the parent span if any.
↳ attributes array

Associative array of $label => $value to attach to this span.
↳ stackTrace array

Stack trace captured at the start of the span.
↳ timeEvents TimeEvent[]

A set of time events. You can have up to 32 annotations and 128 message events per span.
↳ links Link[]

Links associated with the span. You can have up to 128 links per Span.
↳ status Status

An optional final status for this span.
↳ sameProcessAsParentSpan bool

A highly recommended but not required flag that identifies when a trace crosses a process boundary. True when the parent_span belongs to the same process as the current span.

setStartTime

Set the start time for this span.

Example:

// Set the start time to now
$span->setStartTime();

// Set the start time to a custom time
$span->setStartTime(new \DateTime('2017-11-29 11:51:23'));
Parameter
Name Description
when DateTimeInterface|int|float|string

[optional] The start time of this span. Defaults to* now. If provided as a string, it must be in "Zulu" format. If provided as an int or float, it is expected to be a Unix timestamp.

startTime

Returns a "Zulu" formatted string representing the start time for this span.

Example:

echo $span->startTime();
Returns
Type Description
string

setEndTime

Set the end time for this span.

Example:

// Set the end time to now
$span->setEndTime();

// Set the end time to a custom time
$span->setEndTime(new \DateTime('2017-11-29 11:51:23'));
Parameter
Name Description
when DateTimeInterface|int|float|string

[optional] The end time of this span. Defaults to* now. If provided as a string, it must be in "Zulu" format. If provided as an int or float, it is expected to be a Unix timestamp.

endTime

Returns a "Zulu" formatted string representing the end time for this span.

Example:

echo $span->endTime();
Returns
Type Description
string

setSpanId

Set the ID of this span

Example:

$span->setSpanId('1234abcd');
Parameter
Name Description
spanId string

setParentSpanId

Set the ID of this span's parent

Example:

$span->setParentSpanId('1234abcd');
Parameter
Name Description
spanId string

spanId

Retrieve the ID of this span.

Example:

echo $span->spanId();
Returns
Type Description
string

traceId

Retrieve the TraceID of this span

Example:

echo $span->traceId();
Returns
Type Description
string

parentSpanId

Retrieve the ID of this span's parent if it exists.

Example:

echo $span->parentSpanId();
Returns
Type Description
string

name

Retrieve the name of this span.

Example:

echo $span->name();
Returns
Type Description
string

info

Returns the info array for serialization.

Returns
Type Description
array

addTimeEvents

Add multiple TimeEvent to this span.

Example:

$annotation = new Annotation('some message');
$messageEvent = new MessageEvent('message id');
$span->addTimeEvents([
    $annotation,
    $messageEvent
]);
Parameter
Name Description
events array<TimeEvent>

addTimeEvent

Add a single TimeEvent to this span.

Example:

$annotation = new Annotation('some message');
$span->addTimeEvent($annotation);
Parameter
Name Description
event TimeEvent

addLinks

Add multiple Links to this span.

Example:

$link = new Link('abcd1234', 'abcd2345');
$span->addLinks([$link]);
Parameter
Name Description
links array<Link>

addLink

Add a single Link to this span.

Example:

$link = new Link('abcd1234', 'abcd2345');
$span->addLink($link);
Parameter
Name Description
link Link