OpenTelemetry API를 사용한 PHP 커스텀 계측

Unsure when to use OpenTelemetry with Datadog? Start with Custom Instrumentation with the OpenTelemetry API to learn more.

Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

  • You are not using Datadog supported library instrumentation.
  • You want to extend the ddtrace library’s functionality.
  • You need finer control over instrumenting your applications.

The ddtrace library provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with Datadog.

설정

OpenTelemetry를 설정하여 Datadog 트레이스 공급자를 사용하려면,

  1. OpenTelemetry API 패키지를 설치합니다.
composer require open-telemetry/sdk

  1. OpenTelemetry PHP 매뉴얼 계측 설명서에 따라 PHP 코드에 원하는 OpenTelemetry 계측을 수동으로 추가하세요.

  2. Datadog PHP 추적 라이브러리]6을 설치합니다.

  3. DD_TRACE_OTEL_ENABLED을 true로 설정합니다.

Datadog는 이러한 OpenTelemetry 스팬(span)을 다른 Datadog 애플리케이션 성능 모니터링(APM) 스팬(span)과 결합하여 애플리케이션의 단일 트레이스로 만듭니다.

스팬(span) 태그 추가하기

스팬(span)을 시작하는 바로 그 순간에 속성을 추가할 수 있습니다:

$span = $tracer->spanBuilder('mySpan')
    ->setAttribute('key', 'value')
    ->startSpan();

또는 스팬(span) 이 활성화되어 있는 동안,

$activeSpan = OpenTelemetry\API\Trace\Span::getCurrent();

$activeSpan->setAttribute('key', 'value');

스팬(span)에 오류 설정

예외가 발생할 때 활성화되어 있는 경우 예외 정보가 캡처되고 스팬(span)에 첨부됩니다.

// 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

트레이스에 오류 플래그를 지정하는 것도 수동으로 할 수 있습니다:

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);
}

스팬(span) 추가

스팬(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();

스팬 이벤트 추가하기

스팬 이벤트를 추가하려면 SDK 버전 1.3.0 이상이 필요합니다.

addEvent API를 사용하여 스팬 이벤트를 추가할 수 있습니다. 이 메서드에는 name 파라미터가 필요하며 선택적으로 attributes 및 timestamp 파라미터를 허용합니다. 이 메서드는 지정된 속성을 가진 새 스팬 이벤트를 생성하고 해당 스팬 이벤트와 연결합니다.

  • 이름 [필수]: 이벤트의 이름을 나타내는 문자열입니다.
  • 속성 [옵션]: 다음 속성을 가진 0개 이상의 키-값 쌍입니다.
    • 키는 비어 있지 않은 문자열이어야 합니다.
    • 값은 둘 중 하나가 될 수 있습니다.
      • 기본 유형: 문자열, 부울, 또는 숫자
      • 원시 타입 값의 균일한 배열(예: 문자열 배열)입니다.
    • 중첩 배열 및 서로 다른 데이터 유형의 요소를 포함하는 배열은 허용되지 않습니다.
  • 타임스탬프 [옵션]: 이벤트 발생 시간을 나타내는 UNIX 타임스탬프입니다. nanoseconds가 예상됩니다.

다음 예는 스팬에 이벤트를 추가하는 다양한 방법을 보여줍니다.

$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]
    ]
);

자세한 내용은 OpenTelemetry 사양을 참조하세요.

예외 사항 기록

예외를 기록하려면 recordException API를 사용하세요. 이 메서드는 exception 파라미터가 필요하며, 선택적으로 UNIX timestamp 파라미터를 허용합니다. 표준화된 예외 속성을 포함하는 새 스팬 이벤트를 생성하고 해당 스팬과 연결합니다.

다음 예에서는 예외를 기록하는 다양한 방법을 보여줍니다.

$span->recordException(new \Exception("Error Message"));
$span->recordException(new \Exception("Error Message"), [ "status" => "failed" ]);

자세한 내용은 OpenTelemetry 사양을 읽어보세요.

활성 스팬에 액세스(스팬(span))

현재 활성화된 스팬(span) 에 액세스하려면:

스팬(span) = OpenTelemetry\API\추적하다\스팬(span)::getCurrent();

참고 자료

추가 유용한 문서, 링크 및 기사:

서비스, 리소스, 트레이스 탐색설명서 more more OpenTelemetry API 상호 운용성 및 Datadog의 계측된 트레이스설명서 more more