Ruby 애플리케이션 추적 (Tracing Ruby Applications)

datadog은 Datadog의 Ruby용 클라이언트 라이브러리예요. Ruby 애플리케이션의 성능과 보안을 파악할 수 있는 다양한 도구를 포함하고 있어서, Ruby 개발자가 병목 현상이나 기타 문제를 찾아내는 데 도움을 줘요.

출처: 문서

본문

참고: 이 문서는 datadog gem v2.x용이에요. ddtrace gem v1.x 문서를 찾고 있다면 레거시 Ruby 애플리케이션 추적 문서를 보세요.

시작하기 (Getting started)

0.x 버전에서 업그레이드하는 경우에는 업그레이드 가이드를 확인해 보세요.

일반적인 APM 문서는 설정 문서를 참고해요.

애플리케이션이 Datadog에 정보를 보내기 시작한 뒤 APM이 어떤 모습인지 더 알고 싶다면 용어와 개념 문서를 확인해 보세요.

라이브러리 API 문서는 YARD 문서를 참고해요.

기여하고 싶다면 기여 가이드라인과 개발 가이드를 확인해 보세요.

호환성 요구 사항 (Compatibility requirements)

Datadog Ruby 라이브러리의 전체 지원 목록은 호환성 요구 사항을 참고해요.

설치 (Installation)

Ruby 애플리케이션에 추적을 추가하는 일은 몇 단계만 거치면 돼요:

1. 추적을 위한 Datadog Agent 설정하기
2. 애플리케이션 계측하기
3. 애플리케이션을 Datadog Agent에 연결하기

추적을 위한 Datadog Agent 설정 (Setup the Datadog Agent for tracing)

datadog을 설치하기 전에, 먼저 Datadog Agent를 설치해 두세요. datadog이 추적 데이터를 보낼 대상이에요.

그런 다음 Datadog Agent가 추적을 수락하도록 설정해요. 다음 중 한 가지 방법을 사용하세요:

• Agent 환경에 DD_APM_ENABLED=true 설정

또는

• Agent 설정 파일에 apm_enabled: true 추가

추가로, 컨테이너 환경에서는…

• Agent 환경에 DD_APM_NON_LOCAL_TRAFFIC=true 설정

또는

• Agent 설정 파일에 apm_non_local_traffic: true 추가

컨테이너 환경에서 Agent가 추적을 수신하도록 구성하려면 Docker, Kubernetes, Amazon ECS, Fargate별 설정 지침을 확인해 보세요.

추적 데이터 수집 설정 (Configuring trace data ingestion)

Datadog Agent는 기본적으로 HTTP를 통해 포트 8126에서 추적을 수신해요.

Agent가 추적 데이터를 수신하는 프로토콜이나 포트는 다음과 같이 변경할 수 있어요.

HTTP over TCP의 경우:

• Agent 환경에 DD_APM_RECEIVER_PORT=<port> 설정

또는

• Agent 설정 파일에 apm_config: receiver_port: <port> 추가

Unix Domain Socket (UDS)의 경우:

• DD_APM_RECEIVER_SOCKET=<path-to-socket-file> 설정

또는

• Agent 설정 파일에 apm_config: receiver_socket: <path-to-socket-file> 추가

애플리케이션 계측 (Instrument your application)

Rails 또는 Hanami 애플리케이션 (Rails or Hanami applications)

1. Gemfile에 datadog gem을 추가해요:

   source 'https://rubygems.org'
   gem 'datadog', require: 'datadog/auto_instrument'
   

2. bundle install로 gem을 설치해요

3. 다음 내용이 담긴 config/initializers/datadog.rb 파일을 만들어요:

   Datadog.configure do |c|
     # Add additional configuration here.
     # Activate integrations, change tracer settings, etc...
   end
   

이 블록을 사용해서 다음과 같이 할 수 있어요:

• 추가 설정값 추가하기
• 계측 활성화 또는 재구성하기

기타 Ruby 애플리케이션 (Other Ruby applications)

애플리케이션이 위에서 언급한 gem(Rails 또는 Hanami)을 사용하지 않는다면 다음과 같이 설정할 수 있어요:

1. Gemfile에 datadog gem을 추가해요:

   source 'https://rubygems.org'
   gem 'datadog'
   

2. bundle install로 gem을 설치해요

3. 계측해야 하는 지원되는 라이브러리나 프레임워크를 require해요.

• 애플리케이션에 require 'datadog/auto_instrument'을 추가해요. 참고: 이 작업은 지원되는 라이브러리나 프레임워크를 require한 이후에 해야 해요.

  # Example frameworks and libraries
  require 'sinatra'
  require 'faraday'
  require 'redis'
  
  require 'datadog/auto_instrument'
  

1. 애플리케이션에 설정 블록을 추가해요:

   Datadog.configure do |c|
     # Add additional configuration here.
     # Activate integrations, change tracer settings, etc...
   end
   

이 블록을 사용해서 다음과 같이 할 수 있어요:

• 추가 설정값 추가하기
• 계측 활성화 또는 재구성하기

OpenTelemetry 설정 (Configuring OpenTelemetry)

OTLP를 사용하면 datadog 없이도 OpenTelemetry 트레이스를 Datadog Agent로 직접 보낼 수 있어요. 자세한 내용은 Datadog Agent의 OTLP 수집 문서를 확인해 보세요.

애플리케이션을 Datadog Agent에 연결 (Connect your application to the Datadog Agent)

기본적으로 datadog은 아래 나열된 우선순위에서 가장 먼저 사용 가능한 설정으로 Agent에 연결해요:

1. 명시적으로 제공된 설정값(호스트명/포트/전송 방식)
2. /var/run/datadog/apm.socket에 있는 Unix Domain Socket (UDS)
3. 127.0.0.1:8126로 HTTP over TCP

Datadog Agent가 이 중 어느 위치에서든 수신 중이라면 추가 설정이 필요하지 않아요.

Agent가 애플리케이션과 다른 호스트나 컨테이너에서 실행 중이거나, 다른 프로토콜로 트레이스를 보내고 싶다면 그에 맞게 애플리케이션을 설정해야 해요.

• HTTP over TCP로 추적 데이터를 Agent에 보내는 방법
• Unix Domain Socket (UDS)로 추적 데이터를 Agent에 보내는 방법

설치 마지막 단계 (Final steps for installation)

설정을 마치면 몇 분 안에 서비스가 APM 서비스 페이지에 나타나요. APM UI 사용법에 대해 더 알아보세요.

테스트/spec 중 비활성화 및 Ruby 테스트 최적화 (Disabling during testing/specs and test optimization for Ruby)

추적은 기본적으로 활성화되어 있어요. 여기에는 다음이 포함돼요:

• datadog/auto_instrument을 사용해 로드할 때
• Datadog.configure 블록에서 tracing.instrument으로 통합을 활성화할 때
• Datadog::Tracing.trace 메서드를 호출할 때

테스트/spec을 실행할 때 추적을 비활성화하고 싶다면 DD_TRACE_ENABLED 환경 변수를 false로 설정하거나 코드로 설정할 수 있어요:

Datadog.configure do |c|
  c.tracing.enabled = false
end

또한 테스트에 대한 더 많은 가시성을 얻고 싶거나 느리거나 불안정한 테스트 스위트로 고생하고 있다면, datadog-ci gem을 통한 Datadog의 테스트 최적화를 살펴보세요.

수동 계측 (Manual Instrumentation)

지원되는 프레임워크 계측을 사용하지 않는다면, 코드를 수동으로 계측하고 싶을 거예요.

Ruby 코드를 추적하려면 Datadog::Tracing.trace 메서드를 사용할 수 있어요:

Datadog::Tracing.trace(name, **options) do |span, trace|
  # Wrap this block around the code you want to instrument
  # Additionally, you can modify the span here.
  # e.g. Change the resource name, set tags, etc...
end

여기서 name은 수행 중인 작업의 일반적인 종류를 설명하는 String이어야 해요 (예: 'web.request', 'request.parse').

그리고 options는 다음 선택적 키워드 인자예요:

Key	Type	Description	Default
autostart	Bool	시간 측정을 자동으로 시작할지 여부예요. false면 사용자가 span.start를 호출해야 해요.	true
continue_from	Datadog::TraceDigest	다른 실행 컨텍스트에서 시작된 트레이스를 이어서 계속해요. TraceDigest가 이어지는 지점을 설명해요.	nil
on_error	Proc	스팬에서 오류가 발생했을 때 오류 처리 동작을 재정의해요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요.	`proc {
resource	String	작업 대상이 되는 리소스나 액션의 이름이에요. resource 값이 같은 트레이스는 메트릭을 위해 함께 그룹화돼요(하지만 각각 독립적으로 볼 수 있어요). 보통 URL, 쿼리, 요청 등 도메인 특화 값이에요 (예: 'Article#submit', http://example.com/articles/list.)	name of Span.
service	String	이 스팬이 속한 서비스 이름이에요 (예: 'my-web-service')	Tracer default-service, $PROGRAM_NAME 또는 'ruby'
start_time	Time	스팬이 실제로 시작된 시각이에요. 이미 발생한 이벤트를 추적할 때 유용해요.	Time.now
tags	Hash	스팬에 추가해야 할 추가 태그예요.	{}
type	String	스팬의 유형이에요 (예: 'http', 'db' 등)	nil

최소한 service와 resource는 모두 설정하는 걸 강력히 권장해요. service나 resource가 nil인 스팬은 Datadog Agent가 폐기해요.

수동 계측이 실제로 적용된 예시:

get '/posts' do
  Datadog::Tracing.trace('web.request', service: 'my-blog', resource: 'GET /posts') do |span|
    # Trace the activerecord call
    Datadog::Tracing.trace('posts.fetch') do
      @posts = Posts.order(created_at: :desc).limit(10)
    end

    # Add some APM tags
    span.set_tag('http.method', request.request_method)
    span.set_tag('posts.count', @posts.length)

    # Trace the template rendering
    Datadog::Tracing.trace('template.render') do
      erb :index
    end
  end
end

비동기 추적 (Asynchronous tracing)

Datadog::Tracing.trace로 코드 블록을 항상 감쌀 수 있는 건 아니에요. 이벤트 기반 또는 알림 기반 계측 중에는 이벤트가 시작되거나 끝날 때만 알려주는 경우가 있어요.

이런 작업을 추적하려면 블록 없이 Datadog::Tracing.trace를 호출해서 코드를 비동기적으로 추적할 수 있어요:

# Some instrumentation framework calls this after an event finishes...
def db_query(start, finish, query)
  span = Datadog::Tracing.trace('database.query', start_time: start)
  span.resource = query
  span.finish(finish)
end

블록 없이 Datadog::Tracing.trace를 호출하면 시작됐지만 끝나지 않은 Datadog::Tracing::SpanOperation이 반환돼요. 그런 다음 이 스팬을 원하는 대로 수정하고 finish로 닫을 수 있어요.

끝나지 않은 스팬을 남겨두면 안 돼요. 트레이스가 완료될 때 스팬이 열려 있으면 트레이스가 폐기돼요. 이런 일이 벌어질 것 같다면 디버그 모드를 활성화해서 경고를 확인할 수 있어요.

시작/종료 이벤트를 처리할 때 이런 상황을 피하려면 Datadog::Tracing.active_span을 사용해 현재 활성 스팬을 가져올 수 있어요.

# e.g. ActiveSupport::Notifications calls this when an event starts
def start(name, id, payload)
  # Start a span
  Datadog::Tracing.trace(name)
end

# e.g. ActiveSupport::Notifications calls this when an event finishes
def finish(name, id, payload)
  # Retrieve current active span (thread-safe)
  current_span = Datadog::Tracing.active_span
  unless current_span.nil?
    current_span.resource = payload[:query]
    current_span.finish
  end
end

중첩 메서드에서 트레이스 보강 (Enriching traces from nested methods)

어떤 메서드에서든 현재 활성 스팬에 추가 정보를 태그로 붙일 수 있어요. 다만 활성 스팬이 없는 상태에서 메서드가 호출되면 active_span은 nil이 돼요.

# e.g. adding tag to active span

current_span = Datadog::Tracing.active_span
current_span.set_tag('my_tag', 'my_value') unless current_span.nil?

현재 스팬에 예외를 기록할 수 있어요. 기록된 예외는 스팬 이벤트로 추가돼요. 스팬 수명 동안 여러 예외를 기록할 수 있어요.

# e.g: recording an exception in the active span
rescue => e
  current_span = Datadog::Tracing.active_span
  current_span&.record_exception(e, attributes: { "foo" => "bar" })
end

active_trace 메서드로 현재 활성 트레이스를 가져올 수도 있어요. 활성 트레이스가 없으면 nil을 반환해요.

# e.g. accessing active trace

current_trace = Datadog::Tracing.active_trace

스팬 이벤트 추가 (Adding span events)

스팬 이벤트는 스팬에 붙은 타임스탬프 주석으로, 스팬 수명 동안 구조화된 로그, 예외, 사용자 지정 이벤트를 기록하는 데 유용해요. 현재 활성 스팬에 사용자 지정 스팬 이벤트를 다음과 같이 만들어 추가할 수 있어요:

event = Datadog::Tracing::SpanEvent.new(
 "custom.event.name",
 attributes: { "key1" => "value1", "key2" => 123 }
)

span.span_events << event

스팬에 여러 이벤트를 추가할 수 있어요. 각 이벤트 반드시 이름을 포함하고, 선택적으로 속성 집합과 타임스탬프(나노초)를 포함할 수 있어요. 타임스탬프가 없으면 현재 시간이 사용돼요.

이것은 트레이스 안에서 애플리케이션별 이벤트, 오류, 이정표를 기록하는 데 유용해요.

통합 계측 (Integration instrumentation)

많은 인기 라이브러리와 프레임워크가 기본적으로 지원되며 자동 계측할 수 있어요. 자동으로 활성화되진 않지만, Datadog.configure API를 사용해 쉽게 활성화하고 설정할 수 있어요:

Datadog.configure do |c|
  # Activates and configures an integration
  c.tracing.instrument :integration_name, **options
end

options는 통합별 설정을 위한 키워드 인자예요.

사용 가능한 통합과 지원 버전 목록은 Ruby 통합 호환성을 참고해요.

사용 가능한 통합의 설정 옵션 목록은 다음을 참고해요:

Action Cable

Action Cable 통합은 브로드캐스트 메시지와 채널 액션을 추적해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :action_cable, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTION_CABLE_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Action Mailer

Action Mailer 통합은 Rails 5 ActionMailer 액션에 대한 추적을 제공해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :action_mailer, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTION_MAILER_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
email_data	Bool	action_mailer.deliver 스팬에 추가 이메일 페이로드 메타데이터를 추가할지 여부예요. 필드에는 ['subject', 'to', 'from', 'bcc', 'cc', 'date', 'perform_deliveries']가 있어요.	false

Action Pack

대부분의 경우 Action Pack은 Rails의 일부로 설정되지만, 별도로도 활성화할 수 있어요:

require 'actionpack'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :action_pack, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTION_PACK_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Action View

대부분의 경우 Action View는 Rails의 일부로 설정되지만, 별도로도 활성화할 수 있어요:

require 'actionview'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :action_view, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTION_VIEW_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
template_base_path	String	템플릿 이름을 파싱할 때 사용돼요. 템플릿을 views/ 폴더에 저장하지 않는다면 이 값을 변경해야 할 수도 있어요	'views/'

Active Job

대부분의 경우 Active Job은 Rails의 일부로 설정되지만, 별도로도 활성화할 수 있어요:

require 'active_job'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :active_job, **options
end

ExampleJob.perform_later

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTIVE_JOB_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Active Model Serializers

Active Model Serializers 통합은 0.9+ 버전의 serialize 이벤트와 0.10+ 버전의 render 이벤트를 추적해요.

require 'active_model_serializers'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :active_model_serializers, **options
end

my_object = MyModel.new(name: 'my object')
ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTIVE_MODEL_SERIALIZERS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Active Record

대부분의 경우 Active Record는 웹 프레임워크(Rails, Sinatra…)의 일부로 설정되지만, 단독으로도 설정할 수 있어요:

require 'tmpdir'
require 'sqlite3'
require 'active_record'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :active_record, **options
end

Dir::Tmpname.create(['test', '.sqlite']) do |db|
  conn = ActiveRecord::Base.establish_connection(adapter: 'sqlite3',
                                                 database: db)
  conn.connection.execute('SELECT 42') # traced!
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTIVE_RECORD_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	String	SQL 쿼리 계측의 서비스 이름을 덮어써요. ActiveRecord 인스턴스화 계측은 항상 애플리케이션에 설정된 서비스 이름을 사용해요.	데이터베이스 어댑터 이름 (예: 'mysql2')

데이터베이스별 트레이스 설정

describes 옵션을 사용해 데이터베이스 연결별로 트레이스 설정을 구성할 수 있어요:

# Provide a `:describes` option with a connection key.
# Any of the following keys are acceptable and equivalent to one another.
# If a block is provided, it yields a Settings object that
# accepts any of the configuration options listed above.

Datadog.configure do |c|
  # Symbol matching your database connection in config/database.yml
  # Only available if you are using Rails with ActiveRecord.
  c.tracing.instrument :active_record, describes: :secondary_database, service_name: 'secondary-db'

  # Block configuration pattern.
  c.tracing.instrument :active_record, describes: :secondary_database do |second_db|
    second_db.service_name = 'secondary-db'
  end

  # Connection string with the following connection settings:
  # adapter, username, host, port, database
  # Other fields are ignored.
  c.tracing.instrument :active_record, describes: 'mysql2://[email protected]:3306/mysql', service_name: 'secondary-db'

  # Hash with following connection settings:
  # adapter, username, host, port, database
  # Other fields are ignored.
  c.tracing.instrument :active_record, describes: {
      adapter:  'mysql2',
      host:     '127.0.0.1',
      port:     '3306',
      database: 'mysql',
      username: 'root'
    },
    service_name: 'secondary-db'

  # If using the `makara` gem, it's possible to match on connection `role`:
  c.tracing.instrument :active_record, describes: { makara_role: 'primary' }, service_name: 'primary-db'
  c.tracing.instrument :active_record, describes: { makara_role: 'replica' }, service_name: 'secondary-db'
end

데이터베이스 연결 필드의 부분 일치를 기반으로 설정을 만들 수도 있어요:

Datadog.configure do |c|
  # Matches any connection on host `127.0.0.1`.
  c.tracing.instrument :active_record, describes: { host:  '127.0.0.1' }, service_name: 'local-db'

  # Matches any `mysql2` connection.
  c.tracing.instrument :active_record, describes: { adapter: 'mysql2'}, service_name: 'mysql-db'

  # Matches any `mysql2` connection to the `reports` database.
  #
  # In case of multiple matching `describe` configurations, the latest one applies.
  # In this case a connection with both adapter `mysql` and database `reports`
  # will be configured `service_name: 'reports-db'`, not `service_name: 'mysql-db'`.
  c.tracing.instrument :active_record, describes: { adapter: 'mysql2', database:  'reports'}, service_name: 'reports-db'
end

여러 describes 설정이 연결과 일치하면 마지막으로 설정된 일치 규칙이 적용돼요.

ActiveRecord가 describes가 정의한 키와 일치하는 연결을 사용하는 이벤트를 추적하면, 그 연결에 할당된 트레이스 설정을 사용해요. 연결이 설명된 어떤 연결과도 일치하지 않으면 대신 c.tracing.instrument :active_record가 정의한 기본 설정을 사용해요.

Active Support

대부분의 경우 Active Support는 Rails의 일부로 설정되지만, 별도로도 활성화할 수 있어요:

require 'activesupport'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :active_support, **options
end

cache = ActiveSupport::Cache::MemoryStore.new
cache.read('city')

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ACTIVE_SUPPORT_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
cache_service	String	active_support 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	active_support-cache
cache_store	Array	계측할 캐시 저장소를 지정해요. 저장소 이름 목록을 받아요 (예: memory_store, file_store, 또는 :file_store 같은 심볼). 설정하면 나열된 저장소만 추적돼요. 기본값(nil)이면 모든 저장소를 추적해요.	nil

AWS

AWS 통합은 AWS 서비스(S3, ElastiCache 등)와의 모든 상호작용(예: API 호출)을 추적해요.

require 'aws-sdk'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :aws, **options
end

# Perform traced call
Aws::S3::Client.new.list_buckets

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_AWS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_AWS_SERVICE_NAME	String	aws 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	aws
peer_service	DD_TRACE_AWS_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil

Concurrent Ruby

Concurrent Ruby 통합은 ::Concurrent::Future와 Concurrent::Async를 사용할 때 컨텍스트 전파를 지원하고, Future#execute와 Concurrent::Async#async 내부에서 추적된 코드가 올바른 부모를 갖도록 보장해요.

통합을 활성화하려면 Datadog.configure 메서드를 사용해요:

# Inside Rails initializer or equivalent
Datadog.configure do |c|
  # Patches ::Concurrent::Future to use ExecutorService that propagates context
  c.tracing.instrument :concurrent_ruby, **options
end

# Pass context into code executed within Concurrent::Future
Datadog::Tracing.trace('outer') do
  Concurrent::Future.execute { Datadog::Tracing.trace('inner') { } }.wait
end

# Pass context into code executed within Concurrent::Async
class MyClass
  include ConcurrentAsync

  def foo
    Datadog::Tracing.trace('inner') { }
  end
end

Datadog::Tracing.trace('outer') do
  MyClass.new.async.foo
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_CONCURRENT_RUBY_ENABLED	Bool	통합이 컨텍스트를 전파할지 여부예요.	true

Dalli

Dalli 통합은 memcached 서버로의 모든 호출을 추적해요:

require 'dalli'
require 'datadog'

# Configure default Dalli tracing behavior
Datadog.configure do |c|
  c.tracing.instrument :dalli, **options
end

# Configure Dalli tracing behavior for single client
client = Dalli::Client.new('localhost:11211', **options)
client.set('abc', 123)

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_DALLI_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
command_enabled	DD_TRACE_MEMCACHED_COMMAND_ENABLED	Bool	명령을 memcached.command 태그로 수집해요. 명령 key는 잠재적으로 민감한 정보를 포함할 수 있어요.	false
service_name	DD_TRACE_DALLI_SERVICE_NAME	String	dalli 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	memcached
peer_service	DD_TRACE_DALLI_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil

DelayedJob

DelayedJob 통합은 라이프사이클 훅을 사용해 작업 실행과 enqueue를 추적해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :delayed_job, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_DELAYED_JOB_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Elasticsearch

Elasticsearch 통합은 Client 객체에서 perform_request에 대한 모든 호출을 추적해요:

require 'elasticsearch/transport'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :elasticsearch, **options
end

# Perform a query to Elasticsearch
client = Elasticsearch::Client.new url: 'http://127.0.0.1:9200'
response = client.perform_request 'GET', '_cluster/health'

# In case you want to override the global configuration for a certain client instance
Datadog.configure_onto(client.transport, **options)

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ELASTICSEARCH_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_ELASTICSEARCH_SERVICE_NAME	String	elasticsearch 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	elasticsearch
peer_service	DD_TRACE_ELASTICSEARCH_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
quantize	Hash	양자화 옵션을 담은 해시예요. 양자화하지 않을 키의 :show Array(또는 양자화를 건너뛸 :all), 또는 완전히 제외할 키의 :exclude Array를 포함할 수 있어요.	{}
on_error	Proc	요청에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Ethon

ethon 통합은 Easy 또는 Multi 객체를 통한 모든 HTTP 요청을 추적해요. 이 통합은 Ethon 기반의 Typhoeus 라이브러리도 지원해요.

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :ethon, **options

  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :ethon, describes: /user-[^.]+\\.example\\.com/ do |ethon|
    ethon.service_name = 'user.example.com'
    ethon.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_ETHON_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_ETHON_SERVICE_NAME	String	ethon 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	ethon
peer_service	DD_TRACE_ETHON_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_ETHON_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false

Excon

excon 통합은 datadog 미들웨어를 통해 사용할 수 있어요:

require 'excon'
require 'datadog'

# Configure default Excon tracing behavior
Datadog.configure do |c|
  c.tracing.instrument :excon, **options

  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :excon, describes: /user-[^.]+\\.example\\.com/ do |excon|
    excon.service_name = 'user.example.com'
    excon.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

connection = Excon.new('https://example.com')
connection.get

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_EXCON_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_EXCON_SERVICE_NAME	String	excon 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	excon
peer_service	DD_TRACE_EXCON_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_EXCON_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false
on_error	Proc	요청에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요.	`proc {	span, error
error_status_codes	DD_TRACE_EXCON_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...600]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599'), 배열 요소 추가에 쉼표('403,500-599')를 사용해요	400...600

다른 설정을 사용하도록 연결 구성

Excon으로 여러 연결을 사용한다면, 각각의 생성자를 미들웨어로 구성해 서로 다른 설정을 줄 수 있어요:

# Wrap the Datadog tracing middleware around the default middleware stack
Excon.new(
  'http://example.com',
  middlewares: Datadog::Tracing::Contrib::Excon::Middleware.with(options).around_default_stack
)

# Insert the middleware into a custom middleware stack.
# NOTE: Trace middleware must be inserted after ResponseParser!
Excon.new(
  'http://example.com',
  middlewares: [
    Excon::Middleware::ResponseParser,
    Datadog::Tracing::Contrib::Excon::Middleware.with(options),
    Excon::Middleware::Idempotent
  ]
)

여기서 options는 위 표에 있는 매개변수 중 아무거나 담은 Hash예요.

Faraday

faraday 통합은 datadog 미들웨어를 통해 사용할 수 있어요:

require 'faraday'
require 'datadog'

# Configure default Faraday tracing behavior
Datadog.configure do |c|
  c.tracing.instrument :faraday, **options

  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :faraday, describes: /user-[^.]+\\.example\\.com/ do |faraday|
    faraday.service_name = 'user.example.com'
    faraday.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

# In case you want to override the global configuration for a certain client instance
connection = Faraday.new('https://example.com') do |builder|
  builder.use(:datadog_tracing, **options)
  builder.adapter Faraday.default_adapter
end

connection.get('/foo')

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_FARADAY_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_FARADAY_SERVICE_NAME	String	faraday 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	faraday
peer_service	DD_TRACE_FARADAY_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_FARADAY_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false
on_error	Proc	요청에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요.	`proc {	span, error
error_status_codes	DD_TRACE_FARADAY_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...600]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599'), 배열 요소 추가에 쉼표('403,500-599')를 사용해요	400...600

Grape

Grape 통합은 Grape 엔드포인트와 필터에 계측을 추가해요. 이 통합은 Rack, Rails 같은 다른 통합과 나란히 작동할 수 있어요.

통합을 활성화하려면 Grape 애플리케이션을 정의하기 전에 Datadog.configure 메서드를 사용해요:

# api.rb
require 'grape'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :grape, **options
end

# Then define your application
class RackTestingAPI < Grape::API
  desc 'main endpoint'
  get :success do
    'Hello world!'
  end
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_GRAPE_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
error_status_codes	DD_TRACE_GRAPE_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...600]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599'), 배열 요소 추가에 쉼표('403,500-599')를 사용해요	500...600

GraphQL

GraphQL 통합은 GraphQL 쿼리에 대한 계측을 활성화해요.

경고: 자동 계측된 GraphQL 애플리케이션을 온보딩할 때 반드시 환경 변수 DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER=1을 설정해야 해요. 이렇게 하면 엔드포인트 관찰 가능성(Endpoint Observability)이 지원돼요.

Datadog.configure 블록에서는 통합 추적기 옵션을 변경할 수 없어요.

수동으로 통합을 활성화할 땐 Datadog.configure 메서드를 사용해요:

# Inside Rails initializer or equivalent
# For graphql >= v2.2
Datadog.configure do |c|
  c.tracing.instrument :graphql, error_tracking: true, with_unified_tracer: true, **options
end

# For graphql < v2.2
Datadog.configure do |c|
   c.tracing.instrument :graphql, error_tracking: true, **options
end

# Then run a GraphQL query
YourSchema.execute(query, variables: {}, context: {}, operation_name: nil)

instrument :graphql 메서드는 다음 매개변수를 받아들여요. options 자리에 추가 옵션을 넣을 수 있어요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_GRAPHQL_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
schemas	Array	추적할 GraphQL::Schema 객체의 배열이에요(클래스 기반 스키마만 지원해요). 제공하지 않으면 모든 스키마에 추적이 적용돼요.	[]
with_unified_tracer	DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER	Bool	(권장) graphql >= v2.2에서 UnifiedTrace 추적기로 계측하도록 활성화해요. 그러면 엔드포인트 관찰 가능성(Endpoint Observability)이 지원돼요. 자동 계측 애플리케이션이라면 반드시 환경 변수를 사용해야 해요. with_deprecated_tracer가 이것보다 우선해요. 기본값은 false로 GraphQL::Tracing::DataDogTrace를 사용해요. 이 옵션은 하위 호환성을 위해 기본적으로 비활성화되어 있지만, datadog 3.0.0에서는 기본값이 될 거예요.	false
with_deprecated_tracer	Bool	(권장되지 않음) 레거시 GraphQL::Tracing::DataDogTracing으로 계측하도록 활성화해요. with_unified_tracer보다 우선해요. 기본값은 false로 GraphQL::Tracing::DataDogTrace를 사용해요	false
service_name	String	graphql 계측에 사용되는 서비스 이름이에요	'ruby-graphql'
error_extensions	DD_TRACE_GRAPHQL_ERROR_EXTENSIONS	Array	오류가 있는 GraphQL 쿼리에 대해 보고되는 스팬 이벤트에 포함할 extension 키 목록이에요.	[]
error_tracking	DD_TRACE_GRAPHQL_ERROR_TRACKING	Bool	(권장) GraphQL 오류를 Error Tracking에 표시해요.	false

계측 전략을 선택하면(with_unified_tracer: true, with_deprecated_tracer: true, 또는 옵션을 설정하지 않아 기본값인 GraphQL::Tracing::DataDogTrace가 적용된 경우), 계측 전략을 변경할 수 없어요.

GraphQL 스키마 수동 구성

원한다면 스키마별로 추적기 설정을 개별적으로 구성할 수 있어요 (예: 서로 다른 계측 옵션을 가진 여러 스키마).

스키마 설정을 수동으로 구성하기로 했다면 Datadog.configure에서 c.tracing.instrument :graphql을 하지 마세요 — 이중 추적을 피하기 위해서예요. 이 두 가지 GraphQL 추적 구성 방식은 상호 배타적이에요.

각 스키마를 개별적으로 계측하려면 GraphQL API를 사용해 다음을 추가해요:

graphql >= v2.2인 경우:

class YourSchema < GraphQL::Schema
  trace_with Datadog::Tracing::Contrib::GraphQL::UnifiedTrace
end

graphql < v2.2인 경우:

class YourSchema < GraphQL::Schema
  trace_with GraphQL::Tracing::DataDogTrace
end

레거시 추적기 GraphQL(GraphQL::Tracing::DataDogTracing)을 사용하는 경우:

class YourSchema < GraphQL::Schema
  use(GraphQL::Tracing::DataDogTracing)
end

참고: 이 통합은 define-스타일 스키마를 지원하지 않아요. 클래스 기반 스키마만 지원돼요.

Datadog 스팬에 사용자 지정 태그 추가

prepare_span 메서드를 하위 클래스에서 구현한 다음 스키마를 수동으로 구성하면 Datadog 스팬에 사용자 지정 태그를 추가할 수 있어요.

class YourSchema < GraphQL::Schema
  module CustomTracing
    include Datadog::Tracing::Contrib::GraphQL::UnifiedTrace
    def prepare_span(trace_key, data, span)
      span.set_tag("custom:#{trace_key}", data.keys.sort.join(","))
    end
  end

  trace_with CustomTracing
end

gRPC

grpc 통합은 서비스의 원격 프로시저 호출을 실행하기 전에 미들웨어로 작동하는 클라이언트와 서버 인터셉터를 모두 추가해요. gRPC 애플리케이션은 보통 분산되어 있으므로, 이 통합은 클라이언트와 서버 간에 추적 정보를 공유해요.

통합을 설정하려면 Datadog.configure 메서드를 이렇게 사용해요:

require 'grpc'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :grpc, **options
end

# Server side
server = GRPC::RpcServer.new
server.add_http2_port('localhost:50051', :this_port_is_insecure)
server.handle(Demo)
server.run_till_terminated

# Client side
client = Demo.rpc_stub_class.new('localhost:50051', :this_channel_is_insecure)
client.my_endpoint(DemoMessage.new(contents: 'hello!'))

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_GRPC_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_GRPC_SERVICE_NAME	String	grpc 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	grpc
peer_service	DD_TRACE_GRPC_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_GRPC_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
on_error	Proc	오류가 있을 때 호출되는 사용자 지정 오류 처리기예요. span과 error 매개변수를 받는 Proc이에요. 기본적으로 스팬에 오류를 설정해요.	`proc {	span, error

다른 설정을 사용하도록 클라이언트 구성

여러 클라이언트가 여러 고유한 서비스를 호출하는 상황에서는 Datadog 인터셉터를 직접 전달할 수 있어요:

configured_interceptor = Datadog::Tracing::Contrib::GRPC::DatadogInterceptor::Client.new do |c|
  c.service_name = "Alternate"
end

alternate_client = Demo::Echo::Service.rpc_stub_class.new(
  'localhost:50052',
  :this_channel_is_insecure,
  :interceptors => [configured_interceptor]
)

이 통합은 configured_interceptor가 그 클라이언트 인스턴스에 대해 고유한 추적 설정을 수립하도록 보장해요.

hanami

hanami 통합은 hanami 애플리케이션의 라우팅, 액션, 렌더를 계측해요. hanami 계측을 활성화하려면 다음과 같이 자동 계측을 권장해요:

gem 'datadog', require: 'datadog/auto_instrument'

그리고 config/initializers 폴더에 initializer 파일을 만들어요:

# config/initializers/datadog.rb
Datadog.configure do |c|
  c.tracing.instrument :hanami, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_HANAMI_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	String	hanami 계측의 서비스 이름이에요.	nil

http.rb

http.rb 통합은 Http.rb gem을 사용한 모든 HTTP 호출을 추적해요.

require 'http'
require 'datadog'
Datadog.configure do |c|
  c.tracing.instrument :httprb, **options
  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :httprb, describes: /user-[^.]+\\.example\\.com/ do |httprb|
    httprb.service_name = 'user.example.com'
    httprb.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_HTTPRB_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_HTTPRB_SERVICE_NAME	String	httprb 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	httprb
peer_service	DD_TRACE_HTTPRB_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_HTTPRB_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false
error_status_codes	DD_TRACE_HTTPRB_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...**600**]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599'), 배열 요소 추가에 쉼표('403,500-599')를 사용해요	400...600

httpclient

httpclient 통합은 httpclient gem을 사용한 모든 HTTP 호출을 추적해요.

require 'httpclient'
require 'datadog'
Datadog.configure do |c|
  c.tracing.instrument :httpclient, **options
  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :httpclient, describes: /user-[^.]+\\.example\\.com/ do |httpclient|
    httpclient.service_name = 'user.example.com'
    httpclient.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_HTTPCLIENT_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_HTTPCLIENT_SERVICE_NAME	String	httpclient 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	httpclient
peer_service	DD_TRACE_HTTPCLIENT_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_HTTPCLIENT_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false
error_status_codes	DD_TRACE_HTTPCLIENT_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...600]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599')와 배열 요소 추가에 쉼표('403,500-599')를 사용해요	400...600

httpx

httpx는 datadog과의 자체 통합을 유지하고 있어요:

require "datadog"
require "httpx/adapters/datadog"

Datadog.configure do |c|
  c.tracing.instrument :httpx

  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :httpx, describes: /user-[^.]+\\.example\\.com/ do |http|
    http.service_name = 'user.example.com'
    http.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

Kafka

Kafka 통합은 ruby-kafka gem에 대한 추적을 제공해요:

Datadog.configure로 활성화할 수 있어요:

require 'active_support/notifications' # required to enable 'ruby-kafka' instrumentation
require 'kafka'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :kafka, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_KAFKA_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Karafka

karafka 통합은 karafka gem에 대한 추적을 제공해요. Datadog.configure로 활성화할 수 있어요:

require 'karafka'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :karafka, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_KARAFKA_ENABLED	Bool	통합이 스팬을 생성할지 여부를 지정해요.	true
distributed_tracing	DD_TRACE_KARAFKA_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요 (kafka 메시지를 반복할 때 각 메시지의 트레이스가 블록 기간 동안 재개돼요).	false

WaterDrop

WaterDrop 통합은 waterdrop gem(karafka의 의존성이지만 단독으로도 사용할 수 있어요)에 대한 추적을 제공해요.

이 통합은 Karafka 프레임워크와 함께 자동으로 활성화돼요. 애플리케이션이 Karafka를 사용하지 않는다면(예: 다른 앱에서 소비하는 메시지만 생성하는 경우), Datadog.configure로 수동으로 활성화해요:

require 'waterdrop'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :waterdrop, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_WATERDROP_ENABLED	Bool	통합이 스팬을 생성할지 여부를 지정해요.	true
distributed_tracing	DD_TRACE_WATERDROP_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요 (생산된 메시지에 트레이스 컨텍스트가 주입돼요).	false

Kicks

Kicks 통합은 작업 실행을 추적하는 서버 측 미들웨어예요.

경고: Kicks는 Sneakers의 후속작이에요. 두 개는 동일한 Ruby 클래스 네임스페이스를 공유하므로 동시에 활성화할 수 없어요. 기존 Sneakers 설정은 모든 Kicks 설정과 자동으로 병합돼요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :kicks, **options
end

options에 사용할 수 있는 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SNEAKERS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
tag_body	Bool	스팬에 작업 메시지를 태그로 붙일지 여부예요.	false
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

MongoDB

이 통합은 MongoDB Ruby Driver에서 MongoDB 클러스터로 보내진 모든 Command를 추적해요. 따라서 Mongoid 같은 Object Document Mapper(ODM)도 공식 Ruby 드라이버를 사용한다면 자동으로 계측돼요. 통합을 활성화하려면 다음처럼 해요:

require 'mongo'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :mongo, json_command: true, **options
end

# Create a MongoDB client and use it as usual
client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })

# In case you want to override the global configuration for a certain client instance
Datadog.configure_onto(client, **options)

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_MONGO_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_MONGO_SERVICE_NAME	String	mongo 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	mongodb
peer_service	DD_TRACE_MONGO_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
quantize	Hash	양자화 옵션을 담은 해시예요. 양자화하지 않을 키의 :show Array(또는 양자화를 건너뛸 :all), 또는 완전히 제외할 키의 :exclude Array를 포함할 수 있어요.	{ show: [:collection, :database, :operation] }
json_command	DD_TRACE_MONGO_JSON_COMMAND	Bool	(권장) MongoDB 명령을 JSON으로 직렬화해요. 그러면 Datadog 앱에서 인트로스펙션을 완전히 지원할 수 있어요.	false

연결별 트레이스 설정 구성

describes 옵션을 사용해 연결별로 트레이스 설정을 구성할 수 있어요:

# Provide a `:describes` option with a connection key.
# Any of the following keys are acceptable and equivalent to one another.
# If a block is provided, it yields a Settings object that
# accepts any of the configuration options listed above.

Datadog.configure do |c|
  # Network connection string
  c.tracing.instrument :mongo, describes: '127.0.0.1:27017', service_name: 'mongo-primary'

  # Network connection regular expression
  c.tracing.instrument :mongo, describes: /localhost.*/, service_name: 'mongo-secondary'
end

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })
# Traced call will belong to `mongo-primary` service

client = Mongo::Client.new([ 'localhost:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })
# Traced call will belong to `mongo-secondary` service

여러 describes 설정이 연결과 일치하면 마지막으로 설정된 일치 규칙이 적용돼요.

MySQL2

MySQL2 통합은 mysql2 gem을 통해 보내진 모든 SQL 명령을 추적해요.

require 'mysql2'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :mysql2, **options
end

client = Mysql2::Client.new(:host => "localhost", :username => "root")
client.query("SELECT * FROM users WHERE group='x'")

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_MYSQL2_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_MYSQL2_SERVICE_NAME	String	mysql2 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	mysql2
peer_service	DD_TRACE_MYSQL2_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
comment_propagation	DD_DBM_PROPAGATION_MODE	String	데이터베이스 모니터링을 위한 SQL 주석 전파 모드예요 (예: disabled | service| dynamic_service | full).중요: SQL 주석 전파를 활성화하면 잠재적으로 기밀 데이터(서비스 이름)가 데이터베이스에 저장될 수 있으며, 데이터베이스 접근 권한이 부여된 제3자가 접근할 수 있게 돼요.	'disabled'
append_comment	Bool	SQL 주석 전파를 쿼리 문자열에 덧붙여요. false면 앞에 붙여요. 쿼리 문자열이 길면 덧붙여진 전파 주석이 잘릴 수 있어, 쿼리와 트레이스 간 상관 관계가 사라질 수 있어요.	false
on_error	Proc	MySQL에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 애플리케이션 레벨에서 처리되는 오류를 무시하는 데 유용해요.	`proc {	span, error

Net/HTTP

Net/HTTP 통합은 표준 라이브러리 Net::HTTP 모듈을 사용한 모든 HTTP 호출을 추적해요.

require 'net/http'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :http, **options

  # optionally, specify a different service name for hostnames matching a regex
  c.tracing.instrument :http, describes: /user-[^.]+\\.example\\.com/ do |http|
    http.service_name = 'user.example.com'
    http.split_by_domain = false # Only necessary if split_by_domain is true by default
  end
end

Net::HTTP.start('127.0.0.1', 8080) do |http|
  request = Net::HTTP::Get.new '/index'
  response = http.request(request)
end

content = Net::HTTP.get(URI('http://127.0.0.1/index.html'))

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_HTTP_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_NET_HTTP_SERVICE_NAME	String	net/http 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	net/http
peer_service	DD_TRACE_NET_HTTP_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_HTTP_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false
error_status_codes	DD_TRACE_HTTP_ERROR_STATUS_CODES	Array|Range	오류로 추적할 HTTP 상태 코드를 정의해요. 값은 범위(400...600) 또는 범위/정수 배열 [403, 500...600]이 될 수 있어요. 환경 변수로 설정할 땐 범위에 대시('400-599'), 배열 요소 추가에 쉼표('403,500-599')를 사용해요	400...600

각 연결 객체를 개별적으로 구성하고 싶다면 Datadog.configure_onto를 이렇게 사용할 수 있어요:

client = Net::HTTP.new(host, port)
Datadog.configure_onto(client, **options)

OpenSearch

OpenSearch 통합은 Client 객체에서 perform_request에 대한 모든 호출을 추적해요:

require 'opensearch'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :opensearch, **options
end

# Perform a query to OpenSearch
client = OpenSearch::Client.new(
  host: 'https://localhost:9200',
  user: 'user',
  password: 'password',
)
client.cluster.health

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_OPENSEARCH_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_OPENSEARCH_SERVICE_NAME	String	opensearch 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요.	opensearch
peer_service	DD_TRACE_OPENSEARCH_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요.	nil
resource_pattern	DD_TRACE_OPENSEARCH_RESOURCE_PATTERN	String	리소스 이름을 전체 또는 상대 URL 경로로 설정할지에 따라 absolute 또는 relative예요.	absolute
quantize	Hash	양자화 옵션을 담은 해시예요. 양자화하지 않을 키의 :show Array, 양자화를 건너뛸 :all, 또는 완전히 제외할 키의 :exclude Array를 포함할 수 있어요.	{}

Postgres

PG 통합은 pg gem을 통해 보내진 SQL 명령을 다음과 같이 추적해요:

• exec, exec_params, exec_prepared;
• async_exec, async_exec_params, async_exec_prepared; 또는,
• sync_exec, sync_exec_params, sync_exec_prepared

require 'pg'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :pg, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_PG_ENABLED	true	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_PG_SERVICE_NAME	String	pg 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	pg
peer_service	DD_TRACE_PG_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
comment_propagation	DD_DBM_PROPAGATION_MODE	String	데이터베이스 모니터링을 위한 SQL 주석 전파 모드예요 (예: disabled | service| dynamic_service | full).중요: SQL 주석 전파를 활성화하면 잠재적으로 기밀 데이터(서비스 이름)가 데이터베이스에 저장될 수 있으며, 데이터베이스 접근 권한이 부여된 제3자가 접근할 수 있게 돼요.	'disabled'
append_comment	Bool	SQL 주석 전파를 쿼리 문자열에 덧붙여요. false면 앞에 붙여요. 쿼리 문자열이 길면 덧붙여진 전파 주석이 잘릴 수 있어, 쿼리와 트레이스 간 상관 관계가 사라질 수 있어요.	false
on_error	Proc	PG에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 애플리케이션 레벨에서 처리되는 Postgres 오류를 무시하는 데 유용해요.	`proc {	span, error

Presto

Presto 통합은 presto-client gem을 통해 보내진 모든 SQL 명령을 추적해요.

require 'presto-client'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :presto, **options
end

client = Presto::Client.new(
  server: "localhost:8880",
  ssl: {verify: false},
  catalog: "native",
  schema: "default",
  time_zone: "US/Pacific",
  language: "English",
  http_debug: true,
)

client.run("select * from system.nodes")

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_PRESTO_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_PRESTO_SERVICE_NAME	String	presto 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	presto
peer_service	DD_TRACE_PRESTO_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil

Que

Que 통합은 작업 실행을 추적하는 미들웨어예요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :que, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_QUE_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
distributed_tracing	DD_TRACE_QUE_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
tag_args	DD_TRACE_QUE_TAG_ARGS_ENABLED	Bool	작업의 args 필드 태깅을 활성화해요. true면 켜고 false면 꺼요.	false
tag_data	DD_TRACE_QUE_TAG_DATA_ENABLED	Bool	작업의 data 필드 태깅을 활성화해요. true면 켜고 false면 꺼요.	false
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Racecar

Racecar 통합은 Racecar 작업에 대한 추적을 제공해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :racecar, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RACECAR_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_RACECAR_SERVICE_NAME	String	racecar 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	racecar

Rack

Rack 통합은 요청이 기반 프레임워크나 애플리케이션에 도달하기 전에 모든 요청을 추적하는 미들웨어를 제공해요. Rack 최소 인터페이스에 응답하며, Rack 레벨에서 검색할 수 있는 합리적인 값을 제공해요.

이 통합은 Rails 같은 웹 프레임워크와 함께 자동으로 활성화돼요. 일반 Rack 애플리케이션을 사용한다면 config.ru에서 통합을 활성화해요:

# config.ru example
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :rack, **options
end

use Datadog::Tracing::Contrib::Rack::TraceMiddleware

app = proc do |env|
  [ 200, {'Content-Type' => 'text/plain'}, ['OK'] ]
end

run app

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RACK_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
application	Rack Application	Rack 애플리케이션이에요. middleware_names에 필요해요.	nil
distributed_tracing	DD_TRACE_RACK_DISTRIBUTED_TRACING	Bool	추적 헤더를 받으면 이 서비스 트레이스가 다른 서비스의 트레이스와 연결되도록 분산 추적을 활성화해요	true
headers	Hash	rack.request에 태그로 추가할 HTTP 요청 또는 응답 헤더의 해시예요. Array 값을 가진 request와 response 키를 받아요 (예: ['Last-Modified']). 각각 http.request.headers.*와 http.response.headers.* 태그를 추가해요. 이 옵션은 전역 DD_TRACE_HEADER_TAGS를 덮어써요. 자세한 내용은 루트 스팬에 헤더 태그 적용을 참고해요.	{ response: ['Content-Type', 'X-Request-ID'] }
middleware_names	Bool	rack 스팬의 리소스 이름으로 마지막으로 실행된 미들웨어 클래스를 사용하고 싶으면 이 기능을 활성화해요. rails 계측과 함께 활성화하면, 해당될 때 rack 리소스 이름이 활성 rails 컨트롤러로 설정되어 rails가 우선해요. application 옵션이 필요해요.	false
quantize	Hash	양자화 옵션을 담은 해시예요. :query 또는 :fragment를 포함할 수 있어요.	{}
quantize.base	URL 기본부(scheme, host, port)의 동작을 정의해요. http.url 태그에 URL 기본부를 유지하고 http.base_url 태그를 설정하지 않는 :show이거나, 기본적으로 http.url 태그에서 URL 기본부를 제거하고 경로만 남기며 http.base_url을 설정하는 nil일 수 있어요. 옵션은 quantize 옵션 안에 중첩해야 해요.	nil
quantize.query	URL 양자화의 쿼리 부분에 대한 옵션을 담은 해시예요. :show 또는 :exclude를 포함할 수 있어요. 아래 옵션을 참고해요. 옵션은 quantize 옵션 안에 중첩해야 해요.	{}
quantize.query.show	항상 표시해야 하는 값을 정의해요. 문자열의 Array, 모든 값을 표시할 :all, 또는 값을 표시하지 않을 nil일 수 있어요. 옵션은 query 옵션 안에 중첩해야 해요.	nil
quantize.query.exclude	완전히 제거해야 하는 값을 정의해요. 문자열의 Array, 쿼리 문자열을 완전히 제거할 :all, 또는 아무것도 제외하지 않을 nil일 수 있어요. 옵션은 query 옵션 안에 중첩해야 해요.	nil
quantize.query.obfuscate	쿼리 문자열 수정(redaction) 동작을 정의해요. 옵션의 해시, 기본 내부 난독화 설정을 사용할 :internal, 또는 난독화를 비활성화할 nil일 수 있어요. 난독화는 키-값 연산이 아니라 문자열 단위 연산이라는 점에 유의해요. 활성화되면 query.show는 설정하지 않았다면 기본적으로 :all이 돼요. 옵션은 query 옵션 안에 중첩해야 해요.	nil
quantize.query.obfuscate.with	난독화된 일치 항목을 대체할 문자열을 정의해요. String일 수 있어요. 옵션은 query.obfuscate 옵션 안에 중첩해야 해요.	'<redacted>'
quantize.query.obfuscate.regex	쿼리 문자열을 수정할 정규식을 정의해요. Regexp이거나, 잘 알려진 민감 데이터를 수정하는 기본 내부 Regexp를 사용할 :internal일 수 있어요. 각 일치 항목은 query.obfuscate.with로 대체되어 완전히 수정돼요. 옵션은 query.obfuscate 옵션 안에 중첩해야 해요.	:internal
quantize.fragment	URL 프래그먼트의 동작을 정의해요. URL 프래그먼트를 표시할 :show이거나 프래그먼트를 제거할 nil일 수 있어요. 옵션은 quantize 옵션 안에 중첩해야 해요.	nil
request_queuing	Bool	프론트엔드 서버의 대기열에서 보낸 HTTP 요청 시간을 추적해요. 설정 방법은 HTTP 요청 대기열 처리를 참고해요.	false
web_service_name	String	프론트엔드 서버 요청 대기열 스팬의 서비스 이름이에요 (예: 'nginx')	'web-server'

폐기 예정 공지:

• quantize.base의 기본값은 향후 버전에서 :exclude에서 :show로 바뀔 거예요. 자발적으로 :show로 옮기는 걸 권장해요.
• quantize.query.show의 기본값은 향후 버전에서 :all로 바뀌고, quantize.query.obfuscate는 :internal로 바뀔 거예요. 자발적으로 이 미래 값들로 옮기는 걸 권장해요.

URL 양자화 동작 구성

Datadog.configure do |c|
  # Default behavior: all values are quantized, base is removed, fragment is removed.
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id&sort_by
  # http://example.com:8080/path?categories[]=1&categories[]=2 --> /path?categories[]

  # Remove URL base (scheme, host, port)
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id&sort_by#featured
  c.tracing.instrument :rack, quantize: { base: :exclude }

  # Show URL base
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id&sort_by#featured
  c.tracing.instrument :rack, quantize: { base: :show }

  # Show values for any query string parameter matching 'category_id' exactly
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id=1&sort_by
  c.tracing.instrument :rack, quantize: { query: { show: ['category_id'] } }

  # Show all values for all query string parameters
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id=1&sort_by=asc
  c.tracing.instrument :rack, quantize: { query: { show: :all } }

  # Totally exclude any query string parameter matching 'sort_by' exactly
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id
  c.tracing.instrument :rack, quantize: { query: { exclude: ['sort_by'] } }

  # Remove the query string entirely
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path
  c.tracing.instrument :rack, quantize: { query: { exclude: :all } }

  # Show URL fragments
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?category_id&sort_by#featured
  c.tracing.instrument :rack, quantize: { fragment: :show }

  # Obfuscate query string, defaulting to showing all values
  # http://example.com/path?password=qwerty&sort_by=asc#featured --> /path?<redacted>&sort_by=asc
  c.tracing.instrument :rack, quantize: { query: { obfuscate: {} } }

  # Obfuscate query string using the provided regex, defaulting to showing all values
  # http://example.com/path?category_id=1&sort_by=asc#featured --> /path?<redacted>&sort_by=asc
  c.tracing.instrument :rack, quantize: { query: { obfuscate: { regex: /category_id=\\d+/ } } }

  # Obfuscate query string using a custom redaction string
  # http://example.com/path?password=qwerty&sort_by=asc#featured --> /path?REMOVED&sort_by=asc
  c.tracing.instrument :rack, quantize: { query: { obfuscate: { with: 'REMOVED' } } }
end

Rails

Rails 통합은 요청, 데이터베이스 호출, 템플릿 렌더링, 캐시 읽기/쓰기/삭제 작업을 추적해요. 이 통합은 Active Support 계측을 활용해 Notification API를 수신하므로, API로 계측된 모든 작업이 추적돼요.

Rails 계측을 활성화하려면 Rails 자동 계측 지침을 사용해요.

자동 계측 타이밍 참고: Gemfile에서 require 'datadog/auto_instrument'을 사용하면 config/initializers/*.rb 파일이 로드되기 전에 계측이 적용돼요. tracing.contrib.global_default_service_name.enabled 같은 일부 설정 옵션은 initializer가 아닌 환경 변수로 설정해야 해요. 자세한 내용은 자동 계측을 사용한 설정 타이밍을 참고해요.

또는 config/initializers 폴더에 initializer 파일을 만들 수도 있어요:

# config/initializers/datadog.rb
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :rails, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RAILS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
distributed_tracing	DD_TRACE_RAILS_DISTRIBUTED_TRACING	Bool	추적 헤더를 받으면 이 서비스 트레이스가 다른 서비스의 트레이스와 연결되도록 분산 추적을 활성화해요	true
request_queuing	Bool	프론트엔드 서버의 대기열에서 보낸 HTTP 요청 시간을 추적해요. 설정 방법은 HTTP 요청 대기열 처리를 참고해요.	false
middleware	Bool	Rails 애플리케이션에 트레이스 미들웨어를 추가해요. 미들웨어를 로드하고 싶지 않으면 false로 설정해요.	true
middleware_names	Bool	단락된 미들웨어 요청이 트레이스의 리소스로 미들웨어 이름을 표시하도록 활성화해요.	false
service_name	String	애플리케이션 요청을 추적할 때 사용되는 서비스 이름 (on the rack level)	'<app_name>' (Rails 애플리케이션 네임스페이스에서 추론)
template_base_path	String	템플릿 이름을 파싱할 때 사용돼요. 템플릿을 views/ 폴더에 저장하지 않는다면 이 값을 변경해야 할 수도 있어요	'views/'

지원 버전

MRI Versions	Rails Versions
2.5	4.2 - 6.1
2.6 - 2.7	5.0 - 6.1
3.0 - 3.1	6.1 - 7.1
3.2 - 4.0	6.1 - 8.1

Rails Runner 명령의 계측은 Rails 5.1 이상에서만 지원돼요.

Rake

rake 통합을 활성화하고 계측할 Rake 작업의 목록을 제공하면 Rake 작업 주변에 계측을 추가할 수 있어요.

오래 실행되는 Rake 작업은 계측하지 마세요. 그런 작업은 작업이 끝날 때까지 플러시되지 않는 큰 트레이스를 메모리에 축적할 수 있어요.

오래 실행되는 작업에는 반복 코드 경로 주변에 수동 계측을 사용해요.

Rake 작업 추적을 활성화하려면 Rakefile에 다음을 추가해요:

# At the top of your Rakefile:
require 'rake'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :rake, tasks: ['my_task'], **options
end

task :my_task do
  # Do something task work here...
end

Rake::Task['my_task'].invoke

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RAKE_ENABLED	Bool	Rake 작업을 추적할지 여부를 정의해요. 추적을 일시적으로 비활성화하는 데 유용해요. true 또는 false	true
quantize	Hash	작업 인자의 양자화 옵션을 담은 해시예요. 자세한 내용과 예시는 아래를 참고해요.	{}
service_name	String	rake 계측에 사용되는 서비스 이름	'rake'
tasks	Array	계측할 Rake 작업의 이름	[]

작업 양자화 동작 구성

Datadog.configure do |c|
  # Given a task that accepts :one, :two, :three...
  # Invoked with 'foo', 'bar', 'baz'.

  # Default behavior: all arguments are quantized.
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: '?', three: '?' }
  c.tracing.instrument :rake

  # Show values for any argument matching :two exactly
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: 'bar', three: '?' }
  c.tracing.instrument :rake, quantize: { args: { show: [:two] } }

  # Show all values for all arguments.
  # `rake.invoke.args` tag  --> ['foo', 'bar', 'baz']
  # `rake.execute.args` tag --> { one: 'foo', two: 'bar', three: 'baz' }
  c.tracing.instrument :rake, quantize: { args: { show: :all } }

  # Totally exclude any argument matching :three exactly
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: '?' }
  c.tracing.instrument :rake, quantize: { args: { exclude: [:three] } }

  # Remove the arguments entirely
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> {}
  c.tracing.instrument :rake, quantize: { args: { exclude: :all } }
end

Redis

Redis 통합은 단순 호출과 파이프라인을 모두 추적해요.

require 'redis'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :redis, **options
end

# Perform Redis commands
redis = Redis.new
redis.set 'foo', 'bar'

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_REDIS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_REDIS_SERVICE_NAME	String	redis 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. Rails 자동 계측을 사용할 땐 환경 변수로 설정하거나 initializer에서 명시적으로 설정해요. 자세한 내용은 추가 설정을 참고해요	redis
peer_service	DD_TRACE_REDIS_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
command_args	DD_REDIS_COMMAND_ARGS	Bool	명령 인자를(예: GET key의 key) 리소스 이름과 태그로 표시해요. false면 명령 이름만 표시돼요 (예: GET).	false

인스턴스별 트레이스 설정 구성

Redis 버전 >= 5인 경우:

require 'redis'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :redis # Enabling integration instrumentation is still required
end

customer_cache = Redis.new(custom: { datadog: { service_name: 'custom-cache' } })
invoice_cache = Redis.new(custom: { datadog: { service_name: 'invoice-cache' } })

# Traced call will belong to `customer-cache` service
customer_cache.get(...)
# Traced call will belong to `invoice-cache` service
invoice_cache.get(...)

독립형 RedisClient인 경우:

require "redis-client"
require "datadog"

redis = RedisClient.config(custom: { datadog: { service_name: "my-custom-redis" } }).new_client

Datadog.configure do |c|
  c.tracing.instrument :redis # Enabling integration instrumentation is still required
end

redis.call('PING')

Redis 버전 < 5인 경우:

require 'redis'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :redis # Enabling integration instrumentation is still required
end

customer_cache = Redis.new
invoice_cache = Redis.new

Datadog.configure_onto(customer_cache, service_name: 'customer-cache')
Datadog.configure_onto(invoice_cache, service_name: 'invoice-cache')

# Traced call will belong to `customer-cache` service
customer_cache.get(...)
# Traced call will belong to `invoice-cache` service
invoice_cache.get(...)

연결별 트레이스 설정 구성

describes 옵션을 사용해 연결별로 트레이스 설정을 구성할 수 있어요:

# Provide a `:describes` option with a connection key.
# Any of the following keys are acceptable and equivalent to one another.
# If a block is provided, it yields a Settings object that
# accepts any of the configuration options listed above.

Datadog.configure do |c|
  # The default configuration for any redis client
  c.tracing.instrument :redis, service_name: 'redis-default'

  # The configuration matching a given unix socket.
  c.tracing.instrument :redis, describes: { url: 'unix://path/to/file' }, service_name: 'redis-unix'

  # For network connections, only these fields are considered during matching:
  # scheme, host, port, db
  # Other fields are ignored.

  # Network connection string
  c.tracing.instrument :redis, describes: 'redis://127.0.0.1:6379/0', service_name: 'redis-connection-string'
  c.tracing.instrument :redis, describes: { url: 'redis://127.0.0.1:6379/1' }, service_name: 'redis-connection-url'
  # Network client hash
  c.tracing.instrument :redis, describes: { host: 'my-host.com', port: 6379, db: 1, scheme: 'redis' }, service_name: 'redis-connection-hash'
  # Only a subset of the connection hash
  c.tracing.instrument :redis, describes: { host: ENV['APP_CACHE_HOST'], port: ENV['APP_CACHE_PORT'] }, service_name: 'redis-cache'
  c.tracing.instrument :redis, describes: { host: ENV['SIDEKIQ_CACHE_HOST'] }, service_name: 'redis-sidekiq'
end

여러 describes 설정이 연결과 일치하면 마지막으로 설정된 일치 규칙이 적용돼요.

Resque

Resque 통합은 perform 메서드를 감싸는 Resque 훅을 사용해요.

Resque 작업에 추적을 추가하려면:

require 'resque'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :resque, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RESQUE_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Rest Client

rest-client 통합은 datadog 미들웨어를 통해 사용할 수 있어요:

require 'rest_client'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :rest_client, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_REST_CLIENT_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_REST_CLIENT_SERVICE_NAME	String	rest_client 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	rest_client
peer_service	DD_TRACE_REST_CLIENT_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
distributed_tracing	DD_TRACE_REST_CLIENT_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화해요	true
split_by_domain	Bool	true로 설정하면 요청 도메인을 서비스 이름으로 사용해요.	false

Roda

Roda 통합은 요청을 추적해요.

Roda 통합은 Datadog.configure로 활성화할 수 있어요. 분산 추적을 위해 이 통합을 use Datadog::Tracing::Contrib::Rack::TraceMiddleware를 통해 Rack과 함께 사용하는 걸 권장해요.

require "roda"
require "datadog"

class SampleApp < Roda
  use Datadog::Tracing::Contrib::Rack::TraceMiddleware

  Datadog.configure do |c|
    c.tracing.instrument :roda, **options
  end

  route do |r|
    r.root do
      r.get do
        'Hello World!'
      end
    end
  end
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_RODA_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	String	roda 계측의 서비스 이름이에요.	nil

Sequel

Sequel 통합은 데이터베이스에 보낸 쿼리를 추적해요.

require 'sequel'
require 'datadog'

# Connect to database
database = Sequel.sqlite

# Create a table
database.create_table :articles do
  primary_key :id
  String :name
end

Datadog.configure do |c|
  c.tracing.instrument :sequel, **options
end

# Perform a query
articles = database[:articles]
articles.all

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SEQUEL_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	String	sequel 계측의 서비스 이름	데이터베이스 어댑터 이름 (예: 'mysql2')

다른 설정을 사용하도록 데이터베이스 구성

Sequel로 여러 데이터베이스를 사용한다면 각각의 Sequel::Database 객체를 구성해 서로 다른 설정을 줄 수 있어요:

sqlite_database = Sequel.sqlite
postgres_database = Sequel.connect('postgres://user:***@host:port/database_name')

# Configure each database with different service names
Datadog.configure_onto(sqlite_database, service_name: 'my-sqlite-db')
Datadog.configure_onto(postgres_database, service_name: 'my-postgres-db')

Shoryuken

Shoryuken 통합은 작업 실행을 추적하는 서버 측 미들웨어예요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :shoryuken, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SHORYUKEN_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
tag_body	Bool	SQS 메시지 본문으로 스팬을 태그해요 true 또는 false	false
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Sidekiq

Sidekiq 통합은 클라이언트 측 및 서버 측 미들웨어로, 각각 작업 큐잉과 실행을 추적해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :sidekiq, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SIDEKIQ_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
distributed_tracing	DD_TRACE_SIDEKIQ_DISTRIBUTED_TRACING	Bool	분산 추적을 활성화하면 sidekiq.push 스팬과 sidekiq.job 스팬 사이에 부모-자식 관계가 생겨요.중요: 비동기 처리에 대해 분산 추적을 활성화하면 트레이스 그래프가 크게 바뀔 수 있어요. 오래 실행되는 작업, 재시도된 작업, 먼 미래에 예약된 작업이 여기에 포함돼요. 이 기능을 활성화한 뒤 트레이스를 반드시 확인하세요.	false
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error
quantize	Hash	작업 인자의 양자화 옵션을 담은 해시예요.	{}

Sinatra

Sinatra 통합은 요청과 템플릿 렌더링을 추적해요.

추적 클라이언트를 사용하려면 sinatra 또는 sinatra/base 다음에, 애플리케이션/라우트를 정의하기 전에 datadog을 import하고 instrument :sinatra를 해야 해요:

클래식 애플리케이션 (Classic application)

require 'sinatra'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :sinatra, **options
end

get '/' do
  'Hello world!'
end

모듈형 애플리케이션 (Modular application)

require 'sinatra/base'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :sinatra, **options
end

class NestedApp < Sinatra::Base
  get '/nested' do
    'Hello from nested app!'
  end
end

class App < Sinatra::Base
  use NestedApp

  get '/' do
    'Hello world!'
  end
end

계측 옵션 (Instrumentation options)

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SINATRA_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
distributed_tracing	DD_TRACE_SINATRA_DISTRIBUTED_TRACING	Bool	추적 헤더를 받으면 이 서비스 트레이스가 다른 서비스의 트레이스와 연결되도록 분산 추적을 활성화해요	true
headers	Hash	sinatra.request에 태그로 추가할 HTTP 요청 또는 응답 헤더의 해시예요. Array 값을 가진 request와 response 키를 받아요 (예: ['Last-Modified']). 각각 http.request.headers.*와 http.response.headers.* 태그를 추가해요. 이 옵션은 전역 DD_TRACE_HEADER_TAGS를 덮어써요. 자세한 내용은 루트 스팬에 헤더 태그 적용을 참고해요.	{ response: ['Content-Type', 'X-Request-ID'] }
resource_script_names	Bool	리소스 이름 앞에 스크립트 이름을 붙여요	false

Sneakers

Sneakers 통합은 작업 실행을 추적하는 서버 측 미들웨어예요.

경고: Kicks는 Sneakers의 후속작이에요. 두 개는 동일한 Ruby 클래스 네임스페이스를 공유하므로 동시에 활성화할 수 없어요. 기존 Sneakers 설정은 모든 Kicks 설정과 자동으로 병합돼요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :sneakers, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SNEAKERS_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
tag_body	Bool	작업 메시지 태깅을 활성화해요. true면 켜고 false면 꺼요.	false
on_error	Proc	작업에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 일시적인 오류를 무시하는 데 유용해요.	`proc {	span, error

Stripe

Stripe 통합은 Stripe API 요청을 추적해요.

Datadog.configure로 활성화할 수 있어요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :stripe, **options
end

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_STRIPE_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Sucker Punch

sucker_punch 통합은 모든 예약된 작업을 추적해요:

require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :sucker_punch, **options
end

# Execution of this job is traced
LogJob.perform_async('login')

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_SUCKER_PUNCH_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true

Trilogy

trilogy 통합은 trilogy gem을 통해 보내진 모든 SQL 명령을 추적해요.

require 'trilogy'
require 'datadog'

Datadog.configure do |c|
  c.tracing.instrument :trilogy, **options
end

client = Trilogy.new(host: "localhost", username: "root")
client.query("SELECT * FROM users WHERE group='x'")

options는 다음 키워드 인자예요:

Key	Env Var	Type	Description	Default
enabled	DD_TRACE_TRILOGY_ENABLED	Bool	통합이 스팬을 생성할지 여부예요.	true
service_name	DD_TRACE_TRILOGY_SERVICE_NAME	String	trilogy 계측을 실행하는 애플리케이션의 이름이에요. global_default_service_name으로 덮어쓸 수 있어요. 자세한 내용은 추가 설정을 참고해요	trilogy
peer_service	DD_TRACE_TRILOGY_PEER_SERVICE	String	애플리케이션이 연결하는 외부 서비스의 이름이에요	nil
comment_propagation	DD_DBM_PROPAGATION_MODE	String	데이터베이스 모니터링을 위한 SQL 주석 전파 모드예요 (예: disabled | service| dynamic_service | full).중요: SQL 주석 전파를 활성화하면 잠재적으로 기밀 데이터(서비스 이름)가 데이터베이스에 저장될 수 있으며, 데이터베이스 접근 권한이 부여된 제3자가 접근할 수 있게 돼요.	'disabled'
append_comment	Bool	SQL 주석 전파를 쿼리 문자열에 덧붙여요. false면 앞에 붙여요. 쿼리 문자열이 길면 덧붙여진 전파 주석이 잘릴 수 있어, 쿼리와 트레이스 간 상관 관계가 사라질 수 있어요.	false
on_error	Proc	MySQL에서 오류가 발생했을 때 호출되는 사용자 지정 오류 처리기예요. span과 error를 인자로 받아요. 기본적으로 스팬에 오류를 설정해요. 애플리케이션 레벨에서 처리되는 오류를 무시하는 데 유용해요.	`proc {	span, error

추가 설정 (Additional configuration)

datadog의 기본 동작을 변경하려면 우선순위에 따라(1이 가장 높음) 다음을 사용할 수 있어요:

1. Remote Configuration.

참고: 기본적으로 Remote Configuration은 활성화되어 있어요. 비활성화하려면 DD_REMOTE_CONFIGURATION_ENABLED=false를 설정하거나 Datadog.configure { |c| c.remote.enabled = false }를 사용해요.

1. Datadog.configure 블록 안에 설정된 옵션 (예):

   Datadog.configure do |c|
     c.service = 'billing-api'
     c.env = ENV['RACK_ENV']
   
     c.tracing.report_hostname = true
   end
   

2. 환경 변수.

어떤 옵션에 대해 더 높은 우선순위 값이 설정되면, 더 낮은 우선순위로 그 옵션을 설정해도 유효 값이 바뀌지 않아요.

예를 들어 tracing.sampling.default_rate가 Remote Configuration으로 구성되면, Datadog.configure 블록을 통해 값을 변경해도 효과가 없어요.

사용 가능한 설정 옵션 (Available configuration options)

Setting	Env Var	Type	Default	Description
Global (전역)
agent.host	DD_AGENT_HOST	String	127.0.0.1	트레이스 데이터를 보낼 Agent의 호스트 이름이에요.
agent.port	DD_TRACE_AGENT_PORT	Integer	8126	트레이스 데이터를 보낼 Agent 호스트의 포트예요. Agent 설정이 receiver_port 또는 DD_APM_RECEIVER_PORT를 기본값 8126이 아닌 다른 값으로 설정한다면, DD_TRACE_AGENT_PORT 또는 DD_TRACE_AGENT_URL도 그에 맞춰야 해요.
DD_TRACE_AGENT_URL	nil	트레이스를 보낼 URL 엔드포인트를 설정해요. agent.host와 agent.port보다 우선해요. Agent 설정이 receiver_port 또는 DD_APM_RECEIVER_PORT를 기본값 8126이 아닌 다른 값으로 설정한다면, DD_TRACE_AGENT_PORT 또는 DD_TRACE_AGENT_URL도 그에 맞춰야 해요.
diagnostics.debug	DD_TRACE_DEBUG	Bool	false	디버그 모드를 활성화하거나 비활성화해요. 상세한 로그를 출력해요. 프로덕션 또는 기타 민감한 환경에는 권장하지 않아요. 자세한 내용은 디버깅 및 진단을 참고해요.
diagnostics.startup_logs.enabled	DD_TRACE_STARTUP_LOGS	Bool	nil	로그에 시작 설정과 진단 정보를 출력해요. 애플리케이션 시작 시 추적 상태를 평가하는 데 사용해요. 자세한 내용은 디버깅 및 진단을 참고해요.
env	DD_ENV	String	nil	애플리케이션 환경이에요 (예: production, staging 등). 이 값은 모든 트레이스에 태그로 설정돼요.
service	DD_SERVICE	String	Ruby 파일 이름	애플리케이션의 기본 서비스 이름이에요 (예: billing-api). 이 값은 모든 트레이스에 태그로 설정돼요.
tags	DD_TAGS	Hash	nil	,로 구분된 값 쌍의 사용자 지정 태그예요 (예: layer:api,team:intake). 이 태그는 모든 트레이스에 설정돼요. 자세한 내용은 환경 및 태그를 참고해요.
version	DD_VERSION	String	nil	애플리케이션 버전이에요 (예: 2.5, 202003181415, 1.3-alpha 등). 이 값은 모든 트레이스에 태그로 설정돼요.
telemetry.enabled	DD_INSTRUMENTATION_TELEMETRY_ENABLED	Bool	true	Datadog로 텔레메트리 데이터를 보낼 수 있게 해줘요. 여기에 문서화된 대로 비활성화할 수 있어요.
Tracing (추적)
tracing.contrib.peer_service_mapping	DD_TRACE_PEER_SERVICE_MAPPING	Hash	nil	모든 계측에서 peer.service 태그의 재매핑을 정의해요. old_value1:new_value1, old_value2:new_value2, ... 목록을 제공해요.
tracing.contrib.global_default_service_name.enabled	DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED	Bool	false	모든 계측에서 service_name의 기본값을 애플리케이션 서비스 이름으로 변경해요. 자동 계측(require 'datadog/auto_instrument')을 사용하는 Rails 애플리케이션의 경우, 이 값은 config/initializers/datadog.rb가 아닌 환경 변수로 설정해야 해요. 자세한 내용은 자동 계측을 사용한 설정 타이밍을 참고해요.
tracing.propagation_extract_first	DD_TRACE_PROPAGATION_EXTRACT_FIRST	Bool	false	유효한 첫 번째 전파 형식을 감지한 후 검색을 중지해요. 자세한 내용은 분산 추적을 참고해요.
tracing.propagation_style_extract	DD_TRACE_PROPAGATION_STYLE_EXTRACT	Array	['Datadog','tracecontext']	추출할 분산 추적 전파 형식이에요. DD_TRACE_PROPAGATION_STYLE을 덮어써요. 자세한 내용은 분산 추적을 참고해요.
tracing.propagation_style_inject	DD_TRACE_PROPAGATION_STYLE_INJECT	Array	['Datadog','tracecontext']	주입할 분산 추적 전파 형식이에요. DD_TRACE_PROPAGATION_STYLE을 덮어써요. 자세한 내용은 분산 추적을 참고해요.
tracing.propagation_style	DD_TRACE_PROPAGATION_STYLE	Array	nil	추출하고 주입할 분산 추적 전파 형식이에요. 자세한 내용은 분산 추적을 참고해요.
tracing.enabled	DD_TRACE_ENABLED	Bool	true	추적을 활성화하거나 비활성화해요. false로 설정하면 계측은 여전히 실행되지만 트레이스가 트레이스 Agent로 보내지지 않아요.
tracing.header_tags	DD_TRACE_HEADER_TAGS	Array	nil	HTTP 헤더를 스팬 태그로 기록해요. 자세한 내용은 루트 스팬에 헤더 태그 적용을 참고해요.
tracing.instrument(<integration-name>, <options...>)	특정 라이브러리에 대한 계측을 활성화해요. 자세한 내용은 통합 계측을 참고해요.
tracing.log_injection	DD_LOGS_INJECTION	Bool	true	Rails 로그에 Trace Correlation 정보를 주입해요(있을 때). 기본 로거(ActiveSupport::TaggedLogging), lograge, semantic_logger를 지원해요.
tracing.native_span_events	DD_TRACE_NATIVE_SPAN_EVENTS	Bool	false	Agent가 지원하는지 여부와 관계없이 추적기가 항상 네이티브 스팬 이벤트 형식으로 스팬 이벤트를 보내도록 강제해요. Agent가 없는 설정에서 직렬화 형식을 바꾸고 싶을 때 유용해요.
tracing.partial_flush.enabled	Bool	false	부분 플러시를 활성화하거나 비활성화해요. 부분 플러시는 트레이스의 완료된 부분을 Agent에 제출해요. 많은 스팬을 가진 오래 실행되는 작업(예: 작업)을 계측할 때 사용해요.
tracing.partial_flush.min_spans_threshold	Integer	500	부분 플러시가 완료된 스팬을 제출하기 전에 트레이스에서 완료되어야 하는 스팬 수예요.
tracing.sampler	Datadog::Tracing::Sampling::Sampler	nil	고급 사용 전용이에요. 사용자 지정 Datadog::Tracing::Sampling::Sampler 인스턴스를 설정해요. 제공하면 추적기가 이 샘플러를 사용해 샘플링 동작을 결정해요. 자세한 내용은 사용자 지정 샘플링을 참고해요.
tracing.sampling.default_rate	DD_TRACE_SAMPLE_RATE	Float	nil	트레이스 샘플링 비율을 0.0(0%)에서 1.0(100%) 사이로 설정해요.
tracing.sampling.rate_limit	DD_TRACE_RATE_LIMIT	Integer	100 (초당)	초당 샘플링할 트레이스의 최대 수를 설정해요. 트래픽 급증 시 수집량 초과를 피하려면 rate limit을 설정해요.
tracing.sampling.rules	DD_TRACE_SAMPLING_RULES	String	nil	로컬 루트 스팬에 대해 일치하는 트레이스 레벨 샘플링 규칙을 설정해요. 형식은 객체 배열이 포함된 JSON String이에요. 각 객체는 float 속성 sample_rate(0.0~1.0 포함)를 가져야 하고, 선택적으로 name, service, resource, tags 문자열 속성을 가질 수 있어요. name, service, resource, tags는 이 샘플링 규칙이 적용되는 트레이스를 제어해요. 모두 없으면 이 규칙이 모든 트레이스에 적용돼요. 규칙은 배열에서 선언된 순서대로 평가되고, 처음 일치한 것만 적용돼요. 어떤 것도 적용되지 않으면 tracing.sampling.default_rate가 적용돼요.
tracing.sampling.span_rules	DD_SPAN_SAMPLING_RULES,ENV_SPAN_SAMPLING_RULES_FILE	String	nil	Single Span Sampling 규칙을 설정해요. 이 규칙을 사용하면 해당 트레이스가 폐기되더라도 스팬을 유지할 수 있어요.
tracing.trace_id_128_bit_generation_enabled	DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED	Bool	true	true는 128비트 트레이스 ID를, false는 64비트 트레이스 ID를 생성해요
tracing.baggage_tag_keys	DD_TRACE_BAGGAGE_TAG_KEYS	Array<String>	['user.id', 'session.id', 'account.id']	스팬 태그로 변환해야 하는 baggage 키의 쉼표로 구분된 목록이에요. 이 목록에서 정확히, 대소문자를 구분해 일치하는 baggage 키는 접두사 "baggage."와 함께 스팬 태그로 변환돼요. 특수 값: 빈 문자열("")은 baggage 태그 변환을 비활성화하고, 와일드카드("*")는 모든 baggage 키를 스팬 태그로 변환해요.
tracing.report_hostname	DD_TRACE_REPORT_HOSTNAME	Bool	false	트레이스에 hostname 태그를 추가해요.
apm.tracing.enabled	DD_APM_TRACING_ENABLED	Bool	true	APM 트레이스를 활성화하거나 비활성화해요. false로 설정하면 계측은 여전히 실행되지만 분당 하나의 APM 트레이스만 Agent로 보내져요. 그 서비스는 Datadog에서 살아있는 것으로 간주되어 독립형 모드에서 다른 제품을 사용할 수 있게 해줘요. 지금은 Application Security만 지원돼요.

사용자 지정 로깅 (Custom logging)

기본적으로 모든 로그는 기본 Ruby 로거로 처리돼요. Rails를 사용할 땐 애플리케이션 로그 파일에서 메시지를 볼 수 있어요.

Datadog 클라이언트 로그 메시지는 [datadog]로 표시되므로 다른 메시지와 분리할 수 있어요.

또한 기본 로거를 덮어쓰고 사용자 지정 로거로 교체할 수 있어요. 이 작업은 log 설정을 사용해 해요.

f = File.new("my-custom.log", "w+") # Log messages should go there
Datadog.configure do |c|
  c.logger.instance = Logger.new(f) # Overriding the default logger
  c.logger.level = ::Logger::INFO
end

Datadog.logger.info { "this is typically called by tracing code" }

환경 및 태그 (Environment and tags)

기본적으로 트레이스 Agent(이 라이브러리가 아니라, 다양한 클라이언트에서 데이터를 수집하는 백그라운드 프로그램)는 Agent 설정 파일에 설정된 태그를 사용해요. 다음 환경 변수를 사용해 애플리케이션이 트레이스와 메트릭을 자동으로 태그하도록 구성할 수 있어요:

• DD_ENV: 애플리케이션 환경 (예: production, staging 등)
• DD_SERVICE: 애플리케이션의 기본 서비스 이름 (예: billing-api)
• DD_VERSION: 애플리케이션 버전 (예: 2.5, 202003181415, 1.3-alpha 등)
• DD_TAGS: ,로 구분된 값 쌍의 사용자 지정 태그 (예: layer:api,team:intake)
  • DD_ENV, DD_SERVICE, DD_VERSION이 설정되면 DD_TAGS에 정의된 각각의 env/service/version 태그를 덮어써요.
  • DD_ENV, DD_SERVICE, DD_VERSION이 설정되지 않으면 DD_TAGS에 정의된 태그로 각각 env/service/version을 채워요.

이 값들은 추적기 레벨에서도 덮어쓸 수 있어요:

Datadog.configure do |c|
  c.service = 'billing-api'
  c.env = 'test'
  c.tags = { 'team' => 'qa' }
  c.version = '1.3-alpha'
end

이렇게 하면 애플리케이션별로 이 값을 설정할 수 있어서, 예를 들어 같은 호스트에서 서로 다른 환경을 보고하는 여러 애플리케이션을 가질 수 있어요.

태그는 개별 스팬에 직접 설정할 수도 있어요. 이 경우 애플리케이션 레벨에서 정의된 충돌하는 태그보다 우선해요.

디버깅 및 진단 (Debugging and diagnostics)

추적에 대한 진단을 만드는 두 가지 권장 방법이 있어요:

디버그 모드 활성화 (Enabling debug mode)

라이브러리를 디버그 모드로 전환하면 억제된 오류를 포함한 추적 활동에 대한 상세한 로그가 생성돼요. 이 출력은 오류를 식별하거나 Agent로의 트레이스 출력을 확인하는 데 도움이 될 수 있어요.

diagnostics.debug = true 또는 DD_TRACE_DEBUG로 활성화할 수 있어요.

Datadog.configure { |c| c.diagnostics.debug = true }

부하가 걸리면 매우 많은 로그가 나올 수 있으므로, 프로덕션 또는 기타 민감한 환경에서 이 기능을 사용하는 건 권장하지 않아요. 애플리케이션 부하를 제어할 수 있는 통제된 환경에서 사용하는 게 가장 좋아요.

시작 로그 활성화 (Enabling startup logs)

시작 로그는 애플리케이션이 처음 구성될 때 추적 상태에 대한 보고서를 생성해요. 구성과 계측이 올바르게 활성화되었는지 확인하는 데 도움이 될 수 있어요.

diagnostics.startup_logs.enabled = true 또는 DD_TRACE_STARTUP_LOGS로 활성화할 수 있어요.

Datadog.configure { |c| c.diagnostics.startup_logs.enabled = true }

기본적으로 datadog이 애플리케이션이 비개발 환경에서 실행 중임을 감지하면 활성화돼요.

자동 계측을 사용한 설정 타이밍 (Configuration timing with auto-instrumentation)

Rails 애플리케이션에서 require 'datadog/auto_instrument'을 사용하면 config/initializers/*.rb 파일이 로드되기 전에 계측이 적용돼요.

이 타이밍은 특정 설정 옵션에 중요한 영향을 미쳐요:

일부 설정 옵션은 통합이 패치될 때(자동 계측 중에) 읽혀요. 자동 계측을 사용하는 Rails 애플리케이션에서는 이러한 옵션을 config/initializers/datadog.rb가 아닌 환경 변수로 설정해야 해요.

Rails 자동 계측에서 반드시 환경 변수여야 하는 옵션:

• tracing.contrib.global_default_service_name.enabled (DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED)
• GraphQL with_unified_tracer (DD_TRACE_GRAPHQL_WITH_UNIFIED_TRACER)

예시:

# Set via environment variables for Rails auto-instrumentation
DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED=true
DD_SERVICE=my-service

대안적인 방법:

1. 자동 계측을 유지하고 통합별 서비스 이름을 덮어쓰기:

   # Auto-instrumentation still runs; this overrides the defaults
   Datadog.configure do |c|
     c.service = 'my-service'
     # Only configure integrations where you want a custom service name
     c.tracing.instrument :redis, service_name: 'my-service'
     c.tracing.instrument :faraday, service_name: 'my-service'
   end
   

2. 수동 계측 사용: Gemfile에서 require: 'datadog/auto_instrument'을 제거해요. 그러면 initializer에서 모든 옵션(「tracing.contrib.global_default_service_name.enabled」 포함)을 구성할 수 있지만, 사용하는 각 통합을 c.tracing.instrument으로 호출해 수동으로 계측해야 해요.

   # Gemfile - without auto-instrumentation
   gem 'datadog'
   

   # config/initializers/datadog.rb - you must enable each integration
   Datadog.configure do |c|
     c.service = 'my-service'
     c.tracing.contrib.global_default_service_name.enabled = true
     # Must instrument every integration you use
     c.tracing.instrument :redis
     c.tracing.instrument :faraday
     c.tracing.instrument :rails
     # ... and so on for each integration
   end
   

샘플링 (Sampling)

사용 가능한 모든 샘플링 옵션 목록은 수집 메커니즘을 참고해요.

우선순위 샘플링 (Priority sampling)

우선순위 샘플링은 분산 트레이스에 전파되는 우선순위 속성을 사용해 트레이스를 유지할지 결정해요. 그 값은 트레이스가 얼마나 중요한지 Agent와 백엔드에 알려줘요.

샘플러는 우선순위를 다음 값으로 설정할 수 있어요:

• Datadog::Tracing::Sampling::Ext::Priority::AUTO_REJECT: 샘플러가 자동으로 트레이스를 거부하기로 결정했어요.
• Datadog::Tracing::Sampling::Ext::Priority::AUTO_KEEP: 샘플러가 자동으로 트레이스를 유지하기로 결정했어요.

우선순위 샘플링은 기본적으로 활성화되어 있어요. 활성화하면 샘플링된 분산 트레이스가 완전한 상태로 유지되도록 보장해요. 활성화되면 샘플러는 서비스와 볼륨에 따라 트레이스에 우선순위 0 또는 1을 자동으로 할당해요.

재미없는 트레이스를 버리거나 중요한 트레이스를 유지하기 위해 이 우선순위를 수동으로 설정할 수도 있어요. 이를 위해 TraceOperation#sampling_priority를 다음으로 설정해요:

• Datadog::Tracing::Sampling::Ext::Priority::USER_REJECT: 사용자가 트레이스를 거부하도록 요청했어요.
• Datadog::Tracing::Sampling::Ext::Priority::USER_KEEP: 사용자가 트레이스를 유지하도록 요청했어요.

분산 추적을 사용하지 않을 때는 트레이스가 완료되지 않은 동안 언제든지 우선순위를 변경할 수 있어요. 그러나 분산 컨텍스트에서 유용하려면 컨텍스트 전파(fork, RPC 호출) 전에 해야 해요. 컨텍스트가 전파된 후 우선순위를 변경하면 분산 트레이스의 각 부분이 서로 다른 우선순위를 사용하게 돼요. 일부는 유지되고 일부는 거부될 수 있으며, 이로 인해 트레이스가 부분적으로 저장되어 불완전하게 남을 수 있어요.

이런 이유로 우선순위를 변경한다면 가능한 한 빨리 하는 걸 권장해요.

샘플링 우선순위를 변경하려면 다음 메서드를 사용할 수 있어요:

# Rejects the active trace
Datadog::Tracing.reject!

# Keeps the active trace
Datadog::Tracing.keep!

활성 트레이스가 없을 때 Datadog::Tracing.reject!과 Datadog::Tracing.keep!을 사용해도 안전해요.

특정 트레이스 인스턴스를 거부할 수도 있어요:

# First, grab the active trace
trace = Datadog::Tracing.active_trace

# Rejects the trace
trace.reject!

# Keeps the trace
trace.keep!

Single Span Sampling

트레이스 레벨 샘플링 규칙으로 해당 트레이스가 폐기되더라도 스팬을 유지할 수 있게 해주는 샘플링 규칙을 구성할 수 있어요.

이렇게 하면 트레이스 레벨 샘플링이 적용될 때 중요한 스팬을 유지할 수 있어요. Single Span Sampling으로는 스팬을 폐기할 수 없어요.

구성 방법은 수집 메커니즘 문서를 참고해요.

사용자 지정 샘플링 (Custom sampling)

완전히 사용자 지정된 샘플링 전략을 구성하는 것도 가능해요.

가능하면 사용자 지정 샘플링을 피하고, 대신 추가 설정에서 제공되는 샘플링 옵션과 함께 우선순위 샘플링 API를 사용해요. 이렇게 하면 샘플링 결정의 유지 관리성과 디버깅 가능성이 가장 높아져요.

사용자 지정 샘플링이 필요할 때는 두 가지 전략이 가능해요:

1. 우선순위 샘플링 — 권장되는 샘플링 전략이며 모든 수집 후 샘플링 설정과 보고를 지원해요.

2. 애플리케이션 측 — 스팬이 Ruby 프로세스에서 플러시되는 것을 완전히 막을 수 있지만, 수집 후 샘플링이 올바르게 작동하는 데 필요한 데이터를 받지 못하게 해요.

이 전략은 성능 향상과 대역폭 절감이 시스템에 필수적일 때만 사용해야 해요.

애플리케이션 측 샘플링을 사용한다면 GitHub에 이슈를 열어 알려주세요. 그래야 사용 사례를 더 잘 이해하고 지원할 수 있어요.

사용자 지정 샘플링은 sample!와 sample_rate 메서드에 응답하는 Ruby 객체를 만들어 구성할 수 있어요:

class CustomSampler
   # Sets the trace sampling status.
   #
   # This method *may* modify the `trace`, in case changes are necessary based on the
   # sampling decision (e.g. adding trace tags).
   #
   # @param [Datadog::Tracing::TraceOperation] trace
   # @return [void]
  def sample!(trace)
     # Implement one of the two sampling strategies to record the sampling decision:
     #
     # 1. Priority sampling. Ingestion Controls page will be accurate.
     #   a. Keep span with priority sampling.
     trace.keep!
     #   b. or drop span with priority sampling.
     trace.reject!

     # Or

     # 2. Do not flush span. Ingestion Controls page will be **inaccurate**.
     #    Can save processing time and bandwidth.
     #   a. Flush the span
     trace.sampled = true
     #   b. Do not flush the span
     trace.sampled = false
  end

  # The sampling rate, if this sampler has such concept. Otherwise, `nil`.
  #
  # @param [Datadog::Tracing::TraceOperation] trace
  # @return [Float,nil] sampling ratio between 0.0 and 1.0 (inclusive), or `nil` if not applicable
  def sample_rate(trace)
     # ...
  end
end

Datadog.configure do |c|
  c.tracing.sampler = CustomSampler.new
end

다른 모든 샘플링 옵션은 추가 설정을 참고해요.

분산 추적 (Distributed Tracing)

분산 추적은 여러 계측된 애플리케이션에 걸쳐 트레이스가 전파되도록 해서, 요청이 서비스별 개별 트레이스가 아니라 단일 트레이스로 표시되게 해요.

애플리케이션 경계를 넘어 요청을 추적하려면 각 애플리케이션 사이에서 다음이 전파되어야 해요:

Property	Type	Description
Trace ID	Integer	트레이스의 ID예요. 같은 트레이스에 속한 모든 요청에서 이 값은 동일해야 해요.
Parent Span ID	Integer	요청을 시작한 서비스에 있는 스팬의 ID예요. 이 값은 트레이스 내 각 요청마다 항상 달라요.
Sampling Priority	Integer	트레이스의 샘플링 우선순위 레벨이에요. 같은 트레이스에 속한 모든 요청에서 이 값은 동일해야 해요.

이런 전파는 다음과 같이 시각화할 수 있어요:

Service A:
  Trace ID:  100000000000000001
  Parent ID: 0
  Span ID:   100000000000000123
  Priority:  1

  |
  | Service B Request:
  |   Metadata:
  |     Trace ID:  100000000000000001
  |     Parent ID: 100000000000000123
  |     Priority:  1
  |
  V

Service B:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000123
  Span ID:   100000000000000456
  Priority:  1

  |
  | Service C Request:
  |   Metadata:
  |     Trace ID:  100000000000000001
  |     Parent ID: 100000000000000456
  |     Priority:  1
  |
  V

Service C:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000456
  Span ID:   100000000000000789
  Priority:  1

HTTP를 통한 전파

계측된 애플리케이션 간의 HTTP 요청에서는 이 트레이스 메타데이터가 HTTP 요청 헤더를 통해 전파돼요:

Property	Type	HTTP Header name
Trace ID	Integer	x-datadog-trace-id
Parent Span ID	Integer	x-datadog-parent-id
Sampling Priority	Integer	x-datadog-sampling-priority

즉:

Service A:
  Trace ID:  100000000000000001
  Parent ID: 0
  Span ID:   100000000000000123
  Priority:  1

  |
  | Service B HTTP Request:
  |   Headers:
  |     x-datadog-trace-id:          100000000000000001
  |     x-datadog-parent-id:         100000000000000123
  |     x-datadog-sampling-priority: 1
  |
  V

Service B:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000123
  Span ID:   100000000000000456
  Priority:  1

  |
  | Service C HTTP Request:
  |   Headers:
  |     x-datadog-trace-id:          100000000000000001
  |     x-datadog-parent-id:         100000000000000456
  |     x-datadog-sampling-priority: 1
  |
  V

Service C:
  Trace ID:  100000000000000001
  Parent ID: 100000000000000456
  Span ID:   100000000000000789
  Priority:  1

분산 헤더 형식 (Distributed header formats)

추적은 다음 분산 트레이스 형식을 지원해요:

• datadog
• tracecontext: W3C Trace Context
• b3multi: B3 multiple-headers
• b3: B3 single-header
• none: No-op.

Datadog.configure로 이 형식들의 사용을 활성화/비활성화할 수 있어요:

Datadog.configure do |c|
  # List of header formats that should be extracted
  c.tracing.propagation_style_extract = [ 'tracecontext', 'datadog', 'b3' ]

  # List of header formats that should be injected
  c.tracing.propagation_style_inject = [ 'tracecontext', 'datadog' ]
end

통합에 대한 분산 추적 활성화

datadog에 포함된 많은 통합이 분산 추적을 지원해요. 분산 추적은 Agent v7과 대부분의 Agent v6 버전에서 기본적으로 활성화되어 있어요. 필요하면 설정으로 분산 추적을 활성화할 수 있어요.

• 애플리케이션이 분산 추적이 활성화된 서비스에서 요청을 받는다면, 이 요청을 처리하는 통합(예: Rails)에서 분산 추적을 활성화해야 해요
• 애플리케이션이 분산 추적이 활성화된 서비스에 요청을 보낸다면, 이 요청을 보내는 통합(예: Faraday)에서 분산 추적을 활성화해야 해요
• 애플리케이션이 분산 추적을 구현하는 요청을 보내고 받는다면, 이 요청을 처리하는 모든 통합을 활성화해야 해요.

통합에 대한 분산 추적 활성화 방법에 대한 자세한 내용은 해당 통합 문서를 참고해요:

• Excon
• Faraday
• Rest Client
• Net/HTTP
• Rack
• Rails
• Sinatra
• http.rb
• httpclient
• httpx

HTTP 전파기 사용 (Using the HTTP propagator)

이 메타데이터 전파 과정을 더 쉽게 하기 위해 Datadog::Tracing::Contrib::HTTP 모듈을 사용할 수 있어요.

클라이언트에서는:

Datadog::Tracing.trace('web.call') do |span, trace|
  # Inject trace headers into request headers (`env` must be a Hash)
  Datadog::Tracing::Contrib::HTTP.inject(trace.to_digest, env)
end

서버에서는:

trace_digest = Datadog::Tracing::Contrib::HTTP.extract(request.env)

Datadog::Tracing.trace('web.work', continue_from: trace_digest) do |span|
  # Do web work...
end

HTTP 요청 대기열 처리 (HTTP request queuing)

HTTP 요청에서 시작된 트레이스는 요청이 Ruby 애플리케이션에 도달하기 전에 프론트엔드 웹 서버 또는 로드 밸런서 대기열에서 보낸 시간을 포함하도록 구성할 수 있어요.

이 기능은 기본적으로 비활성화되어 있어요. 활성화하려면 요청 대기열 기능을 켜기 전에 웹 서버(예: Nginx)에서 X-Request-Start 또는 X-Queue-Start 헤더를 추가해야 해요. 다음은 Nginx 설정 예시예요:

# /etc/nginx/conf.d/ruby_service.conf
server {
    listen 8080;

    location / {
      proxy_set_header X-Request-Start "t=${msec}";
      proxy_pass http://web:3000;
    }
}

Rack 기반 애플리케이션의 경우 문서를 참고해요.

처리 파이프라인 (Processing Pipeline)

일부 애플리케이션은 트레이스가 Datadog로 보내지기 전에 수정되거나 필터링되도록 요구할 수 있어요. 처리 파이프라인을 사용하면 이런 동작을 정의하는 프로세서를 만들 수 있어요.

필터링 (Filtering)

블록이 truthy로 평가될 때 스팬을 제거하기 위해 Datadog::Tracing::Pipeline::SpanFilter 프로세서를 사용할 수 있어요:

Datadog::Tracing.before_flush(
  # Remove spans that match a particular resource
  Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.resource =~ /PingController/ },
  # Remove spans that are trafficked to localhost
  Datadog::Tracing::Pipeline::SpanFilter.new { |span| span.get_tag('host') == 'localhost' }
)

처리 (Processing)

스팬을 수정하기 위해 Datadog::Tracing::Pipeline::SpanProcessor 프로세서를 사용할 수 있어요:

Datadog::Tracing.before_flush(
  # Strip matching text from the resource field
  Datadog::Tracing::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
)

사용자 지정 프로세서 (Custom processor)

프로세서는 trace를 인자로 받는 #call에 응답하는 모든 객체가 될 수 있어요(trace는 Datadog::Span의 Array예요.)

예를 들어 축약된 블록 문법을 사용하면:

Datadog::Tracing.before_flush do |trace|
   # Processing logic...
   trace
end

사용자 지정 프로세서 클래스의 경우:

class MyCustomProcessor
  def call(trace)
    # Processing logic...
    trace
  end
end

Datadog::Tracing.before_flush(MyCustomProcessor.new)

두 경우 모두 프로세서 메서드는 반드시 trace 객체를 반환해야 해요. 이 반환 값은 파이프라인의 다음 프로세서로 전달돼요.

주의 사항 (Caveats)

1. 제거된 스팬은 트레이스 메트릭을 생성하지 않으므로 모니터와 대시보드에 영향을 미쳐요.
2. 스팬을 제거하면 제거된 스팬의 모든 하위 스팬도 제거돼요. 이렇게 해서 트레이스 그래프에 고아 스팬이 생기는 걸 방지해요.
3. 디버그 모드 로그는 처리 파이프라인이 실행되기 전의 스팬 상태를 보고해요: 수정되거나 제거된 스팬은 디버그 모드 로그에서 원래 상태로 표시돼요.

트레이스 상관 관계 (Trace correlation)

로깅 같은 많은 경우에 트레이스 ID를 다른 이벤트나 데이터 스트림과 상호 참조하기 쉽게 연관시키는 것이 유용할 수 있어요.

Rails 애플리케이션에서의 로깅 (For logging in Rails applications)

자동 (Automatic)

기본 로거(ActiveSupport::TaggedLogging), lograge, semantic_logger를 사용하는 Rails 애플리케이션에서는 트레이스 상관 관계 주입이 기본적으로 활성화되어 있어요.

환경 변수 DD_LOGS_INJECTION=false를 설정해 비활성화할 수 있어요.

경고: lograge를 사용한다면, 평문 TaggedLogging 태그가 로그 라인을 오염시키지 않도록 ActiveSupport::TaggedLogging을 비활성화해요.

ActiveSupport::TaggedLogging을 비활성화하려면 Rails 설정에서 다음을 설정해요:

config.logger = ActiveSupport::Logger.new(STDOUT)
config.active_job.logger = ActiveSupport::Logger.new(STDOUT)

semantic_logger를 사용할 때는 이 작업이 필요하지 않아요.

Ruby 애플리케이션에서의 로깅 (For logging in Ruby applications)

로거에 상관 관계 ID를 추가하려면 Datadog::Tracing.correlation으로 상관 관계 ID를 가져온 다음 메시지에 추가하는 로그 포맷터를 추가해요.

Datadog 로깅과 올바르게 상관 관계를 맺으려면 로그 메시지에 다음이 나타나는 순서대로 포함되어 있어야 해요:

• dd.env=<ENV>: <ENV>는 Datadog::Tracing.correlation.env와 같아요. 환경이 설정되지 않았으면 생략해요.
• dd.service=<SERVICE>: <SERVICE>는 Datadog::Tracing.correlation.service와 같아요. 기본 서비스 이름이 설정되지 않았으면 생략해요.
• dd.version=<VERSION>: <VERSION>는 Datadog::Tracing.correlation.version과 같아요. 애플리케이션 버전이 설정되지 않았으면 생략해요.
• dd.trace_id=<TRACE_ID>: <TRACE_ID>는 Datadog::Tracing.correlation.trace_id와 같거나, 로깅 중 활성 트레이스가 없으면 0이에요.
• dd.span_id=<SPAN_ID>: <SPAN_ID>는 Datadog::Tracing.correlation.span_id와 같거나, 로깅 중 활성 트레이스가 없으면 0이에요.

Datadog::Tracing.log_correlation은 dd.env=<ENV> dd.service=<SERVICE> dd.version=<VERSION> dd.trace_id=<TRACE_ID> dd.span_id=<SPAN_ID>를 반환해요.

활성 트레이스가 없고 애플리케이션 환경과 버전이 설정되지 않았다면 dd.env= dd.service= dd.version= dd.trace_id=0 dd.span_id=0을 반환해요.

실제 예시:

require 'datadog'
require 'logger'

ENV['DD_ENV'] = 'production'
ENV['DD_SERVICE'] = 'billing-api'
ENV['DD_VERSION'] = '2.5.17'

logger = Logger.new(STDOUT)
logger.progname = 'my_app'
logger.formatter  = proc do |severity, datetime, progname, msg|
  "[#{datetime}][#{progname}][#{severity}][#{Datadog::Tracing.log_correlation}] #{msg}\n"
end

# When no trace is active
logger.warn('This is an untraced operation.')
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=0 dd.span_id=0] This is an untraced operation.

# When a trace is active
Datadog::Tracing.trace('my.operation') { logger.warn('This is a traced operation.') }
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=8545847825299552251 dd.span_id=3711755234730770098] This is a traced operation.

전송 레이어 구성 (Configuring the transport layer)

기본적으로 datadog은 나열된 우선순위에서 가장 먼저 사용 가능한 설정으로 Agent에 연결해요:

1. 명시적으로 제공된 구성 설정(호스트명/포트/전송 방식)을 통해
2. /var/run/datadog/apm.socket에 있는 Unix Domain Socket (UDS)을 통해
3. 127.0.0.1:8126로 HTTP over TCP를 통해

하지만 추적기는 트레이스 데이터를 대체 대상 또는 대체 프로토콜로 보내도록 구성할 수 있어요.

기본 Agent 호스트명과 포트 변경 (Changing default Agent hostname and port)

Agent 호스트나 포트를 변경하려면 DD_AGENT_HOST와 DD_TRACE_AGENT_PORT를 제공해요.

또는 Datadog.configure 블록 안에서 다음 설정을 제공해요:

Datadog.configure do |c|
  c.agent.host = '127.0.0.1'
  c.agent.port = 8126
end

자세한 내용은 추가 설정을 참고해요.

Agent 연결 방법 (Agent connection methods)

Agent는 TCP 또는 Unix Domain Socket (UDS)을 통한 통신을 지원해요. 추적기는 제공된 설정에 따라 Agent의 연결 방법을 자동으로 감지해요.

TCP

host와 port가 설정되어 있거나 DD_TRACE_AGENT_URL에서 프로토콜로 HTTP/HTTPS가 지정된 경우 추적기는 TCP를 통해 Agent에 연결해요. TCP가 기본 연결 방법이에요.

Unix Domain Socket (UDS)

사용하려면 먼저 트레이스 Agent를 Unix 소켓으로 수신하도록 구성한 다음, 추적기를 다음과 같이 구성해요:

Datadog.configure do |c|
  # Provide local path to trace Agent Unix socket
  c.agent.uds_path = '/tmp/ddagent/trace.sock'
end

프로토콜을 unix로 설정해 DD_TRACE_AGENT_URL 환경 변수로 UDS 경로를 정의할 수도 있어요:

DD_TRACE_AGENT_URL=unix:///tmp/ddagent/trace.sock

참고: UDS와 TCP 설정을 혼합할 수 없어요. c.agent.uds_path를 설정했다면 c.agent.host나 c.agent.port를 설정하면 안 돼요.

메트릭 (Metrics)

추적기와 그 통합은 애플리케이션 성능에 대한 유용한 통찰을 줄 수 있는 몇 가지 추가 메트릭을 생성할 수 있어요. 이 메트릭은 dogstatsd-ruby로 수집되며, 트레이스를 보내는 것과 같은 Datadog Agent로 보낼 수 있어요.

메트릭 수집을 위해 애플리케이션을 구성하는 방법:

1. StatsD용 Datadog Agent 구성
2. Gemfile에 gem 'dogstatsd-ruby', '~> 5.3' 추가

애플리케이션 런타임용 (For application runtime)

런타임 메트릭이 구성되면 트레이스 라이브러리가 애플리케이션의 상태에 대한 메트릭을 자동으로 수집하고 보내요.

런타임 메트릭을 구성하려면 다음 구성을 추가해요:

# config/initializers/datadog.rb
require 'datadog/statsd'
require 'datadog'

Datadog.configure do |c|
  # To enable runtime metrics collection, set `true`. Defaults to `false`
  # You can also set DD_RUNTIME_METRICS_ENABLED=true to configure this.
  c.runtime_metrics.enabled = true

  # Optionally, you can configure runtime metrics to generate an additional `runtime-id` tag
  # on the generated metrics, which allows you to filter metrics at the individual process level.
  # You can also set DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED=true to configure this.
  c.runtime_metrics.experimental_runtime_id_enabled = true

  # Optionally, you can configure the Statsd instance used for sending runtime metrics.
  # Statsd is automatically configured with default settings if `dogstatsd-ruby` is available.
  # You can configure with host and port of Datadog Agent; defaults to 'localhost:8125'.
  c.runtime_metrics.statsd = Datadog::Statsd.new
end

Datadog::Statsd 구성에 대한 자세한 내용은 Dogstatsd 문서를 참고해요.

통계는 VM별로 다르며 다음을 포함해요:

Name	Type	Description	Available on
runtime.ruby.class_count	gauge	메모리 공간의 클래스 수예요.	CRuby
runtime.ruby.gc.*	gauge	가비지 컬렉션 통계: GC.stat에서 수집돼요.	All runtimes
runtime.ruby.yjit.*	gauge	RubyVM::YJIT.runtime_stats에서 수집한 YJIT 통계예요.	CRuby (if enabled)
runtime.ruby.thread_count	gauge	스레드 수예요.	All runtimes
runtime.ruby.global_constant_state	gauge	전역 상수 캐시 세대예요.	CRuby ≤ 3.1
runtime.ruby.global_method_state	gauge	전역 메서드 캐시 세대.	CRuby 2.x
runtime.ruby.constant_cache_invalidations	gauge	상수 캐시 무효화 횟수예요.	CRuby ≥ 3.2
runtime.ruby.constant_cache_misses	gauge	상수 캐시 미스 수예요.	CRuby ≥ 3.2

또한 모든 메트릭은 다음 태그를 포함해요:

Name	Description
language	추적된 프로그래밍 언어예요 (예: ruby)
service	이 메트릭과 연관된 서비스 목록이에요.

프로파일링 (Profiling)

datadog은 프로덕션 환경에서 메서드 수준의 애플리케이션 리소스 사용을 측정하는 프로파일을 생성할 수 있어요. 이러한 프로파일은 기존 트레이스 계측 밖의 Ruby 코드에서 소비된 리소스에 대한 통찰을 줄 수 있어요.

설정

프로파일링 시작하기는 Ruby 프로파일러 활성화 가이드를 따라 해요.

문제 해결 (Troubleshooting)

프로파일링에 문제가 있다면 프로파일러 문제 해결 가이드를 확인해요.

Resque 작업 프로파일링 (Profiling Resque jobs)

Resque 작업을 프로파일링할 때는 Resque 문서에 설명된 RUN_AT_EXIT_HOOKS=1 옵션을 설정해야 해요.

이 플래그가 없으면 Resque가 정보를 제출할 기회를 주기 전에 워커 프로세스를 종료하므로 수명이 짧은 Resque 작업의 프로파일을 사용할 수 없어요.

오류 추적 (Error Tracking)

datadog은 처리된 오류를 자동으로 보고할 수 있어요. 오류는 오류가 처리된 스팬에 스팬 이벤트를 통해 연결돼요. 또한 Error Tracking에 직접 보고돼요.

요구 사항 (Requirements)

• Ruby 2.7+. JRuby와 TruffleRuby는 지원되지 않아요.
• Datadog Ruby gem(datadog) v2.16.0+.

설정 (Configuration)

다음 환경 변수를 사용해 처리된 오류의 자동 보고를 활성화할 수 있어요:

Environment variable	Type	Description	Default
DD_ERROR_TRACKING_HANDLED_ERRORS	String	사용자 코드, 타사 gem, 또는 둘 다에서 처리된 오류를 보고해요. 허용 값: user, third_party, all.	nil
DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE	Array[String]	처리된 오류를 보고해야 하는 경로, 파일 이름, gem 이름의 쉼표로 구분된 목록이에요. 자세한 내용은 Include 형식을 참고해요.Ruby 3.3 이상: 오류가 rescue된 위치가 일치해요.Ruby 3.2 이하: 오류가 발생한 위치가 일치해요.	[]

또는 Datadog.configure 블록 안에서 다음 설정으로 오류 추적 매개변수를 설정해요:

Setting	Type	Description	Default
c.error_tracking.handled_errors	String	사용자 코드, 타사 gem, 또는 둘 다에서 처리된 오류를 보고해요. 허용 값: user, third_party, all.	nil
c.error_tracking.handled_errors_include	Array[String]	처리된 오류를 보고해야 하는 경로, 파일 이름, gem 이름의 쉼표로 구분된 목록이에요. 자세한 내용은 Include 형식을 참고해요.Ruby 3.3 이상: 오류가 rescue된 위치가 일치해요.Ruby 3.2 이하: 오류가 발생한 위치가 일치해요.	[]

Include 형식 (Include format)

DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE 환경 변수 또는 c.error_tracking.handled_errors_include 설정은 다음 중 하나 이상을 지정해야 해요:

• 파일 이름: 예를 들어 main.rb를 계측하려면 main.
• 폴더 이름: 예를 들어 subdir라는 폴더의 모든 Ruby 파일을 계측하려면 subdir.
• Gem 이름: 예를 들어 rails gem 및 rails라는 프로젝트 하위 폴더의 모든 Ruby 파일을 계측하려면 rails.
• 절대 경로: 예를 들어 /app/lib/mypackage/main.rb로 그 파일을 계측하거나 /app/lib/mypackage/로 그 폴더의 모든 Ruby 파일을 계측해요.
• 상대 경로: 예를 들어 app 디렉터리에서 실행되는 프로그램의 경우 ./lib/mypackage/main.rb로 main.rb 파일을 계측하거나 ./lib/mypackage/로 그 폴더의 모든 Ruby 파일을 계측해요.

동적 계측 (Dynamic Instrumentation)

Dynamic Instrumentation을 사용하면 재시작이나 재배포 없이 실행 중인 애플리케이션에 로그 프로브, 메트릭 프로브, 스팬 프로브를 추가할 수 있어요. 설정 지침은 Dynamic Instrumentation을 참고해요.

설정 (Configuration)

Environment variable	Type	Description	Default
DD_DYNAMIC_INSTRUMENTATION_ENABLED	Boolean	Dynamic Instrumentation을 활성화하거나 비활성화해요. true는 부팅 시 활성화하고, false는 비활성화하며 원격 구성을 통한 UI 기반 활성화를 차단해요. 설정하지 않으면(기본값) 부팅 시에는 꺼져 있지만 프로브가 생성되면 Datadog UI에서 활성화할 수 있어요.	false
DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS	Array	기본 목록에 추가로 수정(redact)할 변수/키 이름의 쉼표로 구분된 목록이에요. 이름은 정규화되고(밑줄, 대시, @, $ 제거) 대소문자를 구분하지 않고 일치해요.	[]
DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS	Array	기본 수정 목록에서 제외할 변수/키 이름의 쉼표로 구분된 목록이에요. 이 값들은 캡처할 수 있어요.	[]
DD_DYNAMIC_INSTRUMENTATION_REDACTED_TYPES	Array	값이 수정될 클래스 이름의 쉼표로 구분된 목록이에요. 와일드카드 일치를 위해 *를 접미사로 붙여요 (예: Foo*는 Foo, FooBar, Foo::Bar를 수정해요).	[]
DD_DYNAMIC_INSTRUMENTATION_MAX_TIME_TO_SERIALIZE	Integer	캡처 표현식 평가를 위한 프로브 발화당 시간 예산(밀리초)이에요.	200

또는 Datadog.configure 블록 안에서 DI 매개변수를 설정해요:

Setting	Type	Description	Default
c.dynamic_instrumentation.enabled	Boolean	Dynamic Instrumentation을 활성화하거나 비활성화해요.	false
c.dynamic_instrumentation.redacted_identifiers	Array	기본 목록에 추가로 수정할 변수/키 이름이에요.	[]
c.dynamic_instrumentation.redaction_excluded_identifiers	Array	기본 수정 목록에서 제외할 변수/키 이름이에요.	[]
c.dynamic_instrumentation.redacted_type_names	Array	값이 수정될 클래스 이름이에요. 와일드카드에 *를 접미사로 붙여요.	[]
c.dynamic_instrumentation.max_time_to_serialize_ms	Integer	캡처 표현식 평가를 위한 프로브 발화당 시간 예산(밀리초)이에요.	200

심볼 데이터베이스 (Symbol Database)

Dynamic Instrumentation이 활성화되면 추적기가 애플리케이션에서 심볼 정보(클래스 이름, 메서드 시그니처, 매개변수 이름)를 추출해 업로드하여 DI UI에서 자동 완성을 가능하게 할 수 있어요. Symbol Database 업로드는 Dynamic Instrumentation을 따릅니다: 기본적으로 Dynamic Instrumentation이 실제로 활성화된 경우에만(DD_DYNAMIC_INSTRUMENTATION_ENABLED 또는 DI UI를 통한 암시적 활성화) 심볼을 업로드하고, 그 외에는 꺼져 있어요. 업로드할 때 Remote Configuration으로 자동 활성화돼요. DD_SYMBOL_DATABASE_UPLOAD_ENABLED(또는 c.symbol_database.enabled)를 true/false로 설정해 덮어쓸 수 있어요: true는 Dynamic Instrumentation과 관계없이 업로드하고, false는 완전히 비활성화해요.

Environment variable	Type	Description	Default
DD_SYMBOL_DATABASE_UPLOAD_ENABLED	Boolean	심볼 데이터베이스 업로드를 활성화하거나 비활성화해요.	설정하지 않음: Dynamic Instrumentation이 실제로 활성화된 경우에만 업로드

Setting	Type	Description	Default
c.symbol_database.enabled	Boolean, nil	심볼 데이터베이스 업로드를 활성화하거나 비활성화해요; nil(설정하지 않음)은 Dynamic Instrumentation을 따릅니다.	설정하지 않음(nil): Dynamic Instrumentation이 실제로 활성화된 경우에만 업로드

Symbol Database는 MRI Ruby 2.7+와 Remote Configuration(기본적으로 활성화)이 필요해요. 무엇이 추출되는지, 어떤 코드가 포함되는지, Ruby 버전별 동작 차이에 대한 자세한 내용은 Dynamic Instrumentation — Symbol Database를 참고해요.

알려진 문제 및 권장 설정 (Known issues and suggested configurations)

페이로드가 너무 큼 (Payload too large)

기본적으로 Datadog는 계측된 애플리케이션 내 메모리 오버헤드를 방지하기 위해 트레이스 페이로드의 크기를 제한해요. 그 결과 수천 개의 작업이 포함된 트레이스는 Datadog로 보내지지 않을 수 있어요.

트레이스가 누락되면 디버그 모드를 활성화해서 "Dropping trace. Payload too large"가 포함된 메시지가 로그에 기록되는지 확인해요.

디버그 모드는 매우 상세하므로 Datadog는 이 기능을 켜두거나 프로덕션에서 활성화하는 걸 권장하지 않아요. 확인 후 비활성화해요. 비슷한 메시지가 있는지 Datadog Agent 로그를 확인할 수 있어요.

큰 페이로드로 인해 트레이스가 폐기되는 것을 확인했다면 partial_flush 설정을 활성화해 큰 트레이스를 더 작은 조각으로 나눠요.

스택 레벨이 너무 깊음 (Stack level too deep)

Datadog 추적은 다른 일반적인 라이브러리(예: Rails, Rack 등)에 계측을 추가해 트레이스 데이터를 수집해요. 일부 라이브러리는 이 계측을 추가하는 API를 제공하지만, 그렇지 않은 것도 있어요. 계측 API가 없는 라이브러리에 계측을 추가하기 위해 Datadog은 "monkey-patching"이라는 기법으로 해당 라이브러리의 코드를 수정해요.

Ruby 1.9.3 이하 버전에서 "monkey-patching"은 기존 Ruby 메서드를 파괴적으로 교체하는 alias_method(메서드 재작성이라고도 함)를 자주 사용했어요. 하지만 두 라이브러리가 같은 메서드를 "재작성"하려고 하면 이 방식은 자주 충돌과 오류를 일으켰어요 (예: 서로 다른 두 APM 패키지가 같은 메서드를 계측하려는 경우).

Ruby 2.0에서 Module#prepend 기능이 도입됐어요. 이 기능은 파괴적인 메서드 재작성을 피하고 같은 메서드에 여러 "monkey patch"를 허용해요. 결과적으로 코드를 "monkey patch"하는 가장 안전하고 선호되는 방법이 됐어요.

Datadog 계측은 Module#prepend 기능을 거의 독점적으로 사용하여 파괴적이지 않게 계측을 추가해요. 하지만 일부 다른 라이브러리(보통 Ruby < 2.0을 지원하는 것들)는 여전히 alias_method를 사용하며, 이는 Datadog 계측과 충돌하여 종종 SystemStackError 또는 stack level too deep 오류를 일으킬 수 있어요.

alias_method의 구현이 그 라이브러리들 안에 존재하므로 Datadog은 일반적으로 고칠 수 없어요. 하지만 일부 라이브러리에는 알려진 해결 방법이 있어요:

• rack-mini-profiler: Net::HTTP stack level too deep errors.

알려진 해결 방법이 없는 라이브러리의 경우, alias나 Module#alias_method를 사용하는 라이브러리를 제거하거나, 테스트를 위해 라이브러리를 다른 환경으로 분리하는 걸 고려해요.

추가 질문이 있거나 이 문제의 발생을 보고하고 싶다면 Datadog 지원팀에 문의해 주세요.

Resque 워커가 종료 시 멈춤 (Resque workers hang on exit)

Resque가 작업마다 프로세스를 fork하는 기본 동작은 드물게 datadog으로 계측된 resque 프로세스가 종료 시 멈추는 결과를 낳을 수 있어요.

해결 방법으로 FORK_PER_JOB 환경 변수를 false로 설정해 이 동작을 비활성화하는 걸 권장해요.

문제에 대한 논의는 이 이슈를 참고해요.

더 알아보기 (Learn more)