941 lines
32 KiB
PHP
941 lines
32 KiB
PHP
<?php
|
|
|
|
namespace Elastic\Apm;
|
|
|
|
/**
|
|
* Class ElasticApm is a facade (as in Facade design pattern) to the rest of Elastic APM public API.
|
|
*/
|
|
final class ElasticApm
|
|
{
|
|
public const VERSION = '1.3.1';
|
|
|
|
private function __construct() {}
|
|
|
|
/**
|
|
* Begins a new transaction and sets it as the current transaction.
|
|
*
|
|
* @param string $name New transaction's name
|
|
* @param string $type New transaction's type
|
|
* @param float|null $timestamp Start time of the new transaction
|
|
* @param string|null $serializedDistTracingData - DEPRECATED since version 1.3 -
|
|
* use newTransaction()->distributedTracingHeaderExtractor() instead
|
|
*
|
|
* @return TransactionInterface New transaction
|
|
*
|
|
* @see TransactionInterface::setName() For the description.
|
|
* @see TransactionInterface::setType() For the description.
|
|
* @see TransactionInterface::getTimestamp() For the description.
|
|
*/
|
|
public static function beginCurrentTransaction(
|
|
string $name,
|
|
string $type,
|
|
?float $timestamp = null,
|
|
?string $serializedDistTracingData = null
|
|
): TransactionInterface {}
|
|
|
|
/**
|
|
* Begins a new transaction, sets as the current transaction,
|
|
* runs the provided callback as the new transaction and automatically ends the new transaction.
|
|
*
|
|
* @param string $name New transaction's name
|
|
* @param string $type New transaction's type
|
|
* @param \Closure $callback Callback to execute as the new transaction
|
|
* @param float|null $timestamp Start time of the new transaction
|
|
* @param string|null $serializedDistTracingData - DEPRECATED since version 1.3 -
|
|
* use newTransaction()->distributedTracingHeaderExtractor() instead
|
|
*
|
|
* @return mixed The return value of $callback
|
|
*
|
|
* @see TransactionInterface::setName() For the description.
|
|
* @see TransactionInterface::setType() For the description.
|
|
* @see TransactionInterface::getTimestamp() For the description.
|
|
*/
|
|
public static function captureCurrentTransaction(
|
|
string $name,
|
|
string $type,
|
|
\Closure $callback,
|
|
?float $timestamp = null,
|
|
?string $serializedDistTracingData = null
|
|
) {}
|
|
|
|
/**
|
|
* Returns the current transaction.
|
|
*
|
|
* @return TransactionInterface The current transaction
|
|
*/
|
|
public static function getCurrentTransaction(): TransactionInterface {}
|
|
|
|
/**
|
|
* If there is the current span then it returns the current span.
|
|
* Otherwise if there is the current transaction then it returns the current transaction.
|
|
* Otherwise it returns the noop execution segment.
|
|
*
|
|
* @return ExecutionSegmentInterface The current execution segment
|
|
*/
|
|
public static function getCurrentExecutionSegment(): ExecutionSegmentInterface {}
|
|
|
|
/**
|
|
* Begins a new transaction.
|
|
*
|
|
* @param string $name New transaction's name
|
|
* @param string $type New transaction's type
|
|
* @param float|null $timestamp Start time of the new transaction
|
|
* @param string|null $serializedDistTracingData - DEPRECATED since version 1.3 -
|
|
* use newTransaction()->distributedTracingHeaderExtractor() instead
|
|
*
|
|
* @return TransactionInterface New transaction
|
|
*
|
|
* @see TransactionInterface::setName() For the description.
|
|
* @see TransactionInterface::setType() For the description.
|
|
* @see TransactionInterface::getTimestamp() For the description.
|
|
*/
|
|
public static function beginTransaction(
|
|
string $name,
|
|
string $type,
|
|
?float $timestamp = null,
|
|
?string $serializedDistTracingData = null
|
|
): TransactionInterface {}
|
|
|
|
/**
|
|
* Begins a new transaction,
|
|
* runs the provided callback as the new transaction and automatically ends the new transaction.
|
|
*
|
|
* @param string $name New transaction's name
|
|
* @param string $type New transaction's type
|
|
* @param \Closure $callback Callback to execute as the new transaction
|
|
* @param float|null $timestamp Start time of the new transaction
|
|
* @param string|null $serializedDistTracingData - DEPRECATED since version 1.3 -
|
|
* use newTransaction()->distributedTracingHeaderExtractor() instead
|
|
*
|
|
* @return mixed The return value of $callback
|
|
*
|
|
* @see TransactionInterface::setName() For the description.
|
|
* @see TransactionInterface::setType() For the description.
|
|
* @see TransactionInterface::getTimestamp() For the description.
|
|
*/
|
|
public static function captureTransaction(
|
|
string $name,
|
|
string $type,
|
|
\Closure $callback,
|
|
?float $timestamp = null,
|
|
?string $serializedDistTracingData = null
|
|
) {}
|
|
|
|
/**
|
|
* Advanced API to begin a new transaction
|
|
*
|
|
* @param string $name New transaction's name
|
|
* @param string $type New transaction's type
|
|
*
|
|
* @return TransactionBuilderInterface New transaction builder
|
|
*
|
|
* @see TransactionInterface::setName() For the description.
|
|
* @see TransactionInterface::setType() For the description.
|
|
*/
|
|
public static function newTransaction(string $name, string $type): TransactionBuilderInterface {}
|
|
|
|
/**
|
|
* Creates an error based on the given Throwable instance
|
|
* with the current execution segment (if there is one) as the parent.
|
|
*
|
|
* @param \Throwable $throwable
|
|
*
|
|
* @return string|null ID of the reported error event or null if no event was reported
|
|
* (for example, because recording is disabled)
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json
|
|
*/
|
|
public static function createErrorFromThrowable(\Throwable $throwable): ?string {}
|
|
|
|
/**
|
|
* Creates an error based on the given data
|
|
* with the current execution segment (if there is one) as the parent.
|
|
*
|
|
* @param CustomErrorData $customErrorData
|
|
*
|
|
* @return string|null ID of the reported error event or null if no event was reported
|
|
* (for example, because recording is disabled)
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json
|
|
*/
|
|
public static function createCustomError(CustomErrorData $customErrorData): ?string {}
|
|
|
|
/**
|
|
* Pauses recording
|
|
*/
|
|
public static function pauseRecording(): void {}
|
|
|
|
/**
|
|
* Resumes recording
|
|
*/
|
|
public static function resumeRecording(): void {}
|
|
|
|
/**
|
|
* @deprecated Deprecated since version 1.3 - use injectDistributedTracingHeaders() instead
|
|
* @see injectDistributedTracingHeaders() Use it instead of this method
|
|
*
|
|
* Returns distributed tracing data for the current span/transaction
|
|
*/
|
|
public static function getSerializedCurrentDistributedTracingData(): string {}
|
|
}
|
|
|
|
/**
|
|
* Class to gather optional parameters to start a new transaction
|
|
*
|
|
* @see ElasticApm::beginCurrentTransaction()
|
|
* @see ElasticApm::captureCurrentTransaction()
|
|
*/
|
|
interface TransactionBuilderInterface
|
|
{
|
|
/**
|
|
* New transaction will be set as the current one
|
|
*
|
|
* @return TransactionBuilderInterface
|
|
*/
|
|
public function asCurrent(): self;
|
|
|
|
/**
|
|
* Set start time of the new transaction
|
|
*
|
|
* @param float $timestamp
|
|
*
|
|
* @return TransactionBuilderInterface
|
|
*/
|
|
public function timestamp(float $timestamp): self;
|
|
|
|
/**
|
|
* @param \Closure $headerExtractor
|
|
*
|
|
* @return TransactionBuilderInterface
|
|
*/
|
|
public function distributedTracingHeaderExtractor(\Closure $headerExtractor): self;
|
|
|
|
/**
|
|
* Begins a new transaction.
|
|
*
|
|
* @return TransactionInterface New transaction
|
|
*/
|
|
public function begin(): TransactionInterface;
|
|
|
|
/**
|
|
* Begins a new transaction,
|
|
* runs the provided callback as the new transaction and automatically ends the new transaction.
|
|
*
|
|
* @param \Closure $callback
|
|
*
|
|
* @return mixed The return value of $callback
|
|
*/
|
|
public function capture(\Closure $callback);
|
|
}
|
|
|
|
interface TransactionInterface extends ExecutionSegmentInterface
|
|
{
|
|
/**
|
|
* Transactions that are 'sampled' will include all available information
|
|
* Transactions that are not sampled will not have 'spans' or 'context'.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L72
|
|
*/
|
|
public function isSampled(): bool;
|
|
|
|
/**
|
|
* Hex encoded 64 random bits ID of the parent transaction or span.
|
|
* Only a root transaction of a trace does not have a parent ID, otherwise it needs to be set.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L19
|
|
*/
|
|
public function getParentId(): ?string;
|
|
|
|
/**
|
|
* Begins a new span with the current execution segment
|
|
* as the new span's parent and sets as the new span as the current span for this transaction.
|
|
* The current execution segment is the current span if there is one or this transaction itself otherwise.
|
|
*
|
|
* @param string $name New span's name.
|
|
* @param string $type New span's type
|
|
* @param string|null $subtype New span's subtype
|
|
* @param string|null $action New span's action
|
|
* @param float|null $timestamp Start time of the new span
|
|
*
|
|
* @see SpanInterface::setName() For the description.
|
|
* @see SpanInterface::setType() For the description.
|
|
* @see SpanInterface::setSubtype() For the description.
|
|
* @see SpanInterface::setAction() For the description.
|
|
* @see SpanInterface::getTimestamp() For the description.
|
|
*
|
|
* @return SpanInterface New span
|
|
*/
|
|
public function beginCurrentSpan(
|
|
string $name,
|
|
string $type,
|
|
?string $subtype = null,
|
|
?string $action = null,
|
|
?float $timestamp = null
|
|
): SpanInterface;
|
|
|
|
/**
|
|
* Begins a new span with the current execution segment as the new span's parent and
|
|
* sets the new span as the current span for this transaction.
|
|
* The current execution segment is the current span if there is one or this transaction itself otherwise.
|
|
*
|
|
* @param string $name New span's name
|
|
* @param string $type New span's type
|
|
* @param \Closure $callback Callback to execute as the new span
|
|
* @param string|null $subtype New span's subtype
|
|
* @param string|null $action New span's action
|
|
* @param float|null $timestamp Start time of the new span
|
|
*
|
|
* @see SpanInterface::setName() For the description.
|
|
* @see SpanInterface::setType() For the description.
|
|
* @see SpanInterface::setSubtype() For the description.
|
|
* @see SpanInterface::setAction() For the description.
|
|
* @see SpanInterface::getTimestamp() For the description.
|
|
*
|
|
* @return mixed The return value of $callback
|
|
*/
|
|
public function captureCurrentSpan(
|
|
string $name,
|
|
string $type,
|
|
\Closure $callback,
|
|
?string $subtype = null,
|
|
?string $action = null,
|
|
?float $timestamp = null
|
|
);
|
|
|
|
/**
|
|
* Returns the current span.
|
|
*
|
|
* @return SpanInterface The current span
|
|
*/
|
|
public function getCurrentSpan(): SpanInterface;
|
|
|
|
/**
|
|
* Returns context (context allows to set labels, etc.)
|
|
*/
|
|
public function context(): TransactionContextInterface;
|
|
|
|
/**
|
|
* The result of the transaction.
|
|
* For HTTP-related transactions, this should be the status code formatted like 'HTTP 2xx'.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L52
|
|
*
|
|
* @param string|null $result
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setResult(?string $result): void;
|
|
|
|
/**
|
|
* @see setResult() For the description
|
|
*/
|
|
public function getResult(): ?string;
|
|
|
|
/**
|
|
* If the transaction does not have a parent ID yet,
|
|
* calling this method generates a new ID,
|
|
* sets it as the parent ID of this transaction, and returns it as a string.
|
|
*
|
|
* @return string
|
|
*/
|
|
public function ensureParentId(): string;
|
|
}
|
|
|
|
interface SpanInterface extends ExecutionSegmentInterface
|
|
{
|
|
/**
|
|
* Hex encoded 64 random bits ID of the correlated transaction.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L14
|
|
*/
|
|
public function getTransactionId(): string;
|
|
|
|
/**
|
|
* Hex encoded 64 random bits ID of the parent.
|
|
* If this span is the root span of the correlated transaction the its parent is the correlated transaction
|
|
* otherwise its parent is the parent span.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L24
|
|
*/
|
|
public function getParentId(): string;
|
|
|
|
/**
|
|
* The specific kind of event within the sub-type represented by the span
|
|
* e.g., 'query' for type/sub-type 'db'/'mysql', 'connect' for type/sub-type 'db'/'cassandra'
|
|
*
|
|
* The length of this string is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L38
|
|
*
|
|
* @param string|null $action
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setAction(?string $action): void;
|
|
|
|
/**
|
|
* A further sub-division of the type
|
|
* e.g., 'mysql', 'postgresql' or 'elasticsearch' for type 'db', 'http' for type 'external', etc.
|
|
*
|
|
* The length of this string is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L33
|
|
*
|
|
* @param string|null $subtype
|
|
*/
|
|
public function setSubtype(?string $subtype): void;
|
|
|
|
/**
|
|
* Returns context (context allows to set labels, etc.)
|
|
*/
|
|
public function context(): SpanContextInterface;
|
|
|
|
/**
|
|
* Extended version of ExecutionSegmentInterface::end()
|
|
*
|
|
* @param int $numberOfStackFramesToSkip Number of stack frames to skip when capturing stack trace.
|
|
* @param float|null $duration In milliseconds with 3 decimal points.
|
|
*
|
|
* @see ExecutionSegmentInterface::end() For the description
|
|
*/
|
|
public function endSpanEx(int $numberOfStackFramesToSkip, ?float $duration = null): void;
|
|
}
|
|
|
|
interface SpanContextInterface extends ExecutionSegmentContextInterface
|
|
{
|
|
/**
|
|
* Returns an object containing contextual data for database spans
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L47
|
|
*/
|
|
public function db(): SpanContextDbInterface;
|
|
|
|
/**
|
|
* Returns an object containing contextual data of the related http request
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L69
|
|
*/
|
|
public function http(): SpanContextHttpInterface;
|
|
|
|
/**
|
|
* Returns an object containing contextual data about the destination for spans
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.6/docs/spec/spans/span.json#L44
|
|
*/
|
|
public function destination(): SpanContextDestinationInterface;
|
|
}
|
|
|
|
interface SpanContextDbInterface
|
|
{
|
|
/**
|
|
* A database statement (e.g. query) for the given database type
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L55
|
|
*
|
|
* @param string|null $statement
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setStatement(?string $statement): void;
|
|
}
|
|
|
|
interface SpanContextHttpInterface
|
|
{
|
|
/**
|
|
* The raw url of the correlating http request
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L73
|
|
*
|
|
* @param string|null $url
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setUrl(?string $url): void;
|
|
|
|
/**
|
|
* The status code of the http request
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L77
|
|
*
|
|
* @param int|null $statusCode
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setStatusCode(?int $statusCode): void;
|
|
|
|
/**
|
|
* The method of the http request
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L81
|
|
*
|
|
* @param string|null $method
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setMethod(?string $method): void;
|
|
}
|
|
|
|
/**
|
|
* An object containing contextual data about the destination for spans
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.6/docs/spec/spans/span.json#L44
|
|
*/
|
|
interface SpanContextDestinationInterface
|
|
{
|
|
/**
|
|
* Sets destination service context
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.11.0/docs/spec/v2/span.json#L106
|
|
*
|
|
* @param string $name
|
|
* @param string $resource
|
|
* @param string $type
|
|
*/
|
|
public function setService(string $name, string $resource, string $type): void;
|
|
}
|
|
|
|
/**
|
|
* This interface has functionality shared between Transaction and Span.
|
|
*/
|
|
interface ExecutionSegmentInterface
|
|
{
|
|
/**
|
|
* Hex encoded 64 random bits (== 8 bytes == 16 hex digits) ID.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L9
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L9
|
|
*/
|
|
public function getId(): string;
|
|
|
|
/**
|
|
* Hex encoded 128 random bits (== 16 bytes == 32 hex digits) ID of the correlated trace.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L14
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L19
|
|
*/
|
|
public function getTraceId(): string;
|
|
|
|
/**
|
|
* Recorded time of the event.
|
|
* For events that have non-zero duration this time corresponds to the start of the event.
|
|
* UTC based and in microseconds since Unix epoch.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L6
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L6
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/timestamp_epoch.json#L7
|
|
*/
|
|
public function getTimestamp(): float;
|
|
|
|
/**
|
|
* Begins a new span with this execution segment as the new span's parent.
|
|
*
|
|
* @param string $name New span's name
|
|
* @param string $type New span's type
|
|
* @param string|null $subtype New span's subtype
|
|
* @param string|null $action New span's action
|
|
* @param float|null $timestamp Start time of the new span
|
|
*
|
|
* @see SpanInterface::setName() For the description.
|
|
* @see SpanInterface::setType() For the description.
|
|
* @see SpanInterface::setSubtype() For the description.
|
|
* @see SpanInterface::setAction() For the description.
|
|
* @see SpanInterface::setTimestamp() For the description.
|
|
*
|
|
* @return SpanInterface New span
|
|
*/
|
|
public function beginChildSpan(
|
|
string $name,
|
|
string $type,
|
|
?string $subtype = null,
|
|
?string $action = null,
|
|
?float $timestamp = null
|
|
): SpanInterface;
|
|
|
|
/**
|
|
* Begins a new span with this execution segment as the new span's parent,
|
|
* runs the provided callback as the new span and automatically ends the new span.
|
|
*
|
|
* @param string $name New span's name
|
|
* @param string $type New span's type
|
|
* @param \Closure $callback Callback to execute as the new span
|
|
* @param string|null $subtype New span's subtype
|
|
* @param string|null $action New span's action
|
|
* @param float|null $timestamp Start time of the new span
|
|
*
|
|
* @see SpanInterface::setName() For the description.
|
|
* @see SpanInterface::setType() For the description.
|
|
* @see SpanInterface::setSubtype() For the description.
|
|
* @see SpanInterface::setAction() For the description.
|
|
* @see SpanInterface::setTimestamp() For the description.
|
|
*
|
|
* @return mixed The return value of $callback
|
|
*/
|
|
public function captureChildSpan(
|
|
string $name,
|
|
string $type,
|
|
\Closure $callback,
|
|
?string $subtype = null,
|
|
?string $action = null,
|
|
?float $timestamp = null
|
|
);
|
|
|
|
/**
|
|
* - For transactions:
|
|
* The name of this transaction.
|
|
* Generic designation of a transaction in the scope of a single service (eg: 'GET /users/:id').
|
|
*
|
|
* - For spans:
|
|
* Generic designation of a span in the scope of a transaction.
|
|
*
|
|
* The length of this string is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L47
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L136
|
|
*
|
|
* @param string $name
|
|
*/
|
|
public function setName(string $name): void;
|
|
|
|
/**
|
|
* Type is a keyword of specific relevance in the service's domain
|
|
* e.g.,
|
|
* - For transaction: 'db', 'external' for a span and 'request', 'backgroundjob' for a transaction, etc.
|
|
* - For span: 'db.postgresql.query', 'template.erb', etc.
|
|
*
|
|
* The length of this string is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L57
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L149
|
|
*
|
|
* @param string $type
|
|
*/
|
|
public function setType(string $type): void;
|
|
|
|
/**
|
|
* @deprecated Deprecated since version 1.3 - use injectDistributedTracingHeaders() instead
|
|
* @see injectDistributedTracingHeaders() Use it instead of this method
|
|
*
|
|
* Returns distributed tracing data
|
|
*/
|
|
public function getDistributedTracingData(): ?DistributedTracingData;
|
|
|
|
/**
|
|
* Returns distributed tracing data for the current span/transaction
|
|
*
|
|
* $headerInjector is callback to inject headers with signature
|
|
*
|
|
* (string $headerName, string $headerValue): void
|
|
*
|
|
* @param \Closure $headerInjector Callback that actually injects header(s) for the underlying transport
|
|
*/
|
|
public function injectDistributedTracingHeaders(\Closure $headerInjector): void;
|
|
|
|
/**
|
|
* Sets the end timestamp and finalizes this object's state.
|
|
*
|
|
* If any mutating method (for example any `set...` method is a mutating method)
|
|
* is called on a instance which has already then a warning is logged.
|
|
* For example, end() is a mutating method as well.
|
|
*
|
|
* @param float|null $duration In milliseconds with 3 decimal points.
|
|
*/
|
|
public function end(?float $duration = null): void;
|
|
|
|
/**
|
|
* Returns true if this execution segment has already ended.
|
|
*/
|
|
public function hasEnded(): bool;
|
|
|
|
/**
|
|
* Creates an error based on the given Throwable instance with this execution segment as the parent.
|
|
*
|
|
* @param \Throwable $throwable
|
|
*
|
|
* @return string|null ID of the reported error event or null if no event was reported
|
|
* (for example, because recording is disabled)
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json
|
|
*/
|
|
public function createErrorFromThrowable(\Throwable $throwable): ?string;
|
|
|
|
/**
|
|
* Creates an error based on the given Throwable instance with this execution segment as the parent.
|
|
*
|
|
* @param CustomErrorData $customErrorData
|
|
*
|
|
* @return string|null ID of the reported error event or null if no event was reported
|
|
* (for example, because recording is disabled)
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json
|
|
*/
|
|
public function createCustomError(CustomErrorData $customErrorData): ?string;
|
|
|
|
/**
|
|
* The outcome of the transaction/span: success, failure, or unknown.
|
|
* Outcome may be one of a limited set of permitted values
|
|
* describing the success or failure of the transaction/span.
|
|
* This field can be used for calculating error rates for incoming/outgoing requests.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.10.0/docs/spec/transactions/transaction.json#L59
|
|
* @link https://github.com/elastic/apm-server/blob/v7.10.0/docs/spec/spans/span.json#L54
|
|
* @link https://github.com/elastic/apm-server/blob/v7.10.0/docs/spec/outcome.json
|
|
*
|
|
* @param string|null $outcome
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setOutcome(?string $outcome): void;
|
|
|
|
/**
|
|
* @see setOutcome() For the description
|
|
*/
|
|
public function getOutcome(): ?string;
|
|
|
|
/**
|
|
* Returns true if this execution segment is a no-op (for example when recording is disabled).
|
|
*/
|
|
public function isNoop(): bool;
|
|
|
|
/**
|
|
* Discards this execution segment.
|
|
*/
|
|
public function discard(): void;
|
|
}
|
|
|
|
final class DistributedTracingData
|
|
{
|
|
/** @var string */
|
|
public $traceId;
|
|
|
|
/** @var string */
|
|
public $parentId;
|
|
|
|
/** @var bool */
|
|
public $isSampled;
|
|
|
|
/**
|
|
* @deprecated Deprecated since version 1.3 - use injectHeaders() instead
|
|
* @see injectHeaders() Use it instead of this method
|
|
*
|
|
* Returns distributed tracing data for the current span/transaction
|
|
*/
|
|
public function serializeToString(): string {}
|
|
|
|
/**
|
|
* Gets distributed tracing data for the current span/transaction
|
|
*
|
|
* $headerInjector is callback to inject headers with signature
|
|
*
|
|
* (string $headerName, string $headerValue): void
|
|
*
|
|
* @param \Closure $headerInjector Callback that actually injects header(s) for the underlying transport
|
|
*/
|
|
public function injectHeaders(\Closure $headerInjector): void {}
|
|
}
|
|
|
|
/**
|
|
* Data to create custom error event
|
|
*
|
|
* @see ElasticApm::createCustomError
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json#L53
|
|
*
|
|
* Code in this file is part of implementation internals and thus it is not covered by the backward compatibility.
|
|
*/
|
|
class CustomErrorData
|
|
{
|
|
/**
|
|
* @var int|string|null
|
|
*
|
|
* The error code set when the error happened, e.g. database error code
|
|
*
|
|
* The length of a string value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json#L56
|
|
*/
|
|
public $code = null;
|
|
|
|
/**
|
|
* @var string|null
|
|
*
|
|
* The original error message
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json#L61
|
|
*/
|
|
public $message = null;
|
|
|
|
/**
|
|
* @var string|null
|
|
*
|
|
* Describes the exception type's module namespace
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json#L65
|
|
*/
|
|
public $module = null;
|
|
|
|
/**
|
|
* @var string|null
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/errors/error.json#L80
|
|
*/
|
|
public $type = null;
|
|
}
|
|
|
|
interface TransactionContextInterface extends ExecutionSegmentContextInterface
|
|
{
|
|
/**
|
|
* Returns an object that can be used to collect information about HTTP request
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/context.json#L43
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json
|
|
*/
|
|
public function request(): TransactionContextRequestInterface;
|
|
}
|
|
|
|
/**
|
|
* This interface has functionality shared between Transaction and Span contexts'.
|
|
*/
|
|
interface ExecutionSegmentContextInterface
|
|
{
|
|
/**
|
|
* @param string $key
|
|
* @param string|bool|int|float|null $value
|
|
*
|
|
* Labels is a flat mapping of user-defined labels with string keys and null, string, boolean or number values.
|
|
*
|
|
* The length of a key and a string value is limited to 1024.
|
|
*
|
|
* @return void
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/transactions/transaction.json#L40
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/context.json#L46
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/spans/span.json#L88
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/tags.json
|
|
*/
|
|
public function setLabel(string $key, $value): void;
|
|
}
|
|
|
|
interface TransactionContextRequestInterface
|
|
{
|
|
/**
|
|
* HTTP method
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L33
|
|
*
|
|
* @param string $method
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setMethod(string $method): void;
|
|
|
|
/**
|
|
* Returns an object that can be used to collect information about HTTP request's URL
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/7.0/docs/spec/request.json#L50
|
|
*/
|
|
public function url(): TransactionContextRequestUrlInterface;
|
|
}
|
|
|
|
interface TransactionContextRequestUrlInterface
|
|
{
|
|
/**
|
|
* The domain of the request, e.g. 'example.com'
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L69
|
|
*
|
|
* @param ?string $domain
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setDomain(?string $domain): void;
|
|
|
|
/**
|
|
* The full, possibly agent-assembled URL of the request
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L64
|
|
*
|
|
* @param ?string $full
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setFull(?string $full): void;
|
|
|
|
/**
|
|
* The raw, unparsed URL of the HTTP request line, e.g https://example.com:443/search?q=elasticsearch.
|
|
* This URL may be absolute or relative.
|
|
* For more details, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L54
|
|
*
|
|
* @param ?string $original
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setOriginal(?string $original): void;
|
|
|
|
/**
|
|
* The path of the request, e.g. '/search'
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L79
|
|
*
|
|
* @param ?string $path
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setPath(?string $path): void;
|
|
|
|
/**
|
|
* The port of the request, e.g. 443
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L74
|
|
*
|
|
* @param ?int $port
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setPort(?int $port): void;
|
|
|
|
/**
|
|
* The protocol of the request, e.g. 'http'
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L59
|
|
*
|
|
* @param ?string $protocol
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setProtocol(?string $protocol): void;
|
|
|
|
/**
|
|
* Sets the query string information of the request.
|
|
* It is expected to have values delimited by ampersands.
|
|
*
|
|
* The length of a value is limited to 1024.
|
|
*
|
|
* @link https://github.com/elastic/apm-server/blob/v7.0.0/docs/spec/request.json#L84
|
|
*
|
|
* @param ?string $query
|
|
*
|
|
* @return void
|
|
*/
|
|
public function setQuery(?string $query): void;
|
|
}
|