개요

이 가이드에 따라 Windows 기반 베어메탈 호스트 및 가상 머신에 Datadog Distribution of OpenTelemetry (DDOT) Collector를 설치하세요.

요구 사항

이 가이드를 완료하려면 다음이 필요합니다.

Datadog 계정:

1. Datadog 계정이 없는 경우 Datadog 계정을 생성합니다.
2. Datadog API 키를 확인하거나 생성합니다.

소프트웨어:

• 지원되는 Windows 버전(Windows Server 2016 이상 또는 Windows 10 이상). 자세한 내용은 지원되는 플랫폼을 참조하세요.

네트워크:

When using the Datadog SDK with OpenTelemetry API support, telemetry is routed to different components depending on the signal source. Ensure the following ports are accessible on your Datadog Agent or Collector:

Datadog Agent와 OpenTelemetry Collector 설치

설치

Windows 호스트에 DDOT Collector를 설치하려면 다음 MSI 명령을 사용하세요.

$p = Start-Process -Wait -PassThru msiexec -ArgumentList '/qn /i "https://windows-agent.datadoghq.com/datadog-agent-7-latest.amd64.msi" /log C:\Windows\SystemTemp\install-datadog.log APIKEY="<DATADOG_API_KEY>" SITE="" DD_OTELCOLLECTOR_ENABLED=true'
if ($p.ExitCode -ne 0) {
  Write-Host "msiexec failed with exit code $($p.ExitCode) please check the logs at C:\Windows\SystemTemp\install-datadog.log" -ForegroundColor Red
}

이 명령은 핵심 Datadog Agent 패키지와 함께 실행되는 DDOT Collector를 모두 설치합니다.

참고: Agent v7.78 이상 버전의 경우, Datadog Agent가 호스트에 이미 설치되어 있다면 DDOT Collector를 별도로 설치할 수 있습니다. 관리자 권한으로 실행한 PowerShell 세션에서 다음 명령을 실행하세요.

& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" otel install

유효성 검사

설치를 확인하려면 Agent의 상태 명령을 실행하세요.

& "$env:ProgramFiles\Datadog\Datadog Agent\bin\agent.exe" status

설치에 성공하면 다음과 같은 Agent 정보로 시작하는 Agent 상태 보고서가 반환됩니다.

====================
Agent (v7.x.x)
====================
  Status date: 2025-08-22 18:35:17.449 UTC (1755887717449)
  Agent start: 2025-08-22 18:16:27.004 UTC (1755886587004)
  Pid: 2828211
  Go Version: go1.24.6
  Python Version: 3.12.11
  Build arch: amd64
  Agent flavor: agent
  FIPS Mode: not available
  Log Level: info

OpenTelemetry 정보가 포함된 OTel Agent 상태 섹션도 표시됩니다.

==========
OTel Agent
==========

  Status: Running
  Agent Version: 7.x.x
  Collector Version: v0.129.0

  Receiver
  ==========================
    Spans Accepted: 0
    Metric Points Accepted: 1055
    Log Records Accepted: 0

  Exporter
  ==========================
    Spans Sent: 0
    Metric Points Sent: 1055
    Log Records Sent: 0

Datadog Agent 구성

DDOT Collector를 활성화

Datadog Agent 구성 파일은 C:\ProgramData\Datadog\datadog.yaml에 자동으로 설치됩니다. 설치 프로그램은 DDOT Collector를 활성화하기 위해 C:\ProgramData\Datadog\datadog.yaml에 다음 구성 설정을 추가합니다.

otelcollector:
  enabled: true
agent_ipc:
  port: 5009
  config_refresh_interval: 60

DDOT는 기본적으로 OpenTelemetry Collector를 포트 4317(grpc) 및 4318(http)에 자동으로 바인딩합니다.

(필요시) 추가 Datadog 기능 활성화

사용 가능한 옵션의 전체 목록은 C:\ProgramData\Datadog\datadog.yaml.example의 모든 항목에 주석이 달린 참조 파일을 참조하세요. 또는 GitHub의 Windows용 Agent 구성 파일 예시를 참조하세요.

추가 Datadog 기능을 활성화할 때는 Datadog 환경 변수에 의존하지 말고 Datadog 또는 OpenTelemetry Collector 구성 파일을 사용하세요.

OpenTelemetry Collector 구성

설치 프로그램은 시작점으로 사용할 수 있는 OpenTelemetry Collector 샘플 구성을 C:\ProgramData\Datadog\otel-config.yaml에 제공합니다.

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: "otelcol"
          scrape_interval: 60s
          static_configs:
            - targets: ["0.0.0.0:8888"]
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
  datadog:
    api:
      key: <DATADOG_API_KEY>
      site: <DATADOG_SITE>
    sending_queue:
      batch:
        flush_timeout: 10s
processors:
  infraattributes:
    cardinality: 2
  cumulativetodelta:
connectors:
  datadog/connector:
    traces:
      compute_top_level_by_span_kind: true
      peer_tags_aggregation: true
      compute_stats_by_span_kind: true
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [infraattributes]
      exporters: [datadog, datadog/connector]
    metrics:
      receivers: [otlp, datadog/connector, prometheus]
      processors: [infraattributes, cumulativetodelta]
      exporters: [datadog]
    logs:
      receivers: [otlp]
      processors: [infraattributes]
      exporters: [datadog]

주요 구성 요소

텔레메트리 데이터를 Datadog으로 전송하기 위해 다음 구성 요소가 정의되어 있습니다.

Datadog 커넥터

Datadog 커넥터는 Datadog APM 트레이스 메트릭을 계산합니다.

connectors:
  datadog/connector:
    traces:

Datadog 익스포터

Datadog 익스포터는 트레이스, 메트릭 및 로그를 Datadog으로 내보냅니다.

exporters:
  datadog:
    api:
      key: <DATADOG_API_KEY>
      site: <DATADOG_SITE>
    sending_queue:
      batch:
        flush_timeout: 10s

참고: key가 지정되지 않았거나 시크릿으로 설정된 경우, 또는 site가 지정되지 않은 경우 시스템은 핵심 Agent 구성의 값을 사용합니다. 기본적으로 핵심 Agent는 사이트를 datadoghq.com(US1)으로 설정합니다.

Prometheus 수신기

Prometheus 수신기는 메트릭 파이프라인을 위해 OpenTelemetry Collector에서 상태 메트릭을 수집합니다.

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: "otelcol"
          scrape_interval: 60s
          static_configs:
            - targets: ["0.0.0.0:8888"]

자세한 내용은 Collector 상태 메트릭 설명서를 참조하세요.

Datadog으로 텔레메트리 전송

텔레메트리 데이터를 Datadog으로 전송하려면 다음 단계를 따르세요.

1. 애플리케이션을 계측합니다.
2. 애플리케이션 구성
3. 관측 가능성 데이터 상호 연결
4. 애플리케이션을 실행합니다.

애플리케이션 계측

OpenTelemetry API를 사용하여 애플리케이션을 계측하세요.

@WithSpan(kind = SpanKind.CLIENT)
public String getDate() {
    Span span = Span.current();
    span.setAttribute("peer.service", "random-date-service");
    ...
}

애플리케이션 구성

애플리케이션은 동일한 호스트에서 실행 중인 DDOT Collector로 데이터를 전송해야 합니다. 애플리케이션에 OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수가 설정되어 있는지 확인하세요.

예시 애플리케이션을 사용하는 경우 run-otel-local.sh에서 필요한 환경 변수를 설정하고 애플리케이션을 실행합니다.

export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

참고: 이 스크립트는 Git for Windows에 포함된 Git Bash에서 실행할 수 있습니다.

관측 가능성 데이터 상호 연결

Unified service tagging은 Datadog의 관측 가능성 데이터를 연결하여 메트릭, 트레이스 및 로그를 일관된 태그로 탐색할 수 있도록 합니다.

베어메탈 환경에서는 OpenTelemetry 리소스 속성 환경 변수를 통해 env, service 및 version을 설정합니다. DDOT Collector는 이러한 태깅 구성을 감지하고 애플리케이션에서 수집한 데이터에 적용합니다.

예시 애플리케이션에서는 run-otel-local.sh에서 이 작업을 수행합니다.

export OTEL_RESOURCE_ATTRIBUTES="service.name=my-calendar-service,service.version=1.0,deployment.environment.name=otel-test,host.name=calendar-host"

애플리케이션 실행

환경 변수에 적용한 변경 사항을 반영하려면 애플리케이션을 다시 배포하세요. 업데이트된 구성이 활성화되면 메트릭, 트레이스 및 로그 전반에서 unified service tagging이 완전히 활성화됩니다.

Datadog에서 관측 가능성 데이터 탐색

Datadog을 사용하여 애플리케이션의 관측 가능성 데이터를 확인하세요.

Fleet Automation

Datadog Agent, DDOT 및 업스트림 OpenTelemetry Collector 구성을 살펴보세요.

인프라 모니터링

런타임 및 인프라 메트릭을 조회하여 호스트 성능을 시각화, 모니터링 및 측정하세요.

로그

로그를 조회하여 애플리케이션 및 시스템 운영을 모니터링하고 문제를 해결하세요.

트레이스

트레이스와 스팬을 조회하여 애플리케이션이 처리하는 요청의 상태 및 성능을 확인하세요. 동일한 트레이스 내에서 인프라 메트릭도 함께 상호 연결되어 표시됩니다.

런타임 메트릭

애플리케이션의 런타임(JVM) 메트릭을 모니터링하세요.

Collector 상태 메트릭

DDOT Collector의 상태를 모니터링하려면 Collector 메트릭을 조회하세요.

추가 자료

추가적인 유용한 설명서, 링크 및 기사:

Datadog Agent와 함께 사용자 지정 OpenTelemetry 구성 요소 사용하기설명서