Datadog에서 ClickStack으로 마이그레이션

관측성 플랫폼 마이그레이션은 대개 단순히 데이터 저장 위치만 바꾸는 일에 그치지 않습니다. Datadog 에이전트와 SDK는 이미 수천 개의 애플리케이션, 호스트, 가상 머신, Kubernetes 파드 전반에 배포되어 있을 수 있습니다. 다른 백엔드를 평가해 보기도 전에 이 모든 것을 다시 계측해야 한다면, 실제 가치를 얻기도 전에 마이그레이션이 대규모 프로젝트로 커지게 됩니다. OpenTelemetry (OTel) collector의 ClickStack 배포판에 내장된 Datadog 수신기는 이러한 선행 비용을 없애 줍니다. 기존 Datadog 에이전트와 SDK는 변경 없이 계속 실행됩니다. 텔레메트리를 Datadog로 보내는 대신 수신기로 보내도록 설정하면, 수신기가 Datadog의 네이티브 로그, 트레이스, 메트릭 페이로드를 OpenTelemetry 데이터 모델로 변환한 뒤 표준 collector pipeline을 통해 ClickStack으로 전달합니다. 수신기는 일반적인 collector pipeline 내부에서 동작하므로 다음과 같은 용도로 사용할 수 있습니다:

애플리케이션 코드를 수정하지 않고도 Datadog와 함께 ClickStack을 평가할 수 있으며, 기존 에이전트를 사용해 동일한 텔레메트리를 두 플랫폼으로 모두 전송할 수 있습니다.
현재 수집 계층은 그대로 유지하면서 ClickStack으로 이전하고, OpenTelemetry 계측은 점진적으로 도입하여 마이그레이션을 수월하게 진행할 수 있습니다.
장기적으로 두 스택을 병렬로 운영하면서 각 플랫폼의 강점을 살려 활용할 수 있습니다.

Datadog와 함께 ClickStack을 실행해야 하는 이유

대부분의 팀이 관측성 데이터를 Datadog에서 옮기려는 가장 큰 이유는 비용입니다. 애플리케이션이 확장되고 더 많은 서비스에 계측이 적용될수록 로그와 트레이스 볼륨은 계속 증가하고, 결국 비용을 더 지불하거나 생성한 텔레메트리를 덜 보관하는 것 중 하나를 선택해야 합니다. 그리고 이러한 비용 통제는 조사 과정에서 확인할 수 있는 범위도 제한합니다. 샘플링된 트레이스, 인덱싱되지 않은 로그, 롤업된 메트릭, 짧은 보존 기간은 모두 가장 필요한 순간에 활용할 수 있는 맥락 정보를 줄입니다. ClickStack은 ClickHouse를 기반으로 구축되었으며, 대규모 로그 및 트레이싱 워크로드에서는 Datadog보다 100배 이상 높은 비용 효율을 제공할 수 있습니다. 바로 이러한 저장 비용의 차이 때문에 Datadog와 함께 ClickStack을 실행할 가치가 있습니다.

더 긴 보존 기간. 예산이 아니라 운영 요구사항에 맞춰 보존 기간을 설정하고, 몇 주 또는 몇 달 뒤에 필요할 수 있는 이벤트도 보관할 수 있습니다.
완전한 원본 데이터. 샘플링 없이 모든 로그와 트레이스를 저장하므로, 부분 집합이 아니라 전체 데이터를 기준으로 조사를 수행할 수 있습니다.
API 속도 제한 없음. 사용량 기반 API를 거치지 않고 텔레메트리를 데이터베이스처럼 쿼리할 수 있으며, 쿼리별 또는 endpoint별 스로틀링도 없습니다.
완전한 SQL 액세스. 로그, 메트릭, 트레이스를 SQL로 분석하고, 이미 ClickHouse에 있는 비즈니스 데이터나 인프라 데이터와 조인할 수 있습니다.
에이전트형 워크로드. ClickStack MCP server를 통해 텔레메트리를 AI 에이전트에 노출하고, ClickHouse에 직접 무제한 분석 쿼리를 실행할 수 있습니다.

완전한 원본 텔레메트리는 에이전트형 조사에서 특히 큰 가치를 가집니다. 조사가 시작되기 전에 버려진 이벤트에 대해서는 에이전트가 추론할 수 없으며, 현재의 incident를 이전 장애, 동작 변화, 장기적으로 나타나는 패턴과 비교할 수 있을 만큼 충분한 이력이 필요합니다.

Datadog 수신기 작동 방식

일반적인 OpenTelemetry 배포에서는 텔레메트리 데이터가 백엔드에 도달하기 전에 OpenTelemetry collector로 전송됩니다. collector는 agent 모드 collector와 애플리케이션을 계측하는 OpenTelemetry SDKs로부터 데이터를 수신하고, 필요한 필터링이나 변환을 적용한 뒤, 이벤트를 배치로 묶어 대상에 내보냅니다. Datadog 수신기는 이 아키텍처에 또 다른 입력 경로를 추가합니다. Datadog agent와 SDK가 사용하는 프로토콜을 이해하는 endpoint를 제공하고, 들어오는 Datadog payload를 OpenTelemetry 데이터 모델로 변환합니다. 이후에는 다른 텔레메트리와 마찬가지로 일반적인 collector pipeline을 거칩니다. 기존 Datadog 에이전트는 ClickStack collector에서 실행 중인 수신기로 logs와 트레이스를 보내도록 간단히 재구성하면 됩니다. 애플리케이션은 기존 Datadog SDK를 그대로 사용할 수 있으며, 인프라 전반에 이미 배포된 agent도 그대로 유지됩니다. collector pipeline은 둘 이상의 exporter를 사용할 수 있으므로, 동일한 텔레메트리를 Datadog와 ClickStack으로 동시에 보낼 수 있습니다. 따라서 두 플랫폼을 동일한 데이터로 비교하면서 나란히 평가하고 장기간 병행 운영할 수 있습니다. 그런 다음 마이그레이션 여부는 별도로 결정하면 됩니다.

수신기가 처리하는 내용

수신기는 Datadog 전용 로직 없이도 ClickStack이 데이터를 해석하고, 연관시키고, 쿼리할 수 있도록 Datadog payload를 올바른 OpenTelemetry 표현으로 변환합니다.

로그 레코드. Datadog의 밀리초 단위 timestamp는 나노초로 변환되어 OpenTelemetry의 timestamp, observed timestamp, body, severity 필드를 채우는 데 사용되므로, 레코드가 더 이상 Unix epoch에 표시되지 않습니다.
리소스 속성과 심각도. info, warn, error와 같은 Datadog status는 해당하는 OpenTelemetry SeverityNumber 및 SeverityText에 매핑됩니다. 호스트명, 서비스 이름, 환경, 그리고 잘 알려진 컨테이너, Cloud, Kubernetes tag는 표준 리소스 속성으로 승격됩니다.
트레이스와 로그의 연관 관계. dd.trace_id 및 dd.span_id 필드는 OpenTelemetry의 트레이스 및 스팬 식별자를 채우며, 수신기는 Datadog의 분할된 표현으로부터 전체 128-bit 트레이스 ID를 재구성합니다. 이 기능은 기본적으로 활성화되어 있으므로 Datadog에서 수집된 로그와 스팬을 OpenTelemetry로 instrument된 서비스와 연관시킬 수 있습니다.
구조화된 JSON 로그. 기본적으로 활성화되는 decode_json_message 옵션은 일반적으로 Datadog backend에서 수행되는 JSON 처리를 수행하여 body, timestamp, severity, 트레이스 식별자, 리소스 필드, 그리고 나머지 속성을 추출합니다.
현재 agent와의 호환성. Datadog Agent 7.59 이상은 기본적으로 HTTP payload를 Zstandard로 압축합니다. 수신기는 gzip과 함께 Zstandard도 지원하므로 현재 agent가 payload 거부 없이 연결할 수 있습니다.

이러한 변경 사항은 ClickStack collector 배포판에 포함되어 자동으로 구성되며, OpenTelemetry Collector Contrib 프로젝트에서도 사용할 수 있습니다.

Datadog 수신기 활성화

Datadog 수신기는 ClickStack 배포에 포함된 OpenTelemetry collector에서 제공되며, 포트 8126에서 수신 대기합니다. 기본적으로는 비활성화되어 있으며, ENABLE_DATADOG_RECEIVER 환경 변수를 설정해 활성화할 수 있습니다. 활성화한 후에는 Datadog 에이전트가 이 수신기로 데이터를 보내도록 구성하고, ClickStack 수집 키로 인증을 설정합니다. 이 키를 어디서 가져오는지는 배포 방식에 따라 다릅니다. Managed ClickStack에서는 독립 실행형 collector를 실행하고 시작할 때 키를 직접 설정합니다. 반면 Open Source ClickStack에서는 키가 자동으로 생성되며 ClickStack 인터페이스(HyperDX)에서 복사하면 됩니다. 아래에서 배포 방식을 선택하십시오.

관리형 ClickStack
오픈소스 ClickStack

관리형 ClickStack에서는 ClickHouse Cloud 서비스로 데이터를 수집하는 독립 실행형 ClickStack collector를 배포합니다. collector는 시작 시 사용자가 선택한 인증 토큰으로 보호하며, 동일한 토큰을 Datadog agent의 API Key로 재사용합니다.

수신기를 활성화한 collector 배포

ClickStack OpenTelemetry collector와 표준 OpenTelemetry collector의 차이Datadog 수신기는 ClickStack 배포판 OpenTelemetry collector에 기본 포함되어 있으며 사전 구성되어 있습니다. 표준 OpenTelemetry Collector Contrib 배포판을 사용하려면 수신기를 직접 구성해야 합니다. 수신기에 대한 변경 사항과 개선 사항은 모두 upstream에 반영되므로 해당 배포판에서도 사용할 수 있습니다. 구성 옵션은 Datadog receiver README를 참조하십시오.

독립 실행형 ClickStack collector를 실행하고 ClickHouse Cloud 서비스를 가리키도록 설정하십시오. ENABLE_DATADOG_RECEIVER=true로 Datadog 수신기를 활성화하고, 포트 8126을 노출한 다음, 사용자 지정 OTLP_AUTH_TOKEN을 설정해 수집을 보호하십시오.

export CLICKHOUSE_ENDPOINT=<HTTPS_ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>
export OTLP_AUTH_TOKEN="a_very_secure_string"

docker run --name clickstack-collector \
  -e ENABLE_DATADOG_RECEIVER=true \
  -e OTLP_AUTH_TOKEN=${OTLP_AUTH_TOKEN} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  clickhouse/clickstack-otel-collector:latest

이제 수신기는 http://localhost:8126에서 사용할 수 있으며, OTLP_AUTH_TOKEN에 설정한 토큰이 Datadog agent에 전달할 키입니다. Helm에서의 동일한 설정을 포함해 collector 보안 설정에 관한 자세한 내용은 “collector 보안 설정”을 참조하십시오.

Datadog agent 구성

logs, traces, metrics를 수신기로 보내도록 /opt/datadog-agent/etc/datadog.yaml의 agent 설정 파일을 업데이트하십시오. OTLP_AUTH_TOKEN 값을 API Key로 사용하고 각 대상을 수신기 endpoint로 지정하십시오.

api_key: "<YOUR_OTLP_AUTH_TOKEN>"

# 메트릭 대상
dd_url: "http://localhost:8126"

# 현재 ClickStack은 Datadog v2 메트릭 수집 endpoint를 지원합니다.
use_v3_api:
  series:
    enabled: false

# trace 대상
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# 로그 대상
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# 이는 Datadog backend가 필요하지만 여기서는 사용하지 않으므로 비활성화합니다.
remote_updates: false

remote_configuration:
  enabled: false

이 구성은 다음을 수행합니다.

metrics, traces, logs를 Datadog 대신 수신기로 전송합니다.
ClickStack이 Datadog v2 metrics endpoint를 지원하므로 v3 metrics intake를 비활성화합니다.
Datadog backend에 의존하는 remote updates와 remote configuration을 비활성화합니다.

agent 재시작

Datadog agent를 재시작하여 새 구성을 적용하십시오. macOS에서는 다음 명령을 사용합니다.

sudo launchctl kickstart -k system/com.datadoghq.agent

이제 agent의 telemetry가 ClickStack으로 수집되며, HyperDX에서 확인할 수 있습니다.

Open Source ClickStack에서는 스택 배포 시 생성되는 수집 key를 사용해 collector가 엔드포인트를 보호합니다. 수신기를 활성화한 다음 ClickStack 인터페이스(HyperDX)에서 해당 key를 복사하여 Datadog agent의 API key로 사용합니다.

수신기가 활성화된 collector 시작

아래 예시에서는 all-in-one image를 사용합니다. 다른 배포 모델을 사용하는 경우에도 collector를 실행하는 컨테이너에 동일한 flag가 적용되었는지 확인하십시오.ENABLE_DATADOG_RECEIVER=true를 설정하고 포트 8126을 노출합니다:

docker run --name clickstack \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

이제 수신기는 http://localhost:8126에서 사용할 수 있습니다.

로컬 Datadog agent 실행Datadog agent도 포트 8126에서 수신 대기합니다. agent가 collector와 같은 호스트에서 실행 중이면 충돌을 방지하기 위해 collector를 다른 호스트 포트에 매핑하십시오. 예를 들어 -p 18126:8126을 사용하고, agent가 대신 해당 포트를 가리키도록 구성하십시오.

나머지 설정 과정은 오픈 소스 시작하기 가이드에 설명된 대로 완료하십시오.

수집 API key 복사

ClickStack 인터페이스(HyperDX)에서 왼쪽 하단의 사용자를 선택하고 Team Settings > API Keys로 이동한 다음 Ingestion API Key를 복사합니다.

Datadog agent 구성

로그, trace, 메트릭을 수신기로 보내도록 /opt/datadog-agent/etc/datadog.yaml의 agent 설정 파일을 업데이트합니다. ClickStack 수집 key를 API key로 사용하고 각 대상을 수신기 엔드포인트로 지정합니다:

api_key: "<YOUR_CLICKSTACK_INGESTION_KEY>"

# 메트릭 대상
dd_url: "http://localhost:8126"

# ClickStack은 현재 Datadog v2 메트릭 수집만 지원합니다.
use_v3_api:
  series:
    enabled: false

# Trace 대상
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# 로그 대상
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# 이 기능은 Datadog backend가 필요하지만 여기서는 사용하지 않으므로 비활성화합니다.
remote_updates: false

remote_configuration:
  enabled: false

이 구성은 다음을 수행합니다:

메트릭, trace, 로그를 Datadog 대신 수신기로 보냅니다.
수신기가 Datadog v2 메트릭 엔드포인트를 지원하므로 v3 메트릭 수집을 비활성화합니다.
Datadog backend에 의존하는 remote updates와 remote configuration을 비활성화합니다.

agent 재시작

Datadog agent를 재시작하여 새 구성을 적용합니다. macOS에서는 다음을 실행합니다:

sudo launchctl kickstart -k system/com.datadoghq.agent

이제 agent의 telemetry가 ClickStack으로 수집되며, HyperDX에서 이를 탐색할 수 있습니다.

실습 예시

다음 예시에서는 샘플 애플리케이션을 사용해, 계측이 적용된 앱에서 Datadog 에이전트를 거쳐 ClickStack으로 이어지는 전체 흐름을 보여줍니다.

샘플 앱 클론 및 실행

이 예시에서는 datadog-instrumentation 브랜치에서 Datadog 계측이 적용된 Hacker News 데모 앱을 사용합니다. 해당 브랜치를 클론합니다:

git clone --branch datadog-instrumentation https://github.com/ClickHouse/hn-news-analyzer.git

앱을 실행하려면 README의 안내를 따르십시오.

수신기를 활성화하여 ClickStack 실행

Datadog 수신기가 활성화된 all-in-one 이미지를 시작합니다. 여기서는 수신기를 호스트 포트 18126에 매핑하여, 동일하게 8126을 사용하는 로컬 Datadog 에이전트와 충돌하지 않도록 합니다:

docker run --name clickstack \
  -p 8080:8080 \
  -p 8123:8123 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 127.0.0.1:18126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

수신기는 http://127.0.0.1:18126에서 사용할 수 있습니다.

Datadog agent 설치 및 구성

Datadog 에이전트를 설치합니다. macOS에서는 다음 명령을 사용합니다:

DD_SITE="datadoghq.com" bash -c "$(curl -L https://install.datadoghq.com/scripts/install_mac_os.sh)"

/opt/datadog-agent/etc/datadog.yaml을 업데이트하여 포트 18126의 수신기를 가리키도록 설정하고, ClickStack 수집 키를 API Key로 사용한 뒤 agent를 다시 시작합니다:

sudo launchctl kickstart -k system/com.datadoghq.agent

전체 agent 구성과 수집 키를 확인하는 방법은 Datadog 수신기 활성화를 참조하십시오.

ClickStack에서 텔레메트리 탐색

http://localhost:8080에서 HyperDX 인터페이스를 열고 Datadog 에이전트에서 수집된 트레이스, 로그, 메트릭을 살펴보십시오.

현재 마이그레이션할 수 있는 항목

Datadog 수신기는 OpenTelemetry Collector Contrib의 알파 구성 요소이며, ClickStack collector 배포판에서는 실험적 기능으로 표시되어 있으므로 활성화하려면 기능 플래그가 필요합니다. 이 수신기는 로그 및 트레이스 워크로드를 중심으로 광범위하게 테스트되었으며, 이러한 시그널로 ClickStack을 평가할 때 권장됩니다. 메트릭도 작동하지만 추가적인 테스트와 개발이 필요합니다. 현재 이 수신기는 Datadog의 v1 및 v2 메트릭 수집 엔드포인트를 지원하며, 더 최신 프로토콜 버전을 사용하는 에이전트는 지원되는 엔드포인트를 통해 메트릭을 전송하도록 명시적으로 구성해야 합니다. 현재로서는 애플리케이션이 이미 Datadog SDKs를 사용하거나 인프라에서 Datadog 에이전트를 실행 중인 경우, 이 수신기를 사용해 ClickStack을 빠르게 평가할 수 있습니다. 두 파이프라인을 병렬로 실행하고, 데이터가 ClickStack에서 어떻게 표현되고 쿼리되는지 검증한 다음, 더 광범위한 마이그레이션을 진행할지 결정하십시오. 평가 결과 명확한 이점이 확인되면 동일한 아키텍처를 사용해 점진적인 마이그레이션도 진행할 수 있으며, 기존 Datadog 인스트루멘테이션은 그대로 유지한 채 시간이 지나면서 서비스를 OpenTelemetry로 옮길 수 있습니다.

​Datadog와 함께 ClickStack을 실행해야 하는 이유

​Datadog 수신기 작동 방식

​수신기가 처리하는 내용

​Datadog 수신기 활성화

​실습 예시

​현재 마이그레이션할 수 있는 항목

Datadog와 함께 ClickStack을 실행해야 하는 이유

Datadog 수신기 작동 방식

수신기가 처리하는 내용

Datadog 수신기 활성화

실습 예시

현재 마이그레이션할 수 있는 항목