관리형

관리형 ClickStack 배포

이 가이드는 기존 ClickHouse Cloud 사용자를 대상으로 합니다. ClickHouse Cloud를 처음 사용하는 경우 Managed ClickStack용 시작하기 가이드를 권장합니다.

이 배포 패턴에서는 ClickHouse와 ClickStack UI(HyperDX)를 모두 ClickHouse Cloud에서 호스팅하므로, 자체 호스팅해야 하는 구성 요소를 최소화할 수 있습니다.

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

• 스토리지와 독립적인 컴퓨트 자동 스케일링
• 객체 스토리지 기반의 저비용, 사실상 무제한 보존
• Warehouses를 사용해 읽기 및 쓰기 워크로드를 독립적으로 격리할 수 있는 기능
• 통합 인증
• 자동 백업
• 보안 및 컴플라이언스 기능
• 원활한 업그레이드

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

​

적합한 경우

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

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

​

설정 단계

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

새 서비스 생성

1. ​

   새 서비스 생성

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

2. ​

   provider, region 및 리소스 지정

   Scale vs Enterprise

   대부분의 ClickStack 워크로드에는 이 Scale tier를 권장합니다. SAML, CMEK 또는 HIPAA 컴플라이언스와 같은 고급 보안 기능이 필요한 경우 Enterprise tier를 선택하십시오. 또한 매우 큰 ClickStack 배포를 위한 사용자 지정 하드웨어 프로필도 제공합니다. 이러한 경우에는 지원팀에 문의하는 것이 좋습니다.

   Cloud provider와 리전을 선택하십시오.

   

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

   Monthly ingest volume	Recommended compute
   월 10 TB 미만	2 vCPU × 3 레플리카
   월 10–50 TB	4 vCPU × 3 레플리카
   월 50–100 TB	8 vCPU × 3 레플리카
   월 100–500 TB	30 vCPU × 3 레플리카
   월 1 PB 이상	59 vCPU × 3 레플리카

   이 권장값은 다음 가정을 바탕으로 합니다:

   • 데이터 볼륨은 월별 비압축 수집량을 의미하며, 로그와 트레이스 모두에 적용됩니다.
   • 쿼리 패턴은 일반적인 관측성 사용 사례를 기준으로 하며, 대부분의 쿼리는 보통 지난 24시간과 같은 최근 데이터를 대상으로 합니다.
   • 수집은 한 달 동안 비교적 균일하게 이루어진다고 가정합니다. 트래픽 급증이나 스파이크가 예상된다면 추가 여유 용량을 프로비저닝해야 합니다.
   • 스토리지는 ClickHouse Cloud 객체 스토리지를 통해 별도로 처리되며, 보존 기간의 제한 요인이 되지 않습니다. 장기간 보존된 데이터는 자주 액세스되지 않는다고 가정합니다.

   더 긴 시간 범위를 정기적으로 쿼리하거나, 무거운 집계를 수행하거나, 많은 수의 동시 사용자를 지원하는 액세스 패턴에서는 더 많은 컴퓨트가 필요할 수 있습니다.

   주어진 수집 처리량에 대해 CPU와 메모리 요구 사항은 2개의 레플리카로도 충족할 수 있지만, 가능한 경우 동일한 총 용량을 확보하고 서비스 이중화를 개선하기 위해 3개의 레플리카 사용을 권장합니다.

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

   요구 사항을 지정하면 Managed ClickStack 서비스가 프로비저닝되는 데 몇 분 정도 걸립니다. 프로비저닝이 완료될 때까지 기다리는 동안 ClickHouse Cloud 콘솔의 다른 기능도 살펴보십시오.

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

3. ​

   수집 설정

   서비스 프로비저닝이 완료되면 해당 서비스가 선택되어 있는지 확인한 후, 왼쪽 메뉴에서 “ClickStack”을 클릭하십시오.

   

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

   

   OpenTelemetry 권장

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

   OpenTelemetry

   Managed ClickStack로 OpenTelemetry 데이터를 보내려면 OpenTelemetry Collector를 사용하는 것이 좋습니다. collector는 애플리케이션(및 다른 collector)으로부터 OpenTelemetry 데이터를 수신하는 게이트웨이 역할을 하며, 이를 ClickHouse Cloud로 전달합니다.

   아직 실행 중인 collector가 없다면 아래 단계에 따라 시작하세요. 기존 collector가 있다면 구성 예시도 함께 제공됩니다.

   ​

   collector 시작

   다음 내용은 ClickStack 배포판의 OpenTelemetry Collector를 사용하는 권장 방식을 기준으로 합니다. 이 배포판에는 추가 처리 기능이 포함되어 있으며 ClickHouse Cloud에 맞게 특별히 최적화되어 있습니다. 자체 OpenTelemetry Collector를 사용하려면 “기존 collector 구성”을 참조하세요.

   빠르게 시작하려면 아래에 표시된 Docker 명령을 복사해 실행하세요.

   

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

   프로덕션 배포

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

   이 명령 하나로 4317(gRPC) 및 4318(HTTP) 포트에서 OTLP 엔드포인트가 노출된 ClickStack collector가 시작됩니다. 이미 OpenTelemetry 계측과 agent를 사용하고 있다면 즉시 이 엔드포인트로 텔레메트리 데이터를 보내기 시작할 수 있습니다.

   ​

   기존 collector 구성

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

   ClickHouse exporter 필요

   예를 들어 contrib image와 같은 자체 배포판을 사용하는 경우, ClickHouse exporter가 포함되어 있는지 확인하세요.

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

   

   OpenTelemetry collector 구성에 대한 자세한 내용은 “OpenTelemetry로 수집하기”를 참조하세요.

   ​

   수집 시작(선택 사항)

   OpenTelemetry로 계측할 기존 애플리케이션이나 인프라가 있다면 UI에서 연결된 관련 가이드로 이동하세요.

   애플리케이션을 계측해 trace와 로그를 수집하려면 지원되는 언어 SDK를 사용하세요. 이 SDK는 Managed ClickStack으로 수집하기 위한 게이트웨이 역할을 하는 OpenTelemetry Collector로 데이터를 전송합니다.

   로그는 agent 모드로 실행되는 OpenTelemetry Collector를 사용해 수집할 수 있으며, 동일한 collector로 데이터를 전달합니다. Kubernetes 모니터링은 전용 가이드를 따르세요. 다른 통합은 quickstart 가이드를 참조하세요.

   ​

   데모 데이터

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

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

   
   

   벡터

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

   ClickStack와 함께 Vector를 사용할 때는 사용자가 직접 스키마를 정의해야 합니다. 이러한 스키마는 OpenTelemetry 규약을 따를 수도 있지만, 사용자 정의 이벤트 구조를 나타내는 완전히 맞춤형 스키마일 수도 있습니다.

   Timestamp 필수

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

   다음 내용은 수집 파이프라인이 미리 구성되어 데이터를 전달하도록 설정된 Vector 인스턴스가 이미 실행 중이라고 가정합니다.

   ​

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

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

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

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

   CREATE DATABASE IF NOT EXISTS logs
   

   그런 다음 로그 데이터 구조에 맞는 스키마(schema)의 테이블을 생성하세요. 아래 예시는 전형적인 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에서 기본 키가 어떻게 작동하는지 이해하고, 액세스 패턴에 따라 정렬 키를 선택할 것을 강력히 권장합니다. 기본 키 선택에 대해서는 ClickStack 관련 지침도 참조하십시오.

   테이블을 생성한 후에는 표시된 구성 스니펫을 복사하십시오. 필요에 따라 기존 파이프라인을 사용하도록 입력 구성을 조정하고, 대상 테이블과 데이터베이스도 수정하십시오. 자격 증명은 미리 입력되어 있습니다.

   

   Vector를 사용해 데이터를 수집하는 추가 예시는 “Vector로 수집하기”를 참조하고, 고급 옵션은 Vector ClickHouse 싱크 문서를 확인하십시오.

   
   
4. ​

   ClickStack UI로 이동

   “Launch ClickStack”을 선택하여 ClickStack UI(HyperDX)에 액세스합니다. 자동으로 인증된 후 해당 화면으로 리디렉션됩니다.

   OpenTelemetry

   모든 OpenTelemetry 데이터에 대한 데이터 소스가 미리 생성됩니다.

   

   Vector

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

   

   이 구성은 time_local 컬럼을 타임스탬프로 사용하는 Nginx 스타일 스키마를 가정합니다. 가능하면 이 컬럼은 프라이머리 키(primary key)에 선언된 타임스탬프 컬럼이어야 합니다. 이 컬럼은 필수입니다.

   또한 로그 보기에서 반환할 컬럼을 명시적으로 정의할 수 있도록 Default SELECT를 업데이트하는 것이 좋습니다. 서비스 이름, 로그 레벨 또는 본문 컬럼과 같은 추가 필드를 사용할 수 있다면 이들도 구성할 수 있습니다. 표시용 타임스탬프 컬럼이 테이블의 프라이머리 키에 사용된 컬럼 및 위에서 구성한 컬럼과 다를 경우, 이를 재정의할 수도 있습니다.

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

   다른 옵션은 구성 참고를 참조하십시오.

   생성이 완료되면 검색 보기로 이동하며, 즉시 데이터 탐색을 시작할 수 있습니다.

   

   
   

   이제 준비가 모두 완료되었습니다. 🎉

   이제 ClickStack을 살펴보십시오. 로그와 트레이스 검색을 시작하고, 로그·트레이스·메트릭이 실시간으로 어떻게 연관되는지 확인하고, 대시보드를 만들고, 서비스 맵을 탐색하고, Event deltas와 패턴을 파악하고, 알림을 설정하여 문제에 선제적으로 대응할 수 있습니다.

   
   

기존 서비스 사용하기

1. ​

   서비스 선택

   ClickHouse Cloud 랜딩 페이지에서 관리형 ClickStack을 활성화할 ClickHouse 서비스를 선택합니다.

   리소스 산정

   이 가이드는 ClickStack으로 수집하고 쿼리할 예정인 관측성 데이터 양을 처리할 수 있도록 충분한 리소스를 프로비저닝했다고 가정합니다. 필요한 리소스를 산정하려면 리소스 산정 가이드를 참조하십시오.

   ClickHouse 서비스에서 이미 실시간 애플리케이션 분석과 같은 기존 워크로드를 실행 중이라면, 관측성 워크로드를 격리하기 위해 ClickHouse Cloud’s warehouses feature를 사용해 하위 서비스를 생성하는 것이 좋습니다. 이렇게 하면 기존 애플리케이션에 영향을 주지 않으면서도 두 서비스 모두에서 데이터셋에 액세스할 수 있습니다.

2. ​

   ClickStack UI로 이동

   왼쪽 탐색 메뉴에서 ‘ClickStack’을 선택하세요. ClickStack UI로 이동하며, ClickHouse Cloud 권한에 따라 자동으로 인증됩니다.

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

   데이터 소스 자동 감지

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

   자동 감지가 성공하면 Search view로 이동하며, 즉시 데이터를 탐색할 수 있습니다.

   이 단계가 성공하면 설정이 완료된 것입니다 — 모두 준비되었습니다 🎉. 그렇지 않으면 수집 설정을 계속 진행하세요.

3. ​

   수집 설정

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

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

   OpenTelemetry 권장

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

   OpenTelemetry

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

   아직 실행 중인 collector가 없다면 아래 단계에 따라 시작하세요. 기존 collector가 있다면 구성 예시도 제공됩니다.

   ​

   collector 시작

   다음 내용은 권장 방식인 ClickStack distribution of the OpenTelemetry Collector 사용을 전제로 합니다. 이 배포판에는 추가 처리 기능이 포함되어 있으며 ClickHouse Cloud에 맞게 특별히 최적화되어 있습니다. 자체 OpenTelemetry Collector를 사용하려면 “기존 collector 구성”을 참조하세요.

   빠르게 시작하려면 아래에 표시된 Docker 명령을 복사해 실행하세요.

   서비스를 생성할 때 기록한 서비스 자격 증명에 맞게 이 명령을 수정하세요.

   프로덕션에 배포

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

   이 명령 하나로 4317(gRPC) 및 4318(HTTP) 포트에 OTLP endpoint를 노출하는 ClickStack collector가 시작됩니다. 이미 OpenTelemetry instrumentation과 agent가 있다면 이 endpoint로 즉시 텔레메트리 데이터를 보내기 시작할 수 있습니다.

   ​

   기존 collector 구성

   기존 OpenTelemetry Collectors를 직접 구성하거나 자체 배포판의 collector를 사용할 수도 있습니다.

   ClickHouse exporter 필요

   자체 배포판을 사용하는 경우(예: contrib image)에는 ClickHouse exporter가 포함되어 있는지 확인하세요.

   이를 위해 적절한 설정으로 ClickHouse exporter를 사용하고 OTLP 수신기를 노출하는 OpenTelemetry Collector 구성 예시가 제공됩니다. 이 구성은 ClickStack distribution에서 기대하는 인터페이스와 동작에 맞춰져 있습니다.

   이 구성의 예시는 아래와 같습니다(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%(최대 2G), 메모리가 부족한 환경에서는 조정 필요
       limit_mib: 1500
       # 제한의 25%(최대 2G), 메모리가 부족한 환경에서는 조정 필요
       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로 instrument할 infrastructure가 있다면 “애플리케이션 연결”에 링크된 관련 가이드로 이동하세요.

   애플리케이션을 instrument하여 traces와 logs를 수집하려면 지원되는 language SDKs를 사용하세요. 이 SDK는 Managed ClickStack으로 수집하기 위한 gateway 역할을 하는 OpenTelemetry Collector로 데이터를 보냅니다.

   logs는 agent 모드로 실행되는 OpenTelemetry Collectors를 사용해 수집할 수 있으며, 데이터는 동일한 collector로 전달됩니다. Kubernetes 모니터링의 경우 전용 가이드를 따르세요. 다른 통합은 quickstart 가이드를 참조하세요.

   
   

   Vector

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

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

   timestamp 필수

   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에서 프라이머리 키가 어떻게 동작하는지 이해하고, 액세스 패턴에 따라 정렬 키를 선택할 것을 강력히 권장합니다. 프라이머리 키 선택에 관한 ClickStack 전용 지침도 참조하십시오.

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

   Vector로 데이터를 수집하는 추가 예시는 “Vector로 수집하기”를 참조하십시오. 고급 옵션은 Vector ClickHouse sink documentation에서 확인할 수 있습니다.

   
   
4. ​

   ClickStack UI로 이동

   수집 설정을 완료하고 데이터 전송을 시작한 후에는 “다음”을 선택하세요.

   OpenTelemetry

   이 가이드를 사용해 OpenTelemetry 데이터를 수집했다면 데이터 소스가 자동으로 생성되므로 추가 설정이 필요하지 않습니다. 바로 ClickStack을 탐색할 수 있습니다. 즉시 쿼리를 시작할 수 있도록 소스가 자동으로 선택된 검색 보기로 이동됩니다.

   이제 모든 설정이 완료되었습니다 🎉.

   
   

   Vector

   Vector나 다른 소스를 통해 데이터를 수집했다면 데이터 소스를 구성하라는 메시지가 표시됩니다.

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

   또한 로그 보기에서 반환할 컬럼을 명시적으로 정의할 수 있도록 Default SELECT를 업데이트하는 것을 권장합니다. 서비스 이름, 로그 레벨 또는 본문 컬럼과 같은 추가 필드를 사용할 수 있다면 이러한 항목도 구성할 수 있습니다. 타임스탬프 표시 컬럼이 테이블의 프라이머리 키에 사용된 컬럼 및 위에서 구성한 컬럼과 다르다면 이 값도 재정의할 수 있습니다.

   위 예시에서는 데이터에 Body 컬럼이 없습니다. 대신 사용 가능한 필드에서 Nginx 로그 한 줄을 재구성하는 SQL 표현식을 사용해 정의합니다.

   다른 옵션은 구성 참고를 참조하십시오.

   소스 구성을 마친 후 “Save”를 클릭하고 데이터 탐색을 시작하세요.

   
   

​

추가 작업

​

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

1. ClickHouse Cloud 콘솔에서 해당 서비스로 이동합니다
2. 설정 → SQL 콘솔 액세스로 이동합니다
3. 각 사용자에게 적절한 권한 수준을 설정합니다.
   • 서비스 관리자 → 전체 액세스 - 알림을 활성화하려면 필요합니다
   • 서비스 읽기 전용 → 읽기 전용 - 관측성 데이터를 확인하고 대시보드를 생성할 수 있습니다
   • 액세스 없음 - HyperDX에 액세스할 수 없습니다

알림을 사용하려면 관리자 권한이 필요합니다

알림을 활성화하려면 서비스 관리자 권한(SQL 콘솔 액세스 드롭다운에서 전체 액세스로 매핑됨)을 가진 사용자가 최소 한 번 HyperDX에 로그인해야 합니다. 그러면 알림 쿼리를 실행하는 전용 사용자가 데이터베이스에 프로비저닝됩니다.

​

읽기 전용 컴퓨트에서 ClickStack 사용하기

ClickStack UI는 읽기 전용 ClickHouse Cloud 서비스만으로도 완전히 실행할 수 있습니다. 수집 워크로드와 쿼리 워크로드를 분리하려는 경우 권장되는 구성입니다.

​

ClickStack에서 컴퓨트를 선택하는 방식

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

즉, 다음과 같습니다.

• 읽기 전용 서비스에서 ClickStack를 열면 ClickStack UI가 실행하는 모든 쿼리는 해당 읽기 전용 컴퓨트에서 실행됩니다.
• 읽기-쓰기 서비스에서 ClickStack를 열면 ClickStack는 대신 해당 컴퓨트를 사용합니다.

읽기 전용 동작을 강제하기 위해 ClickStack 내부에서 추가로 구성할 필요는 없습니다.

​

권장 설정

읽기 전용 컴퓨트에서 ClickStack을 실행하려면 다음과 같이 하십시오.

1. warehouse에서 읽기 전용으로 구성된 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 스키마를 따르면 설정은 자동으로 감지됩니다.

자체 스키마를 사용하는 경우에는 필수 필드가 지정되도록 로그 소스를 생성하는 것이 좋습니다. 자세한 내용은 “로그 소스 설정”을 참조하십시오.

​

스키마 선택: Map vs JSON

ClickStack는 기본적으로 속성을 Map(LowCardinality(String), String) 컬럼에 저장합니다. 이는 관측성 워크로드에 권장되는 스키마입니다. 버킷 기반 맵 직렬화와 맵 키 및 값에 대한 텍스트 인덱스를 함께 사용하면, 동적 JSON 서브컬럼에서 발생하는 키별 수집 오버헤드 없이 필요한 항목만 선택적으로 조회할 수 있습니다.

JSON 타입 스키마는 속성 키 집합이 작고 안정적인 워크로드에서 평가할 수 있도록 베타로 제공됩니다. 기본값으로는 권장되지 않습니다. 전체 비교 내용과 JSON 지원을 활성화하는 데 필요한 환경 변수는 Map vs JSON type에서 확인하십시오.