PHP Custom Instrumentation using the OpenTelemetry API
このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
概要
OpenTelemetry API を使用してアプリケーションを手動でインスツルメントする理由はいくつかあります。
ddtrace ライブラリは、これらの目標を達成するためのさまざまなテクニックを提供しています。次のセクションでは、Datadog で使用するために OpenTelemetry API を使用してカスタムインスツルメンテーションを行う方法を説明します。
Setup
To configure OpenTelemetry to use the Datadog trace provider:
- Install OpenTelemetry API packages.
composer require open-telemetry/sdk
Add your desired manual OpenTelemetry instrumentation to your PHP code following the OpenTelemetry PHP Manual Instrumentation documentation.
Install the Datadog PHP tracing library.
Set DD_TRACE_OTEL_ENABLED to true.
Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application.
You can add attributes at the exact moment as you are starting the span:
$span = $tracer->spanBuilder('mySpan')
->setAttribute('key', 'value')
->startSpan();
Or while the span is active:
$activeSpan = OpenTelemetry\API\Trace\Span::getCurrent();
$activeSpan->setAttribute('key', 'value');
Setting errors on a span
Exception information is captured and attached to a span if one is active when the exception is raised.
// Create a span
$span = $tracer->spanBuilder('mySpan')->startSpan();
throw new \Exception('Oops!');
// 'mySpan' will be flagged as erroneous and have
// the stack trace and exception message attached as tags
Flagging a trace as erroneous can also be done manually:
use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\Context\Context;
// Can only be done after the setup steps, such as initializing the tracer.
try {
throw new \Exception('Oops!');
} catch (\Exception $e) {
$rootSpan = Span::fromContext(Context::getRoot());
$rootSpan->recordException($e);
}
Adding spans
To add a span:
// Get a tracer or use an existing one
$tracerProvider = \OpenTelemetry\API\Globals::tracerProvider();
$tracer = $tracerProvider->getTracer('datadog')
// Create a span
$span = $tracer->spanBuilder('mySpan')->startSpan();
// ... do stuff
// Close the span
$span->end();
Adding span events
Adding span events requires SDK version 1.3.0 or higher.
You can add span events using the addEvent API. This method requires a name parameter and optionally accepts attributes and timestamp parameters. The method creates a new span event with the specified properties and associates it with the corresponding span.
- Name [required]: A string representing the event’s name.
- Attributes [optional]: Zero or more key-value pairs with the following properties:
- The key must be a non-empty string.
- The value can be either:
- A primitive type: string, Boolean, or number.
- A homogeneous array of primitive type values (for example, an array of strings).
- Nested arrays and arrays containing elements of different data types are not allowed.
- Timestamp [optional]: A UNIX timestamp representing the event’s occurrence time. Expects
nanoseconds.
The following examples demonstrate different ways to add events to a span:
$span->addEvent("Event With No Attributes");
$span->addEvent(
"Event With Some Attributes",
[
'int_val' => 1,
'string_val' => "two",
'int_array' => [3, 4],
'string_array' => ["5", "6"],
'bool_array' => [true, false]
]
);
Read the OpenTelemetry specification for more information.
Recording exceptions
To record exceptions, use the recordException API. This method requires an exception parameter and optionally accepts a UNIX timestamp parameter. It creates a new span event that includes standardized exception attributes and associates it with the corresponding span.
The following examples demonstrate different ways to record exceptions:
$span->recordException(new \Exception("Error Message"));
$span->recordException(new \Exception("Error Message"), [ "status" => "failed" ]);
Read the OpenTelemetry specification for more information.
Accessing active spans
To access the currently active span:
$span = OpenTelemetry\API\Trace\Span::getCurrent();
Further Reading
