Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Managed ClickStack 시작하기

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickHouse Cloud에 Managed ClickStack을 배포하고, 수집 파이프라인을 통해 테스트 이벤트를 전송한 다음, 해당 이벤트가 ClickStack UI에서 사용 가능한지 확인하십시오.

ClickHouse Cloud는 ClickHouse 백엔드를 운영하지만, 수집 파이프라인과 스키마에 대한 제어는 유지할 수 있습니다. Managed ClickStack은 다음을 제공합니다:

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

시작하기 전에

지원되는 통합과 자체 스키마를 사용하여 데이터를 ClickHouse로 직접 전송할 수도 있습니다.

ClickHouse Cloud 서비스 만들기

ClickHouse Cloud 빠른 시작 가이드의 ClickHouse 서비스 만들기를 완료하십시오. 계속하기 전에 서비스가 실행 중인지 확인하십시오.

수집 환경 준비하기

  • 새 OpenTelemetry Collector를 시작하려면 Docker를 설치하십시오. Kubernetes에서는 Helm을 사용하여 collector를 배포하십시오.
  • 기존 collector를 사용하려면 gateway 역할로 실행하고, 해당 배포판에 ClickHouse exporter가 포함되어 있는지 확인하십시오. 이 가이드에서 필요한 구성을 추가합니다.

관리형 ClickStack 설정하기

수집 소스 및 collector 설정 선택

ClickHouse Cloud 서비스에서 ClickStack을 시작합니다. ClickStack 시작하기 페이지에서 수집 시작을 선택합니다.

수집 시작

수집 소스 선택 페이지에서 OpenTelemetry를 선택합니다.

수집 소스로 OpenTelemetry 선택

ClickStack은 default 관리자 자격 증명을 사용해 collector 명령을 생성합니다. 수집 액세스를 관리 작업과 분리하고 관리자 비밀번호에 의존하지 않도록 전용 수집 자격 증명을 사용하는 것이 좋습니다.

전용 수집 자격 증명 생성(권장)

ClickHouse Cloud에서 서비스의 SQL 콘솔을 열고 다음을 실행합니다.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;

생성된 명령에서 CLICKHOUSE_USER="default"를 CLICKHOUSE_USER="clickstack-ingest"로 바꾸고, CLICKHOUSE_PASSWORD를 전용 사용자의 비밀번호로 설정합니다.

default 관리자 자격 증명을 계속 사용하려면 Collector 시작 탭에서 명령을 복사합니다. ClickStack은 서비스 endpoint를 미리 채웁니다. 비밀번호 자리 표시자를 서비스 비밀번호로 바꿉니다. 비밀번호를 더 이상 가지고 있지 않다면 연결 정보를 확인하거나 재설정합니다.

명령 형식은 다음과 같습니다.

docker run -e CLICKHOUSE_ENDPOINT="https://<host>:8443" \
    -e CLICKHOUSE_USER="default" \
    -e CLICKHOUSE_PASSWORD="<your_password_here>" \
    -p 4317:4317 -p 4318:4318 \
    clickhouse/clickstack-otel-collector:latest

<host>와 <your_password_here>를 ClickHouse Cloud 서비스에 맞는 값으로 바꾼 후 명령을 실행합니다.

collector는 포그라운드에서 실행됩니다. 이 terminal은 열어 둔 채로, 이 가이드의 나머지 명령은 두 번째 terminal에서 실행합니다.

테스트 데이터 전송

현재 타임스탬프가 포함된 테스트 로그를 전송합니다:

NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

기존 collector를 사용하는 경우 http://localhost:4318을 해당 OTLP HTTP 엔드포인트로 바꾸십시오. 수신기에 인증이 필요한 경우 curl 명령에 필요한 헤더를 추가하십시오.

요청이 성공하면 HTTP/1.1 200 OK가 반환됩니다.

탐색을 시작하고 수집을 확인합니다

ClickStack이 OpenTelemetry 데이터 소스를 감지하면 탐색 시작을 선택해 검색 보기를 엽니다. ClickStack ingestion test를 검색합니다.

결과에 서비스 이름이 clickstack-docs-test인 테스트 이벤트가 표시됩니다.

ClickStack 수집 테스트 이벤트가 표시된 ClickStack 로그 보기

수집 환경 준비하기

ClickHouse로 데이터를 전송할 수 있는 기존 Vector 파이프라인부터 준비하십시오.

관리형 ClickStack 설정하기

Vector 선택 및 수집 구성

ClickHouse Cloud 서비스에서 ClickStack을 실행합니다. ClickStack 시작하기 페이지에서 Start ingestion을 선택합니다.

수집 시작

Choose an ingestion source 페이지에서 Vector를 선택하십시오.

수집 소스로 Vector를 선택합니다

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

ClickStack에서 Vector를 사용할 때는 스키마(schema)를 직접 정의합니다. 이 스키마는 OpenTelemetry 규약을 따를 수도 있고, 사용자의 이벤트에 특화된 필드를 사용할 수도 있습니다.

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

Vector 싱크를 구성하기 전에 데이터베이스와 테이블을 생성하십시오.

ClickHouse Cloud에서 해당 서비스의 SQL 콘솔을 열고 데이터베이스를 생성하세요:

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

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 key)가 어떻게 동작하는지 이해한 후 액세스 패턴에 맞는 정렬 키를 선택할 것을 강력히 권장합니다. 기본 키 선택에 대해서는 ClickStack 전용 가이드를 참고하십시오.

ClickHouse 싱크 구성하기

테이블이 준비되면 Vector 구성에 ClickHouse 싱크를 추가하십시오:

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "https://<host>:8443"
    database: logs
    table: nginx_logs
    format: json_each_row
    skip_unknown_fields: true
    auth:
      strategy: basic
      user: default
      password: "<your_password_here>"

your_input은 기존 파이프라인의 입력으로 대체하십시오. <host>와 <your_password_here>는 사용 중인 ClickHouse Cloud 서비스의 값으로 대체하십시오. 필요한 경우 대상 데이터베이스 또는 테이블을 변경하십시오.

전용 수집 자격 증명 사용(권장)

프로덕션 환경에서는 전용 사용자를 생성하고 Vector 대상 테이블에 대한 권한을 부여하십시오. ClickHouse Cloud에서 서비스의 SQL 콘솔을 열고 다음을 실행하십시오:

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;

Vector 싱크에서 default를 clickstack-ingest로 바꾸고 password를 전용 사용자의 비밀번호로 설정합니다.

변경한 구성을 저장한 다음, 기존 배포 프로세스를 사용해 Vector를 다시 로드하거나 재시작하십시오.

Vector로 데이터를 수집하는 더 많은 예시는 Vector로 수집하기를, 고급 옵션은 Vector ClickHouse 싱크 문서를 참고하십시오.

ClickStack 데이터 소스 생성

Vector 파이프라인이 데이터를 적재한 테이블에 대한 데이터 소스를 생성하십시오. ClickStack은 최초 로그인 시 데이터 소스를 생성하도록 안내합니다.

이 폼에는 기본 OpenTelemetry 스키마에 맞는 표현식이 미리 채워집니다. 이 가이드에서 생성한 Nginx 테이블에 대해서는 다음 값으로 소스를 구성하십시오:

설정 값
이름 Nginx 로그
소스 데이터 유형 로그
서버 연결 Default
데이터베이스 logs
테이블 nginx_logs
타임스탬프 컬럼 time_local
기본 SELECT 쿼리 time_local, remote_addr, status, request
서비스 이름 표현식 'nginx'
로그 레벨 표현식 multiIf(status >= 500, 'ERROR', status >= 400, 'WARN', 'INFO')
로그 속성 표현식 map('http.remote_addr', toString(remote_addr), 'http.status_code', toString(status), 'http.request', request)
리소스 속성 표현식 map('service.name', 'nginx')
표시할 타임스탬프 컬럼 time_local
트레이스 ID 표현식 ''
스팬 ID 표현식 ''
암시적 컬럼 표현식 request

Nginx 테이블에는 Body 컬럼이 없습니다. Body Expression을 다음과 같이 설정하십시오:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%i:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

그 밖의 source 설정은 ClickStack 구성 참고를 확인하십시오.

테스트 데이터 전송

기존 Vector 파이프라인의 입력으로 대표 이벤트를 전송합니다.

Vector 소스 및 변환에 관한 더 많은 예시는 Vector를 사용한 수집을 참조하십시오.

탐색을 시작하고 수집을 확인합니다

데이터 소스를 만든 후 탐색 시작을 선택하여 검색 보기로 이동합니다. 테이블의 데이터 소스를 선택한 다음, 전송한 이벤트가 포함되어 있는지 확인합니다.

ClickStack UI의 로그

이제 Managed ClickStack 서비스와 정상 작동하는 수집 경로가 준비되었으며, ClickStack에서 테스트 이벤트를 확인할 수 있습니다.

다음 단계

다른 가이드에서 ClickHouse Cloud 엔드포인트 또는 비밀번호가 필요한 경우, 계속하기 전에 연결 정보를 확인하거나 재설정하십시오.

애플리케이션 및 인프라 데이터 전송

ClickStack으로 전송할 데이터에 맞는 가이드를 선택하십시오.

애플리케이션 계측

지원되는 OpenTelemetry SDK를 사용하여 애플리케이션 트레이스와 로그를 전송합니다.

호스트 로그 수집

agent 역할로 실행되는 OpenTelemetry Collector에서 호스트 로그를 전달합니다.

Kubernetes 모니터링

Kubernetes 클러스터에서 로그, 메트릭 및 트레이스를 수집합니다.

기타 통합 살펴보기

추가 애플리케이션 및 텔레메트리 소스에 대한 가이드를 찾아보십시오.

샘플 데이터 살펴보기

샘플 데이터셋을 사용해 더 풍부한 텔레메트리로 ClickStack을 살펴보십시오.

샘플 로그, 트레이스 및 메트릭

공개 데모에서 데이터를 로드하고 문제를 진단하십시오. 이 가이드에서는 새 로컬 OpenTelemetry Collector를 시작한 것으로 가정합니다. 기존 collector를 구성한 경우 엔드포인트 및 인증 설정을 배포 환경에 맞게 조정하십시오.

로컬 로그 및 메트릭

macOS 또는 Linux에서 로컬 파일과 시스템 메트릭을 수집하십시오.

합성 데이터 생성

기존 애플리케이션이나 데이터셋 없이 데이터 수집을 테스트하려면 생성기를 사용하십시오.

otelgen으로 데이터 생성

합성 OTLP 로그, 트레이스, 메트릭을 짧은 시간 동안 전송합니다.

telemetrygen으로 데이터 생성

여러 서비스에서 구성 가능한 OpenTelemetry 신호를 생성합니다.

ClickStack의 모든 샘플 데이터와 데모를 참조하십시오.

프로덕션 환경 준비

지속적인 워크로드에 ClickStack을 사용하기 전에 프로덕션 환경 및 용량 산정 가이드를 검토하십시오.

프로덕션 환경으로 전환

수집 자격 증명, 보안, 보존 기간 및 운영 관련 가이드를 검토하십시오.

리소스 산정

예상 수집량에 맞게 필요한 컴퓨트 용량을 산정하십시오.

배포 작업은 Managed ClickStack 배포 가이드를 참조하십시오.

Navigation