관리형

Beta feature. Learn more.

베타 기능

이 기능은 현재 ClickHouse Cloud 베타 단계에 있습니다.

이 가이드는 기존 ClickHouse Cloud 사용자를 위한 것입니다. ClickHouse Cloud가 처음이라면, Managed ClickStack용 시작하기 가이드를 참고하기를 권장합니다.

이 배포 패턴에서는 ClickHouse와 ClickStack UI(HyperDX) 모두 ClickHouse Cloud에서 호스팅되며, 사용자가 자체적으로 호스팅해야 하는 구성 요소의 수를 최소화합니다.

인프라 관리 부담을 줄여 줄 뿐만 아니라, 이 배포 패턴은 인증이 ClickHouse Cloud SSO/SAML과 통합되도록 보장합니다. 셀프 호스팅 배포와 달리, 대시보드, 저장된 검색, 사용자 설정, 알림과 같은 애플리케이션 상태를 저장하기 위한 MongoDB 인스턴스를 프로비저닝할 필요도 없습니다. 또한 다음과 같은 이점이 있습니다.

• 스토리지와 독립적인 컴퓨트 리소스의 자동 확장
• 객체 스토리지를 기반으로 한 저비용의 사실상 무제한 보존 기간
• Warehouses를 사용하여 읽기 및 쓰기 워크로드를 서로 분리해 격리할 수 있는 기능
• 통합 인증
• 자동 백업
• 보안 및 규정 준수 기능
• 중단 없는 업그레이드

이 모드에서는 데이터 수집이 전적으로 사용자 책임입니다. 사용자가 호스팅하는 OpenTelemetry collector, 클라이언트 라이브러리에서의 직접 수집, Kafka 또는 S3와 같은 ClickHouse 네이티브 테이블 엔진, ETL 파이프라인, 또는 ClickHouse Cloud의 관리형 수집 서비스인 ClickPipes를 사용하여 Managed ClickStack으로 데이터를 수집할 수 있습니다. 이 방식은 ClickStack을 운영하기 위한 가장 단순하면서도 성능이 뛰어난 방법을 제공합니다.

적합한 경우

이 배포 패턴은 다음과 같은 시나리오에 적합합니다.

1. 이미 ClickHouse Cloud에 관측성 데이터가 있으며, 이를 ClickStack을 사용해 시각화하고자 하는 경우.
2. 대규모 관측성 배포를 운영 중이며, ClickHouse Cloud에서 실행되는 ClickStack의 전용 성능과 확장성이 필요한 경우.
3. 이미 분석용으로 ClickHouse Cloud를 사용 중이며, ClickStack 계측 라이브러리를 사용해 애플리케이션을 계측하고 동일한 클러스터로 데이터를 전송하고자 하는 경우. 이때는 관측성 워크로드용 컴퓨트를 분리하기 위해 warehouses를 사용할 것을 권장합니다.

설정 단계

이 가이드는 이미 ClickHouse Cloud 서비스를 생성했다고 가정합니다. 아직 서비스를 생성하지 않았다면 Managed ClickStack용 시작하기 가이드를 따르십시오. 이 과정을 마치면 이 가이드와 동일한 상태, 즉 ClickStack이 활성화되어 관측성 데이터를 수집할 준비가 된 서비스가 생성됩니다.

새 서비스를 생성하십시오.

새 서비스 생성

ClickHouse Cloud 랜딩 페이지에서 New service를 선택하여 새 서비스를 생성합니다.

프로바이더, 리전 및 리소스 지정

Scale vs Enterprise

대부분의 ClickStack 워크로드에는 이 Scale 티어를 권장합니다. SAML, CMEK, HIPAA 컴플라이언스와 같은 고급 보안 기능이 필요하다면 Enterprise 티어를 선택하십시오. Enterprise 티어는 매우 대규모 ClickStack 배포를 위한 맞춤형 하드웨어 프로필도 제공합니다. 이러한 경우에는 지원팀에 문의하시기 바랍니다.

Cloud 공급자와 리전을 선택합니다.

CPU와 메모리를 지정할 때에는 예상 ClickStack 수집 처리량을 기준으로 산정하십시오. 아래 표는 이러한 리소스 규모를 결정하는 데 참고할 수 있는 가이드를 제공합니다.

월별 수집량	권장 컴퓨트 리소스
< 10 TB / month	2 vCPU × 3 레플리카
10–50 TB / month	4 vCPU × 3 레플리카
50–100 TB / month	8 vCPU × 3 레플리카
100–500 TB / month	30 vCPU × 3 레플리카
1 PB+ / month	59 vCPU × 3 레플리카

이 권장 사항은 다음과 같은 가정을 기반으로 합니다.

• 데이터 볼륨은 한 달 기준 압축되지 않은 수집량을 의미하며, 로그와 트레이스 모두에 적용됩니다.
• 쿼리 패턴은 관측성 사용 사례에서 일반적인 형태이며, 대부분의 쿼리는 보통 최근 24시간과 같은 최신 데이터를 대상으로 합니다.
• 수집은 한 달 동안 비교적 균일하게 발생한다고 가정합니다. 버스트 트래픽이나 스파이크가 예상된다면 추가 여유 용량을 확보해야 합니다.
• 스토리지는 ClickHouse Cloud 객체 스토리지를 통해 별도로 처리되며, 보존 기간을 제한하는 요소가 아닙니다. 장기간 보존되는 데이터는 드물게 조회된다고 가정합니다.

더 긴 기간을 자주 조회하거나, 무거운 집계 작업을 수행하거나, 동시 접속 사용자가 많은 액세스 패턴을 지원하려면 더 많은 컴퓨트 리소스가 필요할 수 있습니다.

두 개의 레플리카로도 주어진 수집 처리량에 필요한 CPU와 메모리 요구 사항을 충족할 수 있지만, 가능한 경우에는 동일한 총 용량을 유지하면서 서비스 중복성을 높이기 위해 세 개의 레플리카 사용을 권장합니다.

참고

이 값들은 추정치일 뿐이며 초기 기준선으로만 사용해야 합니다. 실제 요구 사항은 쿼리 복잡도, 동시성, 보존 정책, 수집 처리량 변동에 따라 달라집니다. 리소스 사용량을 항상 모니터링하고 필요에 따라 확장하십시오.

요구 사항을 지정한 후 Managed ClickStack 서비스가 프로비저닝되는 데 몇 분 정도 소요됩니다. 프로비저닝을 기다리는 동안 ClickHouse Cloud 콘솔의 다른 부분을 탐색하십시오.

프로비저닝이 완료되면 왼쪽 메뉴의 'ClickStack' 옵션이 활성화됩니다.

수집 설정

서비스가 프로비저닝 완료된 후 해당 서비스가 선택되어 있는지 확인한 다음, 왼쪽 메뉴에서 「ClickStack」을 클릭합니다.

「Start Ingestion」을 선택하면 수집 소스를 선택하라는 메시지가 표시됩니다. Managed ClickStack은 주요 수집 소스로 OpenTelemetry와 Vector를 지원합니다. 또한 사용자는 ClickHouse Cloud support integrations를 사용해 자체 스키마로 데이터를 ClickHouse에 직접 전송할 수도 있습니다.

OpenTelemetry 권장

수집 포맷으로 OpenTelemetry를 사용하는 것을 강력히 권장합니다. 가장 간단하고 최적화된 사용 경험을 제공하며, ClickStack과 효율적으로 동작하도록 특별히 설계된 기본 제공 스키마를 제공합니다.

OpenTelemetry

Managed ClickStack로 OpenTelemetry 데이터를 보내기 위해서는 OpenTelemetry Collector 사용이 권장됩니다. Collector는 애플리케이션(및 다른 collector)에서 OpenTelemetry 데이터를 수신하고 이를 ClickHouse Cloud로 전달하는 게이트웨이 역할을 합니다.

Collector가 이미 실행 중이 아니라면 아래 단계를 따라 collector를 시작하십시오. 이미 collector가 있는 경우를 위해 구성 예제도 제공됩니다.

Collector 시작

다음 내용은 OpenTelemetry Collector의 ClickStack 배포판 사용을 권장하는 경로를 전제로 합니다. 이 배포판에는 추가 처리 기능이 포함되어 있으며 ClickHouse Cloud에 특화되어 최적화되어 있습니다. 자체 OpenTelemetry Collector를 사용하려는 경우 "기존 collector 구성"을 참고하십시오.

빠르게 시작하려면 표시된 Docker 명령을 복사하여 실행하십시오.

이 명령에는 연결 자격 증명이 미리 채워져 있어야 합니다.

프로덕션 배포

이 명령은 Managed ClickStack에 연결하기 위해 default 사용자를 사용하지만, 프로덕션으로 전환할 때는 전용 사용자를 생성하고 구성을 수정하는 것이 좋습니다.

이 단일 명령을 실행하면 OTLP 엔드포인트를 포트 4317(gRPC)과 4318(HTTP)에 노출하는 ClickStack collector가 시작됩니다. 이미 OpenTelemetry 계측 및 에이전트가 있다면, 즉시 이 엔드포인트로 텔레메트리 데이터를 전송할 수 있습니다.

기존 collector 구성

기존 OpenTelemetry Collector를 구성하거나 자체 배포판을 사용하는 것도 가능합니다.

ClickHouse exporter 필요

예를 들어 contrib 이미지와 같은 자체 배포판을 사용하는 경우, 해당 이미지에 ClickHouse exporter가 포함되어 있는지 확인하십시오.

이를 위해 ClickHouse exporter를 적절한 설정과 함께 사용하고 OTLP 리시버를 노출하는 예제 OpenTelemetry Collector 구성이 제공됩니다. 이 구성은 ClickStack 배포판에서 기대하는 인터페이스와 동작에 맞춰져 있습니다.

아래는 이 구성의 예시입니다(UI에서 복사하면 환경 변수가 미리 입력됩니다).

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

OpenTelemetry collector 구성에 대한 자세한 내용은 "OpenTelemetry를 사용한 수집"을 참고하십시오.

수집 시작(선택 사항)

OpenTelemetry로 계측할 기존 애플리케이션이나 인프라가 있는 경우, UI에서 연결된 관련 가이드로 이동하십시오.

애플리케이션을 계측하여 트레이스와 로그를 수집하려면, 데이터를 OpenTelemetry Collector로 전송하는 지원 언어 SDKs를 사용하십시오. 이 Collector는 Managed ClickStack으로의 수집을 위한 게이트웨이 역할을 합니다.

로그는 에이전트 모드로 실행되며 동일한 collector로 데이터를 전달하는 OpenTelemetry Collector를 사용해 수집할 수 있습니다. Kubernetes 모니터링의 경우 전용 가이드를 따르십시오. 다른 통합에 대해서는 빠른 시작 가이드를 참고하십시오.

데모 데이터

또는 기존 데이터가 없다면 샘플 데이터셋 중 하나를 사용해 보십시오.

• 예제 데이터셋 - 공개 데모에서 예제 데이터셋을 로드하여 간단한 문제를 진단해 보십시오.
• 로컬 파일 및 메트릭 - 로컬 OTel collector를 사용하여 OSX 또는 Linux에서 로컬 파일을 로드하고 시스템을 모니터링합니다.

Vector

Vector는 고성능의 벤더 중립적 관측성(observability) 데이터 파이프라인으로, 유연성과 낮은 리소스 사용량 덕분에 특히 로그 수집(ingestion)에 많이 사용됩니다.

Vector를 ClickStack과 함께 사용할 때는 사용자가 직접 스키마를 정의해야 합니다. 이 스키마는 OpenTelemetry 규약을 따를 수도 있지만, 사용자 정의 이벤트 구조를 표현하는 완전히 사용자 정의 스키마일 수도 있습니다.

타임스탬프 필수

Managed ClickStack에서 유일하게 엄격한 요구 사항은 데이터에 타임스탬프 컬럼(timestamp column)(또는 이에 상응하는 시간 필드)이 포함되어 있어야 한다는 점이며, 이는 ClickStack UI에서 데이터 소스를 구성할 때 선언할 수 있습니다.

아래 내용에서는 Vector 인스턴스가 이미 실행 중이며, 수집 파이프라인이 사전에 구성되어 데이터를 전달하고 있다고 가정합니다.

데이터베이스와 테이블 생성

Vector를 사용하려면 데이터 수집 전에 테이블과 스키마가 정의되어 있어야 합니다.

먼저 데이터베이스를 생성합니다. 이는 ClickHouse Cloud console을 통해 수행할 수 있습니다.

예를 들어, 로그용 데이터베이스를 생성합니다:

CREATE DATABASE IF NOT EXISTS logs

그런 다음 로그 데이터 구조에 맞는 스키마를 가진 테이블을 CREATE 합니다. 아래 예시는 일반적인 Nginx access log 형식을 가정합니다:

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr);

테이블은 Vector가 생성하는 출력 스키마와 일치해야 합니다. 권장되는 스키마 모범 사례를 참고하여 데이터에 맞게 스키마를 조정하십시오.

ClickHouse에서 Primary keys가 어떻게 동작하는지 이해하고, 액세스 패턴에 따라 정렬 키를 선택할 것을 강력히 권장합니다. 기본 키 선택에 대한 지침은 ClickStack 전용 가이드를 참고하십시오.

테이블을 생성한 후 표시된 구성 스니펫을 복사하십시오. 필요한 경우 기존 파이프라인을 입력으로 사용하도록 조정하고, 대상 테이블과 데이터베이스를 수정하십시오. 자격 증명 정보는 미리 채워져 있어야 합니다.

Vector로 데이터를 수집하는 추가 예시는 "Vector로 수집하기" 또는 고급 옵션을 위한 Vector ClickHouse sink 문서를 참고하십시오.

ClickStack UI로 이동

'Launch ClickStack'를 선택하여 ClickStack UI(HyperDX)에 액세스합니다. 자동으로 인증된 후 리디렉션됩니다.

OpenTelemetry

OpenTelemetry 데이터에 대해서는 데이터 소스가 미리 생성되어 있습니다.

Vector

Vector를 사용하는 경우 데이터 소스를 직접 생성해야 합니다. 첫 로그인 시 데이터 소스를 생성하라는 안내가 표시됩니다. 아래에는 로그 데이터 소스 예제 구성을 보여 줍니다.

이 구성은 time_local 컬럼을 타임스탬프로 사용하는 Nginx 스타일 스키마를 가정합니다. 가능하다면 기본 키에 선언된 타임스탬프 컬럼을 사용해야 합니다. 이 컬럼은 필수입니다.

또한 로그 뷰에서 반환할 컬럼을 명시적으로 정의하도록 Default SELECT를 수정하는 것을 권장합니다. 서비스 이름, 로그 레벨, 본문 컬럼 등 추가 필드가 있다면 이들도 함께 구성할 수 있습니다. 타임스탬프 표시 컬럼이 테이블 기본 키에 사용된 컬럼과 다를 경우, 위에서 구성한 것과 별도로 이 컬럼을 재정의할 수도 있습니다.

위 예제에서는 데이터에 Body 컬럼이 존재하지 않습니다. 대신 사용 가능한 필드를 이용해 Nginx 로그 라인을 재구성하는 SQL 표현식으로 해당 컬럼을 정의합니다.

사용할 수 있는 다른 옵션은 구성 레퍼런스를 참조하십시오.

데이터 소스를 생성한 후에는 검색 뷰로 이동하며, 즉시 데이터를 탐색할 수 있습니다.

이것으로 모든 준비가 완료되었습니다. 🎉

이제 ClickStack을 탐색해 보십시오. 로그와 트레이스를 검색하고, 로그·트레이스·메트릭이 실시간으로 어떻게 연관되는지 확인하며, 대시보드를 구성하고, 서비스 맵을 탐색하고, 이벤트 델타와 패턴을 분석하고, 경보를 설정하여 문제를 선제적으로 감지하십시오.

기존 서비스 사용

서비스를 선택하세요

ClickHouse Cloud 랜딩 페이지에서 관리형 ClickStack을 활성화할 서비스를 선택하십시오.

리소스 예측

이 가이드는 ClickStack으로 수집하고 쿼리할 관측성 데이터의 양을 처리하기에 충분한 리소스를 프로비저닝했다고 가정합니다. 필요한 리소스를 예측하려면 프로덕션 가이드를 참조하세요.

ClickHouse 서비스가 실시간 애플리케이션 분석과 같은 기존 워크로드를 이미 호스팅하고 있는 경우, ClickHouse Cloud의 웨어하우스 기능을 사용하여 하위 서비스를 생성하고 관측성 워크로드를 격리하는 것을 권장합니다. 이를 통해 기존 애플리케이션의 중단 없이 두 서비스 모두에서 데이터셋에 액세스할 수 있습니다.

ClickStack UI로 이동

왼쪽 탐색 메뉴에서 'ClickStack'을 선택하세요. ClickStack UI로 리디렉션되며 ClickHouse Cloud 권한을 기반으로 자동으로 인증됩니다.

서비스에 OpenTelemetry 테이블이 이미 존재하는 경우, 자동으로 감지되며 해당 데이터 소스가 생성됩니다.

데이터 소스 자동 감지

자동 감지는 ClickStack 배포판의 OpenTelemetry 수집기에서 제공하는 표준 OpenTelemetry 테이블 스키마를 기반으로 합니다. 가장 완전한 테이블 세트를 보유한 데이터베이스에 대해 소스가 생성됩니다. 필요한 경우 추가 테이블을 별도의 데이터 소스로 추가할 수 있습니다.

자동 감지가 성공하면 검색 뷰로 이동되며, 즉시 데이터 탐색을 시작할 수 있습니다.

이 단계가 성공하면 모든 설정이 완료된 것입니다 🎉. 그렇지 않은 경우 수집 설정을 진행하세요.

수집 설정하기

자동 감지가 실패하거나 기존 테이블이 없는 경우, 수집을 설정하라는 메시지가 표시됩니다.

"Start Ingestion"을 선택하면 수집 소스를 선택하라는 메시지가 표시됩니다. 관리형 ClickStack은 OpenTelemetry와 Vector를 주요 수집 소스로 지원합니다. 또한 ClickHouse Cloud 지원 통합을 사용하여 자체 스키마로 ClickHouse에 직접 데이터를 전송할 수도 있습니다.

OpenTelemetry 권장

수집 형식으로 OpenTelemetry 사용을 강력히 권장합니다. ClickStack과 효율적으로 작동하도록 특별히 설계된 기본 제공 스키마를 통해 가장 간단하고 최적화된 환경을 제공합니다.

OpenTelemetry

Managed ClickStack로 OpenTelemetry 데이터를 전송하려면 OpenTelemetry Collector 사용이 권장됩니다. Collector는 애플리케이션(및 다른 collector)에서 OpenTelemetry 데이터를 수신하고 이를 ClickHouse Cloud로 전달하는 게이트웨이 역할을 합니다.

Collector가 아직 실행 중이 아니라면 아래 단계를 따라 Collector를 시작하십시오. 이미 Collector를 사용 중인 경우에도 참고할 수 있는 구성 예제가 제공됩니다.

Collector 시작

다음 내용은 OpenTelemetry Collector에 대한 ClickStack 배포판 사용을 권장하는 경로를 전제로 합니다. 이 배포판에는 추가 처리 로직이 포함되어 있으며 ClickHouse Cloud에 최적화되어 있습니다. 자체 OpenTelemetry Collector를 사용하려는 경우 "기존 Collector 구성하기"를 참조하십시오.

빠르게 시작하려면 표시된 Docker 명령을 복사하여 실행하십시오.

서비스를 생성할 때 기록해 둔 서비스 자격 증명으로 이 명령을 수정하십시오.

프로덕션 배포

이 명령은 Managed ClickStack에 연결하기 위해 default 사용자를 사용하지만, 프로덕션으로 전환할 때는 전용 사용자를 생성하고 구성을 수정해야 합니다.

이 단일 명령을 실행하면 ClickStack Collector가 시작되며, OTLP 엔드포인트가 포트 4317(gRPC)과 4318(HTTP)에 노출됩니다. 이미 OpenTelemetry 계측과 에이전트를 사용 중이라면, 즉시 이 엔드포인트로 텔레메트리 데이터를 전송할 수 있습니다.

기존 Collector 구성

기존에 사용 중인 OpenTelemetry Collector를 구성하거나, 자체 배포판의 Collector를 사용할 수도 있습니다.

ClickHouse exporter 필수

contrib 이미지와 같이 자체 배포판을 사용하는 경우, ClickHouse exporter가 포함되어 있는지 반드시 확인하십시오.

이를 위해 ClickHouse exporter에 적절한 설정을 적용하고 OTLP 리시버를 노출하는 예제 OpenTelemetry Collector 구성이 제공됩니다. 이 구성은 ClickStack 배포판에서 기대하는 인터페이스와 동작을 그대로 따릅니다.

아래는 이 구성의 예시입니다(UI에서 복사하면 환경 변수가 미리 입력됩니다).

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

OpenTelemetry Collector 구성에 대한 자세한 내용은 "OpenTelemetry를 사용한 수집"을 참조하십시오.

수집 시작(선택 사항)

이미 OpenTelemetry로 계측할 애플리케이션 또는 인프라가 있는 경우, 「애플리케이션 연결」에서 연결된 관련 가이드를 확인하십시오.

애플리케이션을 계측하여 트레이스와 로그를 수집하려면 지원되는 언어 SDKs를 사용하십시오. 이 SDK는 Managed ClickStack으로의 수집을 위한 게이트웨이 역할을 하는 OpenTelemetry Collector로 데이터를 전송합니다.

로그는 에이전트 모드로 실행되며 동일한 Collector로 데이터를 전달하는 OpenTelemetry Collector를 사용해 수집할 수 있습니다. Kubernetes 모니터링의 경우 전용 가이드를 따르십시오. 그 밖의 통합 방법은 빠른 시작 가이드를 참조하십시오.

Vector

Vector는 고성능의 벤더 중립 관측성 데이터 파이프라인으로, 특히 유연성과 낮은 리소스 사용량 덕분에 로그 수집에 널리 사용됩니다.

Vector를 ClickStack과 함께 사용할 때는 스키마를 직접 정의해야 합니다. 이러한 스키마는 OpenTelemetry 컨벤션을 따를 수도 있지만, 사용자 정의 이벤트 구조를 전적으로 커스텀 형식으로 표현할 수도 있습니다.

타임스탬프 필수

Managed ClickStack에서의 유일한 엄격한 요구 사항은 데이터에 timestamp 컬럼(또는 이에 상응하는 시간 필드)이 포함되어야 한다는 점이며, 이는 ClickStack UI에서 데이터 소스를 구성할 때 선언할 수 있습니다.

다음 설명은 Vector 인스턴스가 이미 실행 중이며, 사전에 구성된 수집 파이프라인을 통해 데이터를 전달하고 있다고 가정합니다.

데이터베이스와 테이블 생성

Vector는 데이터 수집 이전에 테이블과 스키마가 정의되어 있어야 합니다.

먼저 데이터베이스를 생성합니다. 이는 ClickHouse Cloud 콘솔에서 수행할 수 있습니다.

예를 들어, 로그용 데이터베이스를 다음과 같이 생성합니다:

CREATE DATABASE IF NOT EXISTS logs

그런 다음 로그 데이터 구조에 맞는 스키마로 테이블을 생성합니다. 아래 예시는 클래식한 Nginx 액세스 로그 형식을 가정합니다.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr);

테이블은 Vector가 생성하는 출력 스키마와 일치해야 합니다. 데이터에 맞게 스키마를 필요한 대로 조정하되, 권장되는 스키마 모범 사례를 따르십시오.

ClickHouse에서 기본 키(Primary keys)가 어떻게 동작하는지 이해한 뒤, 액세스 패턴에 따라 정렬 키(ordering key)를 선택할 것을 강력히 권장합니다. 기본 키 선택에 대한 지침은 ClickStack 전용 문서를 참조하십시오.

테이블을 생성한 뒤에는 표시된 설정 스니펫을 복사하십시오. 기존 파이프라인을 입력으로 사용하도록 input을 조정하고, 필요한 경우 대상 테이블과 데이터베이스도 수정하십시오. 자격 증명은 미리 채워져 있습니다.

Vector로 데이터를 수집하는 추가 예시는 「Vector로 수집하기」 또는 고급 옵션은 Vector ClickHouse sink 문서를 참조하십시오.

ClickStack UI로 이동

수집 설정을 완료하고 데이터 전송을 시작한 후 "Next"를 선택하세요.

OpenTelemetry

이 가이드를 사용하여 OpenTelemetry 데이터를 수집한 경우, 데이터 소스는 자동으로 생성되며 추가 설정은 필요하지 않습니다. 바로 ClickStack 탐색을 시작할 수 있습니다. 검색 뷰로 이동하며, 소스가 자동으로 선택되어 즉시 쿼리를 실행할 수 있습니다.

이로써 모든 준비가 완료되었습니다 🎉.

Vector

Vector 데이터 또는 다른 소스를 통해 수집한 경우, 데이터 소스를 구성하라는 메시지가 표시됩니다.

위 구성은 time_local 컬럼을 타임스탬프로 사용하는 Nginx 스타일 스키마를 가정합니다. 가능하다면 기본 키에 선언된 타임스탬프 컬럼을 사용해야 합니다. 이 컬럼은 필수입니다.

또한 로그 뷰에서 반환되는 컬럼을 명시적으로 정의하도록 Default SELECT를 업데이트할 것을 권장합니다. 서비스 이름, 로그 레벨, 본문 컬럼 등 추가 필드를 사용할 수 있는 경우, 이들도 함께 구성할 수 있습니다. 위에서 구성한 테이블 기본 키 컬럼과 다른 컬럼을 표시용 타임스탬프로 사용하려면, 타임스탬프 표시 컬럼을 재정의할 수도 있습니다.

위 예시에서는 데이터에 Body 컬럼이 존재하지 않습니다. 대신 사용 가능한 필드로부터 Nginx 로그 라인을 재구성하는 SQL 식을 사용해 정의합니다.

다른 가능한 옵션은 configuration reference를 참고하십시오.

소스 구성이 완료되면 "Save"를 클릭하여 데이터 탐색을 시작하십시오.

추가 작업

Managed ClickStack에 대한 액세스 권한 부여

1. ClickHouse Cloud 콘솔에서 해당 서비스로 이동합니다.
2. Settings → SQL Console Access로 이동합니다.
3. 각 사용자에 대해 적절한 권한 수준을 설정합니다.
   • Service Admin → Full Access - 알림을 활성화하는 데 필요합니다.
   • Service Read Only → Read Only - 관측성 데이터를 조회하고 대시보드를 생성할 수 있습니다.
   • No access - HyperDX에 접근할 수 없습니다.

알림에는 관리자 권한이 필요합니다

알림을 활성화하려면 Service Admin 권한(SQL Console Access 드롭다운의 Full Access에 매핑됨)이 있는 사용자가 최소 한 번 HyperDX에 로그인해야 합니다. 이때 알림 쿼리를 실행하는 전용 사용자가 데이터베이스에 생성됩니다.

읽기 전용 컴퓨트로 ClickStack 사용

ClickStack UI는 읽기 전용 ClickHouse Cloud 서비스만으로도 완전히 동작합니다. 수집 워크로드와 쿼리 워크로드를 분리하려는 상황에서는 이 구성을 권장합니다.

ClickStack가 컴퓨트를 선택하는 방식

ClickStack UI는 항상 ClickHouse Cloud 콘솔에서 해당 UI를 실행한 ClickHouse 서비스에 연결합니다.

이는 다음을 의미합니다.

• 읽기 전용 서비스에서 ClickStack을 여는 경우, ClickStack UI에서 수행되는 모든 쿼리는 해당 읽기 전용 컴퓨트에서 실행됩니다.
• 읽기/쓰기 서비스에서 ClickStack을 여는 경우, ClickStack은 해당 컴퓨트를 사용합니다.

읽기 전용 동작을 보장하기 위해 ClickStack에서 추가로 구성해야 하는 사항은 없습니다.

권장 설정

읽기 전용 컴퓨트 환경에서 ClickStack을 실행하려면:

1. 웨어하우스에서 읽기 전용으로 구성된 ClickHouse Cloud 서비스를 생성하거나 선택합니다.
2. ClickHouse Cloud 콘솔에서 해당 읽기 전용 서비스를 선택합니다.
3. 왼쪽 내비게이션 메뉴에서 ClickStack을 실행합니다.

실행한 후에는 ClickStack UI가 이 읽기 전용 서비스에 자동으로 연결됩니다.

더 많은 데이터 소스 추가하기

ClickStack은 OpenTelemetry를 네이티브로 지원하지만 OpenTelemetry 전용은 아니므로, 필요하다면 자체 테이블 스키마를 사용할 수도 있습니다.

다음에서는 자동으로 구성되는 데이터 소스 외에 추가 데이터 소스를 추가하는 방법을 설명합니다.

OpenTelemetry 스키마 사용

OTel collector를 사용하여 ClickHouse 내에서 데이터베이스와 테이블을 생성하는 경우, 소스 생성 화면의 기본값은 모두 유지하고, 로그 소스를 생성하려면 Table 필드에 otel_logs 값을 입력하십시오. 다른 모든 설정은 자동으로 감지되므로 Save New Source를 클릭하면 됩니다.

트레이스와 OTel 메트릭에 대한 소스를 생성하려면 상단 메뉴에서 Create New Source를 선택하십시오.

여기에서 필요한 소스 유형을 선택한 다음, 해당하는 테이블을 선택하십시오. 예를 들어 트레이스의 경우 otel_traces 테이블을 선택합니다. 모든 설정은 자동으로 감지됩니다.

소스 상관관계 설정

ClickStack의 서로 다른 데이터 소스(예: 로그와 트레이스)는 서로 연관될 수 있습니다. 이를 활성화하려면 각 소스마다 추가 구성이 필요합니다. 예를 들어 로그 소스에서는 해당하는 트레이스 소스를 지정할 수 있고, 반대로 트레이스 소스에서도 로그 소스를 지정할 수 있습니다. 자세한 내용은 "상관관계 소스"를 참조하십시오.

사용자 지정 스키마 사용

기존 서비스에 이미 존재하는 데이터와 ClickStack을 연결하려는 경우, 필요에 따라 데이터베이스와 테이블 설정을 완료합니다. 테이블이 ClickHouse용 OpenTelemetry 스키마를 준수하는 경우 설정은 자동으로 감지됩니다.

사용자 지정 스키마를 사용하는 경우, 필수 필드가 지정되도록 Logs 소스를 생성할 것을 권장합니다. 자세한 내용은 "Log source settings"를 참조하십시오.

JSON 타입 지원

Beta feature. Learn more.

베타 기능 - 프로덕션 환경에 아직 적합하지 않음

ClickStack의 JSON 타입 지원은 베타 기능입니다. JSON 타입 자체는 ClickHouse 25.3+에서 프로덕션 환경에서 사용할 준비가 되어 있지만, ClickStack 내 통합은 아직 활발히 개발 중이며 제한 사항이 있거나, 향후 변경되거나, 버그를 포함할 수 있습니다.

ClickStack은 2.0.4 버전부터 JSON type에 대한 베타 지원을 제공합니다.

이 타입의 이점은 Benefits of the JSON type를 참고하십시오.

JSON 타입 지원을 활성화하려면 다음 환경 변수를 설정해야 합니다.

• OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - OTel collector에서 지원을 활성화하여 스키마가 JSON 타입을 사용해 생성되도록 합니다.
• BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true (ClickStack 오픈 소스 배포판에서만 해당) - ClickStack UI 애플리케이션에서 지원을 활성화하여 JSON 데이터를 조회할 수 있도록 합니다.

또한 ClickHouse Cloud 서비스에서 JSON이 활성화되어 있는지 확인하기 위해 support@clickhouse.com으로 문의해야 합니다.