PHP 로그와 트레이스 상호 연결

자동 삽입

버전 0.89.0부터 PHP 트레에서는 트레이스 상호 연결 식별자를 애플리케이션 로그에 자동으로 삽입합니다. 자동 삽입을 활성화하려면 환경 변수 DD_LOGS_INJECTION (INI 설정 datadog.logs_injection)을 true로 설정합니다.

PHP 트레이서는 Monolog 또는 Laminas 로그와 같은 PSR-3 준수 로거를 지원합니다.

참고: 로깅 라이브러리를 설정하여 JSON 형식으로 로그를 생성하도록 합니다. 이렇게 하면

로그에 삽입 설정하기

아직 추가하지 않았다면 DD_ENV, DD_SERVICE, DD_VERSION를 사용하여 PHP 트레이서를 설정합니다. 이렇게 하면 env, service, version를 로그에 추가하는 데 가장 최적화된 환경을 조성할 수 있습니다. 자세한 내용을 확인하려면 통합 서비스 태깅을 참조하세요.

PHP 트레이서는 트레이스 상호 연결 식별자를 로그에 삽입하도록 설정할 수 있는 다양한 방법을 제공합니다.

로그 컨텍스트에 트레이스 상호 연결 식별자를 추가하기

PHP 트레이서의 기본 작업은 트레이스 상호 연결 식별자를 로그 컨텍스트에 추가하는 것입니다.

예를 들어, 다음과 같이 Laravel 애플리케이션에서 Monolog 라이브러리를 사용하는 경우를 살펴보겠습니다.

use Illuminate\Support\Facades\Log;
# ...
Log::debug('Hello, World!');

PHP 트레이서는 사용 가능한 트레이스 상호 연결 식별자를 로그 컨텍스트에 추가합니다. 위의 로깅된 메시지는 다음과 같이 변환될 수 있습니다.

[2022-12-09 16:02:42] production.DEBUG: Hello, World! {"dd.trace_id":"1234567890abcdef","dd.span_id":"1234567890abcdef","dd.service":"laravel","dd.version":"8.0.0","dd.env":"production","status":"debug"}

참고: 메시지에 자리표시자가 있거나 트레이스 ID가 이미 존재하는 경우, PHP 트레이서는 트레이스 상호 연결 식별자를 로그 컨텍스트에 추가하지 않습니다.

메시지에 자리표시자 사용하기

메시지에 자리표시자를 사용하여 로그에 트레이스 상호 연결 식별자를 자동으로 삽입할 수 있습니다. PHP 트레이스는 다음과 같은 자리표시자를 지원합니다.

  • %dd.trace_id%: 트레이스 ID
  • %dd.span_id%: 스팬(span) ID
  • %dd.service%: 서비스 이름
  • %dd.version%: 서비스 버전
  • %dd.env%: 서비스 환경

자리표시자는 대소문자를 구분하며 반드시 % 문자로 묶어야 합니다.

예를 들어, 다음과 같이 Laravel 애플리케이션에서 Monolog 라이브러리를 사용하는 경우, 다음과 같이 로그 메시지에 삽입하도록 설정할 수 있습니다.

use Illuminate\Support\Facades\Log;
# ...
Log::info('Hello, World! [%dd.trace_id% %dd.span_id% %status%]');

PHP 트레이서는 자리표시자를 해당 값으로 대체합니다. 예를 들어, 위의 로깅된 메시지는 다음과 같이 변환될 수 있습니다.

[2022-12-09 16:02:42] production.INFO: Hello, World! [dd.trace_id="1234567890abcdef" dd.span_id="1234567890abcdef" status="info"]

참고: PHP 로그 파이프라인에 제공된 기본 파싱 규칙을 사용하려는 경우 대괄호 사용은 필수입니다. 사용자 지정 파싱 규칙을 사용하는 경우 필요하다면 대괄호를 생략할 수 있습니다.

수동 삽입

참고:\DDTrace\current_context() 함수는 버전 0.61.0에 도입되었으며 10진수 트레이스 식별자를 반환합니다.

로그와 트레이스를 연결하려면 로그에 dd.trace_id 및 dd.span_id 속성이 반드시 포함되어야 하며, 개별 트레이스 ID 및 스팬(span) ID가 포함되어야 합니다.

Datadog 로그 통합을 사용하여 로그를 파싱하지 않는 경우, 사용자 지정 로그 파싱 규칙은 dd.trace_id 및 dd.span_id가 문자열로 파싱되고 트레이스 리매퍼를 통해 다시 맵핑되는지 확인해야 합니다. 자세한 내용은 트레이스 ID 패널에 표시되지 않는 상호 연결 로그에서 확인할 수 있습니다.

예를 들어, 로그에 다음 두 속성을 추가할 수 있습니다.

  <?php
  $append = sprintf(
      ' [dd.trace_id=%s dd.span_id=%s]',
      \DDTrace\logs_correlation_trace_id(),
      \dd_trace_peek_span_id()
  );
  my_error_logger('Error message.' . $append);
?>

로거가 monolog/monolog 라이브러리를 실행한다면 Logger::pushProcessor()를 사용하여 모든 로그메시지에 식별자를 자동으로 추가합니다. monolog v1의 경우 다음 설정을 추가합니다.

<?php
  $logger->pushProcessor(function ($record) {
      $record['message'] .= sprintf(
          ' [dd.trace_id=%s dd.span_id=%s]',
          \DDTrace\logs_correlation_trace_id(),
          \dd_trace_peek_span_id()
      );
      return $record;
  });
?>

monolog v2의 경우 다음 설정을 추가합니다.

<?php
  $logger->pushProcessor(function ($record) {
      return $record->with(message: $record['message'] . sprintf(
          ' [dd.trace_id=%s dd.span_id=%s]',
          \DDTrace\logs_correlation_trace_id(),
          \dd_trace_peek_span_id()
      ));
    });
  ?>

애플리케이션이 JSON 로그 형식을 사용하는 경우, 다음과 같이 로그 메시지에 trace_id 및 span_id를 추가하는 대신, trace_id 및 span_id을 포함하는 1레벨 키 dd를 추가합니다.

<?php
  $logger->pushProcessor(function ($record) use ($context) {
      $record['dd'] = [
          'trace_id' => \DDTrace\logs_correlation_trace_id(),
          'span_id'  => \dd_trace_peek_span_id()
      ];

      return $record;
  });
?>

monolog v3의 경우 다음 설정을 추가합니다.

<?php
  $logger->pushProcessor(function ($record) {
        $record->extra['dd'] = [
            'trace_id' => \DDTrace\logs_correlation_trace_id(),
            'span_id'  => \dd_trace_peek_span_id()
        ];
        return $record;
    });
?>

JSON으로 로그를 수집하는 경우, JSON 로그 전처리로 이동하여 트레이스 ID 속성 필드에 extra.dd.trace_id을 추가합니다.

참고 자료

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

애플리케이션을 수동으로 계측하여 트레이스를 생성합니다.설명서 more more 서비스, 리소스 및 트레이스 탐색설명서 more more 로그 요청을 트레이스와 자동으로 상호 연결블로그 more more 제품 간 상관관계를 활용한 쉬운 트러블슈팅길라잡이 more more