Public APIedit

The public API of the Elastic APM PHP agent lets you customize and manually create spans and transactions.

ElasticApmedit

This is the entry point of the public API. It allows to start transactions, gives you access to the current transaction, etc.

To use the API, you invoke the static methods on the class \Elastic\Apm\ElasticApm.

ElasticApm::beginCurrentTransactionedit

Begins a new transaction and sets it as the current transaction. Use this method to create a custom transaction. Note that when automatic instrumentation is used the agent begins a new transaction automatically whenever your application receives an incoming HTTP request so you only need to use this method to create custom transactions.

You must call TransactionInterface::end when the transaction has ended.

The best practice is to use a try-finally block. For example:

use Elastic\Apm\ElasticApm;

$transaction = ElasticApm::beginCurrentTransaction(
    'transaction_name',
    'transaction_type'
);
try {
    // do your thing ...
} finally {
    $transaction->end();
}

See TransactionInterface on how to customize a transaction.

ElasticApm::captureCurrentTransactionedit

This is a convenience API that ensures TransactionInterface::end is called when the transaction has ended. This API:

  • Begins a new transaction
  • Sets the new transaction as the current transaction
  • Executes the provided callable as the new transaction
  • Ends the new transaction
  • Returns the value returned by the provided callable

For example:

use Elastic\Apm\ElasticApm;

ElasticApm::captureCurrentTransaction(
    'transaction_name',
    'transaction_type'
    function (TransactionInterface $transaction) {
        // do your thing...
    }
);

See TransactionInterface on how to customize a transaction.

ElasticApm::getCurrentTransactionedit

Returns the current transaction.

use Elastic\Apm\ElasticApm;

$transaction = ElasticApm::getCurrentTransaction();

See TransactionInterface on how to customize a transaction.

TransactionInterfaceedit

A transaction describes an event captured by an Elastic APM agent monitoring a service. Transactions help combine multiple Spans into logical groups, and they are the first Span of a service. More information on Transactions and Spans is available in the APM data model documentation.

See ElasticApm::getCurrentTransaction on how to get a reference to the current transaction.

TransactionInterface::getCurrentSpanedit

Returns the current span for this transaction.

Example:

$span = $transaction->getCurrentSpan();

TransactionInterface::beginCurrentSpanedit

Begins a new span with the current span as the new span’s parent and sets the new span as the current span for this transaction. If this transaction’s doesn’t have the current span then the transaction itself is set as the new span’s parent.

You must call SpanInterface::end when the span has ended.

The best practice is to use a try-finally block. For example:

$span = $transaction->beginCurrentSpan(
    'span_name',
    'span_type',
    'span_sub-type', // optional
    'span_action' // optional
);
try {
    // do your thing ...
} finally {
    $span->end();
}

TransactionInterface::captureCurrentSpanedit

This is a convenience API that ensures SpanInterface::end is called when the span has ended. This API

  • Begins a new span with this transaction’s current span as the new span’s parent and sets the new span as the current span for this transaction. If this transaction’s doesn’t have a current span then the transaction itself is set as the new span’s parent.
  • Executes the provided callable as the new span
  • Ends the new transaction
  • Returns the value returned by the provided callable

For example:

$parentSpan->captureCurrentSpan(
    'span_name',
    'span_type'
    function (SpanInterface $childSpan) {
        // do your thing...
    },
    'span_sub-type', // optional
    'span_action' // optional
);

TransactionInterface::beginChildSpanedit

Begins a new span with this transaction as the new span’s parent.

You must call SpanInterface::end when the span has ended.

The best practice is to use try-finally block. For example:

$span = $transaction->beginChildSpan(
    'span_name',
    'span_type',
    'span_sub-type', // optional
    'span_action' // optional
);
try {
    // do your thing ...
} finally {
    $span->end();
}

TransactionInterface::captureChildSpanedit

This is a convenience API that ensures SpanInterface::end is called when the span has ended. This API

  • Begins a new span with this transaction as the new span’s parent
  • Executes the provided callable as the new span and
  • Ends the new span
  • Returns the value returned by the provided callable

For example:

$transaction->captureChildSpan(
    'span_name',
    'span_type'
    function (SpanInterface $span) {
        // do your thing...
    },
    'span_sub-type', // optional
    'span_action' // optional
);

TransactionInterface::setNameedit

Sets the name of the transaction. Transaction name is generic designation of a transaction in the scope of a single service (e.g., GET /users/:id).

Example:

$transaction->setName('GET /users/:id');

TransactionInterface::getNameedit

Gets the name of the transaction.

Example:

$transactionName = $transaction->getName();

TransactionInterface::setTypeedit

Sets the type of the transaction. Transaction type is a keyword of specific relevance in the service’s domain. For example request, backgroundjob, etc.

Example:

$transaction->setType('my custom transaction type');

TransactionInterface::getTypeedit

Gets the type of the transaction.

Example:

$transactionType = $transaction->getType();

TransactionInterface::setLabeledit

Sets a label by a key. Labels are a flat mapping of user-defined string keys and string, number, or boolean values.

The labels are indexed in Elasticsearch so that they are searchable and aggregatable. Take special care when using user provided data, like URL parameters, as a label key because it can lead to Elasticsearch mapping explosion.

Example:

$transaction->setLabel('my label with string value', 'some text');
$transaction->setLabel('my label with int value', 123);
$transaction->setLabel('my label with float value', 4.56);

TransactionInterface::getIdedit

Gets the ID of the transaction. Transaction ID is a hex encoded 64 random bits (== 8 bytes == 16 hex digits) ID.

If this transaction represents a noop, this method returns an unspecified dummy ID.

Example:

$transactionId = $transaction->getId();

TransactionInterface::getTraceIdedit

Gets the trace ID of the transaction. Trace ID is a hex encoded 128 random bits (== 16 bytes == 32 hex digits) ID of the correlated trace.

The trace ID is consistent across all transactions and spans which belong to the same logical trace, even for transactions and spans which happened in another service (given this service is also monitored by Elastic APM).

If this transaction represents a noop, this method returns an unspecified dummy ID.

Example:

$traceId = $transaction->getTraceId();

TransactionInterface::getParentIdedit

Gets ID of the parent transaction or span.

See TransactionInterface::getId and SpanInterface::getId.

The root transaction of a trace does not have a parent, so null is returned.

If this transaction represents a noop, this method returns an unspecified dummy ID.

Example:

$parentId = $transaction->getParentId();

TransactionInterface::endedit

Ends the transaction and queues it to be reported to the APM Server.

It is illegal to call any mutating methods (i.e., not getXyz) on a transaction instance which has already ended.

Example:

$transaction->end();

SpanInterfaceedit

A span contains information about a specific code path, executed as part of a transaction.

If for example a database query happens within a recorded transaction, a span representing this database query may be created. In such a case the name of the span will contain information about the query itself, and the type will hold information about the database type.

See TransactionInterface::getCurrentSpan on how to get the current span.

SpanInterface::setNameedit

Sets the name of the span. Span name is generic designation of a span in the scope of a transaction.

Example:

$span->setName('SELECT FROM customer');

SpanInterface::getNameedit

Gets the name of the span.

Example:

$spanName = $span->getName();

SpanInterface::setTypeedit

Sets the type of the span. Span type is a keyword of specific relevance in the service’s domain. For example db, external, etc.

Example:

$span->setType('my custom span type');

SpanInterface::getTypeedit

Gets the type of the span.

Example:

$spanType = $span->getType();

SpanInterface::setSubtypeedit

Sets the sub-type of the span. Span sub-type is a further sub-division of the type. For example, mysql, postgresql, or elasticsearch for the type db, http for the type external, etc.

Span sub-type is optional and can be set to null. Span sub-type default value is null.

Example:

$span->setSubtype('my custom span sub-type');

SpanInterface::getSubtypeedit

Gets the sub-type of the span.

Example:

$spanSubtype = $span->getSubtype();

SpanInterface::setActionedit

Sets the action of the span. Span action is the specific kind of event within the sub-type represented by the span. For example query for type/sub-type db/mysql, connect for type/sub-type db/cassandra, etc.

Span action is optional and can be set to null. Span action default value is null.

Example:

$span->setAction('my custom span action');

SpanInterface::getActionedit

Gets the action of the span.

Example:

$spanAction = $span->getAction();

SpanInterface::setLabeledit

Sets a label by a key. Labels are a flat mapping of user-defined string keys and string, number, or boolean values.

The labels are indexed in Elasticsearch so that they are searchable and aggregatable. Take special care when using user provided data, like URL parameters, as a label key because it can lead to Elasticsearch mapping explosion.

Example:

$span->setLabel('my label with string value', 'some text');
$span->setLabel('my label with int value', 123);
$span->setLabel('my label with float value', 4.56);

SpanInterface::getIdedit

Gets the ID of the span. Span ID is a hex encoded 64 random bits (== 8 bytes == 16 hex digits) ID.

If this span represents a noop, this method returns an unspecified dummy ID.

Example:

$spanId = $span->getId();

SpanInterface::getTraceIdedit

Gets the trace ID of the span. Trace ID is a hex encoded 128 random bits (== 16 bytes == 32 hex digits) ID of the correlated trace.

The trace ID is consistent across all transactions and spans which belong to the same logical trace, even for transactions and spans which happened in another service (given this service is also monitored by Elastic APM).

If this span represents a noop, this method returns an unspecified dummy ID.

Example:

$traceId = $span->getTraceId();

SpanInterface::getTransactionIdedit

Gets ID of the correlated transaction. See TransactionInterface::getId.

If this span represents a noop, this method returns an unspecified dummy ID.

Example:

$transactionId = $span->getTransactionId();

SpanInterface::getParentIdedit

Gets ID of the parent transaction or span. If this span is the root span of the correlated transaction then its parent is the correlated transaction, otherwise, its parent is the parent span. See TransactionInterface::getId and SpanInterface::getId.

If this span represents a noop, this method returns an unspecified dummy ID.

Example:

$parentId = $span->getParentId();

SpanInterface::beginChildSpanedit

Begins a new span with this span as the new span’s parent.

You must call SpanInterface::end when the span has ended.

The best practice is to use a try-finally block. For example:

$childSpan = $parentSpan->beginChildSpan(
    'span_name',
    'span_type',
    'span_sub-type', // optional
    'span_action' // optional
);
try {
    // do your thing ...
} finally {
    $childSpan->end();
}

SpanInterface::captureChildSpanedit

This is a convenience API that ensures SpanInterface::end is called when the span has ended. This API

  • Begins a new span with this span as the new span’s parent
  • Executes the provided callable as the new span
  • Ends the new span
  • Returns the value returned by the provided callable

For example:

$parentSpan->captureChildSpan(
    'span_name',
    'span_type'
    function (SpanInterface $childSpan) {
        // do your thing...
    },
    'span_sub-type', // optional
    'span_action' // optional
);

SpanInterface::endedit

Ends the span and queues it to be reported to the APM Server.

It is illegal to call any mutating methods (i.e., not getXyz) on a span instance which has already ended.

Example:

$span->end();