PHP Custom Instrumentation using the OpenTelemetry API

このページは日本語には対応しておりません。随時翻訳に取り組んでいます。翻訳に関してご質問やご意見ございましたら、お気軽にご連絡ください。
Datadog で OpenTelemetry を使用するタイミングがわからない場合は、OpenTelemetry API を使用したカスタムインスツルメンテーションから始めて、詳細を学びましょう。

概要

OpenTelemetry API を使用してアプリケーションを手動でインスツルメントする理由はいくつかあります。

ddtrace ライブラリは、これらの目標を達成するためのさまざまなテクニックを提供しています。次のセクションでは、Datadog で使用するために OpenTelemetry API を使用してカスタムインスツルメンテーションを行う方法を説明します。

Setup

To configure OpenTelemetry to use the Datadog trace provider:

  1. Install OpenTelemetry API packages.
composer require open-telemetry/sdk

  1. Add your desired manual OpenTelemetry instrumentation to your PHP code following the OpenTelemetry PHP Manual Instrumentation documentation.

  2. Install the Datadog PHP tracing library.

  3. Set DD_TRACE_OTEL_ENABLED to true.

Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application.

Adding span tags

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

お役に立つドキュメント、リンクや記事:

Explore your services, resources, and tracesDOCUMENTATION more more Interoperability of OpenTelemetry API and Datadog instrumented tracesDOCUMENTATION more more