Stackdriver Trace Client - Class Span (1.4.11)

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();

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<Google\Cloud\Trace\TimeEvent>`

addTimeEvent

Add a single TimeEvent to this span.

Example:

$annotation = new Annotation('some message');
$span->addTimeEvent($annotation);

Parameter
Name	Description
`event`	`Google\Cloud\Trace\TimeEvent`

addLinks

Add multiple Links to this span.

Example:

$link = new Link('abcd1234', 'abcd2345');
$span->addLinks([$link]);

Parameter
Name	Description
`links`	`array<Google\Cloud\Trace\Link>`

addLink

Add a single Link to this span.

Example:

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

Parameter
Name	Description
`link`	`Google\Cloud\Trace\Link`