개요

Datadog 추적 라이브러리는 코드 계측을 위해 OpenTelemetry API를 구현 기능을 제공합니다. 이에 따라 공급 업체와 무관하게 모든 서비스를 계측하면서도 Datadog의 네이티브 구현, 기능, 제품의 장점을 모두 이용할 수 있습니다. Datadog 스타일 스팬과 트레이스를 생성해 Datadog 추적 라이브러리에서 내 언어에 맞게 처리하여 Datadog로 전송할 수 있습니다.

OpenTelemetry API로 코드를 계측하면 다음을 할 수 있습니다.

• 코드가 공급 업체와 무관하게 API 호출을 할 수 있습니다.
• 컴파일링할 때 코드가 Datadog 추적 라이브러리에 의존하지 않습니다(런타임에만 필요).
• 코드가 사용되지 않는 OpenTracing API를 사용하지 않습니다.

계측된 애플리케이션에서 OpenTelemetry SDK를 Datadog 추적 라이브러리로 대체하세요. 그러면 실행 코드로 생성된 트레이스와 Datadog 전용 제품 내 Datadog 트레이스를 처리, 분석, 모니터링할 수 있습니다.

자세한 내용은 OpenTelemetry API 상호 운용성 및 Datadog의 계측된 트레이스을 참고하세요.

Datadog 추적 라이브러리를 여기에 안내된 대로 구성하면 OpenTelemetry 계측된 코드로 생성된 스팬과 트레이스를 허용하고, 텔레메트리를 처리해 Datadog로 전송합니다. 예를 들어 코드를 OpenTelemetry API로 이미 계측했거나 OpenTelemetry API로 계측하고 싶고, 코드를 변경하지 않고 Datadog 추적 라이브러리 사용의 장점을 활용하고 싶을 때 이 방법을 사용할 수 있습니다.

OpenTelemetry로 코드를 계측한 후 Datadog 추적 라이브러리를 통하지 않고 스팬 데이터를 Datadog로 전송하는 방법을 모색 중인 경우 Datadog 내 OpenTelemetry를 참고하세요.

Requirements and limitations

• Datadog Ruby tracing library dd-trace-rb version 1.9.0 or greater.
• Gem version support 1.1.0 or greater.

The following OpenTelemetry features implemented in the Datadog library as noted:

Configuring OpenTelemetry to use the Datadog tracing library

1. Add your desired manual OpenTelemetry instrumentation to your Ruby code following the OpenTelemetry Ruby Manual Instrumentation documentation. Important! Where those instructions indicate that your code should call the OpenTelemetry SDK, call the Datadog tracing library instead.

2. Add the datadog gem to your Gemfile:

   source 'https://rubygems.org'
   gem 'datadog' # For dd-trace-rb v1.x, use the `ddtrace` gem.
   

3. Install the gem by running bundle install.

4. Add the following lines to your OpenTelemetry configuration file:

   require 'opentelemetry/sdk'
   require 'datadog/opentelemetry'
   

5. Add a configuration block to your application where you can activate integrations and change tracer settings. Without additional configuration here, only code you have instrumented with OpenTelemetry is traced:

   Datadog.configure do |c|
     ...
   end
   

   Using this block you can:

   • Add additional Datadog configuration settings
   • Activate or reconfigure Datadog instrumentation

Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application. It supports integration instrumentation and OpenTelemetry Automatic instrumentation also.

Adding span events

You can add span events using the add_event 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 seconds(Float).

The following examples demonstrate different ways to add events to a span:

span.add_event('Event With No Attributes')
span.add_event(
  'Event With All Attributes',
  attributes: { 'int_val' => 1, 'string_val' => 'two', 'int_array' => [3, 4], 'string_array' => ['5', '6'], 'bool_array' => [false, true]}
)

Read the OpenTelemetry specification for more information.

Recording exceptions

To record exceptions, use the record_exception 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.record_exception(
  StandardError.new('Error Message')
)
span.record_exception(
  StandardError.new('Error Message'),
  attributes: { 'status' => 'failed' }
)

Read the OpenTelemetry specification for more information.

Further Reading

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

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