MediaWiki master
Wikimedia\Telemetry\SpanInterface Interface Reference

Represents an OpenTelemetry span, i.e. More...

Inherited by Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

Public Member Functions

 activate ()
 Make this span the active span.
 
 deactivate ()
 Deactivate this span.
 
 end (?int $epochNanos=null)
 End this span, optionally specifying an override for its end time.
 
 getContext ()
 Get the context holding data for this span.
 
 setAttributes (array $attributes)
 Set attributes (arbitrary metadata) for this span.
 
 setSpanKind (int $spanKind)
 Set the kind of this span, which describes how it relates to its parent and children within the overarching trace.
 
 setSpanStatus (int $spanStatus)
 Set the status of this span.
 
 start (?int $epochNanos=null)
 Start this span, optionally specifying an override for its start time.
 

Public Attributes

const SPAN_KIND_CLIENT = 3
 Indicates that the span describes a request to some remote service.
 
const SPAN_KIND_CONSUMER = 5
 Indicates that the span describes a child of an asynchronous SpanInterface::SPAN_KIND_PRODUCER request.
 
const SPAN_KIND_INTERNAL = 1
 Default value.
 
const SPAN_KIND_PRODUCER = 4
 Indicates that the span describes the initiators of an asynchronous request.
 
const SPAN_KIND_SERVER = 2
 Indicates that the span covers server-side handling of a synchronous RPC or other incoming request from a remote client.
 
const SPAN_STATUS_ERROR = 2
 Indicates that the operation represented by this span failed.
 
const SPAN_STATUS_OK = 1
 Indicates that the operation represented by this span was successful.
 
const SPAN_STATUS_UNSET = 0
 Default value.
 

Detailed Description

Represents an OpenTelemetry span, i.e.

a single operation within a trace.

A Span is literally a span of time, with an operation name, and an optional set of key/value attributes. It may be attached to a parent span, or it may be the root of a trace.

Since
1.43
See also
https://opentelemetry.io/docs/specs/otel/trace/api/#span

Definition at line 14 of file SpanInterface.php.

Member Function Documentation

◆ activate()

Wikimedia\Telemetry\SpanInterface::activate ( )

Make this span the active span.

This will cause any spans started without specifying an explicit parent to automatically become children of this span, for as long as it remains active.

Activated spans form a stack; the most recently activated span is the active span.

Long-running synchronous operations are good candidates for activation, especially if they will have other children spans created by code that is not explicitly aware of the parent span. For example, a MediaWiki EntryPoint might activate a span at the start of the request. Or a large unit of work (like wikitext parsing) might activate their own span, so that all database queries and other operations that occur during that work are automatically made descendants.

Returns
SpanInterface fluent interface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ deactivate()

Wikimedia\Telemetry\SpanInterface::deactivate ( )

Deactivate this span.

Spans will also automatically be deactivated when they go out of scope.

Returns
SpanInterface fluent interface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ end()

Wikimedia\Telemetry\SpanInterface::end ( ?int $epochNanos = null)

End this span, optionally specifying an override for its end time.

Spans will also automatically be ended shortly after they go out of scope, but calling end() yourself is a good way to ensure the end timestamp is accurate.

Parameters
int | null$epochNanosThe end time to use, or null to use the current time.
Returns
void

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ getContext()

Wikimedia\Telemetry\SpanInterface::getContext ( )

Get the context holding data for this span.

Returns
SpanContext

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ setAttributes()

Wikimedia\Telemetry\SpanInterface::setAttributes ( array $attributes)

Set attributes (arbitrary metadata) for this span.

Any existing attributes with the same keys will be overwritten. Attributes with a null value will be ignored during export.

These attributes will be attached to the span and will be searchable in the trace viewer.

When deciding on the set of attributes to register as well as their naming, consider following Semantic Conventions where applicable.

Parameters
array$attributeskey-value mapping of attribute names to values
Returns
SpanInterface fluent interface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ setSpanKind()

Wikimedia\Telemetry\SpanInterface::setSpanKind ( int $spanKind)

Set the kind of this span, which describes how it relates to its parent and children within the overarching trace.

Parameters
int$spanKindOne of the SpanInterface::SPAN_KIND_** constants
See also
https://opentelemetry.io/docs/specs/otel/trace/api/#spankind
Returns
SpanInterface fluent interface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ setSpanStatus()

Wikimedia\Telemetry\SpanInterface::setSpanStatus ( int $spanStatus)

Set the status of this span.

By default this is SPAN_STATUS_UNSET.

Parameters
int$spanStatusOne of the SpanInterface::SPAN_STATUS_** constants
Returns
SpanInterface fluent interface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

◆ start()

Wikimedia\Telemetry\SpanInterface::start ( ?int $epochNanos = null)

Start this span, optionally specifying an override for its start time.

Parameters
int | null$epochNanosThe start time to use, or null to use the current time.
Returns
SpanInterface

Implemented in Wikimedia\Telemetry\NoopSpan, and Wikimedia\Telemetry\Span.

Member Data Documentation

◆ SPAN_KIND_CLIENT

const Wikimedia\Telemetry\SpanInterface::SPAN_KIND_CLIENT = 3

Indicates that the span describes a request to some remote service.

Definition at line 30 of file SpanInterface.php.

◆ SPAN_KIND_CONSUMER

const Wikimedia\Telemetry\SpanInterface::SPAN_KIND_CONSUMER = 5

Indicates that the span describes a child of an asynchronous SpanInterface::SPAN_KIND_PRODUCER request.

Definition at line 41 of file SpanInterface.php.

◆ SPAN_KIND_INTERNAL

const Wikimedia\Telemetry\SpanInterface::SPAN_KIND_INTERNAL = 1

Default value.

Indicates that the span represents an internal operation within an application, as opposed to an operations with remote parents or children. For example: wikitext parsing.

Definition at line 19 of file SpanInterface.php.

◆ SPAN_KIND_PRODUCER

const Wikimedia\Telemetry\SpanInterface::SPAN_KIND_PRODUCER = 4

Indicates that the span describes the initiators of an asynchronous request.

Definition at line 35 of file SpanInterface.php.

◆ SPAN_KIND_SERVER

const Wikimedia\Telemetry\SpanInterface::SPAN_KIND_SERVER = 2

Indicates that the span covers server-side handling of a synchronous RPC or other incoming request from a remote client.

Definition at line 25 of file SpanInterface.php.

◆ SPAN_STATUS_ERROR

const Wikimedia\Telemetry\SpanInterface::SPAN_STATUS_ERROR = 2

Indicates that the operation represented by this span failed.

Will be searchable in the trace viewer, for example with the error=true tag in Jaeger.

Definition at line 68 of file SpanInterface.php.

◆ SPAN_STATUS_OK

const Wikimedia\Telemetry\SpanInterface::SPAN_STATUS_OK = 1

Indicates that the operation represented by this span was successful.

Definition at line 62 of file SpanInterface.php.

◆ SPAN_STATUS_UNSET

const Wikimedia\Telemetry\SpanInterface::SPAN_STATUS_UNSET = 0

Default value.

Indicates that the span status is not set. This is to ensure that successes are recorded explicitly.

Definition at line 57 of file SpanInterface.php.


The documentation for this interface was generated from the following file: