본문으로 바로가기
본문으로 바로가기

Vector로 데이터 수집하기

Vector는 고성능의 벤더 중립적인 관측성(observability) 데이터 파이프라인입니다. 다양한 소스에서 로그와 메트릭을 수집, 변환 및 라우팅하는 데 널리 사용되며, 특히 유연성과 낮은 리소스 사용량 덕분에 로그 수집(ingestion) 용도로 많이 활용됩니다.

Vector를 ClickStack과 함께 사용할 때는 스키마를 직접 정의해야 합니다. 이 스키마는 OpenTelemetry 규칙을 따를 수도 있고, 사용자 정의 이벤트 구조를 완전히 커스텀한 형태로 표현할 수도 있습니다. 실제로 Vector를 통한 수집은 로그에 가장 많이 사용되며, 데이터가 ClickHouse에 기록되기 전에 파싱과 부가 정보(enrichment) 추가 과정을 완전히 제어하고자 할 때 주로 활용됩니다.

이 가이드는 ClickStack 오픈 소스와 관리형 ClickStack 모두에서 Vector를 사용하여 데이터를 ClickStack으로 도입하는 방법에 초점을 맞춥니다. 단순화를 위해 Vector 소스나 파이프라인 구성은 자세히 다루지 않습니다. 대신 데이터를 ClickHouse에 기록하는 sink를 구성하는 방법과, 그 결과 스키마가 ClickStack과 호환되도록 하는 데 중점을 둡니다.

오픈 소스든 관리형 배포든 ClickStack에서 유일하게 엄격하게 요구되는 사항은 데이터에 timestamp 컬럼(또는 동등한 시간 필드)이 포함되어 있어야 한다는 점입니다. 이 필드는 ClickStack UI에서 데이터 소스를 구성할 때 선언할 수 있습니다.

Vector를 사용하여 데이터 전송​


다음 가이드는 Managed ClickStack 서비스를 이미 생성하고 서비스 자격 증명을 기록한 상태를 가정합니다. 아직 생성하지 않았다면 Vector를 구성하도록 안내받기 전까지 Managed ClickStack의 시작하기 가이드를 따르십시오.

데이터베이스 및 테이블 생성하기​

Vector는 데이터를 수집하기 전에 테이블과 스키마를 미리 정의해야 합니다.

먼저 데이터베이스를 생성하세요. ClickHouse Cloud 콘솔을 통해 수행할 수 있습니다.

아래 예제에서는 logs를 사용합니다:

CREATE DATABASE IF NOT EXISTS logs

데이터를 위한 테이블을 생성하세요. 이는 데이터의 출력 스키마와 일치해야 합니다. 아래 예시는 일반적인 Nginx 구조를 가정합니다. 스키마 모범 사례를 준수하여 데이터에 맞게 조정하세요. 기본 키(Primary Key)의 개념을 숙지하고, 여기에 설명된 가이드라인에 따라 기본 키를 선택하실 것을 강력히 권장합니다.

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)
Nginx 기본 키

위의 기본 키는 ClickStack UI에서 Nginx 로그의 일반적인 접근 패턴을 가정합니다. 프로덕션 환경의 워크로드에 따라 조정해야 할 수 있습니다.

Vector 구성에 ClickHouse 싱크 추가하기​

Vector 구성을 수정하여 ClickHouse 싱크를 포함하고, 기존 파이프라인에서 이벤트를 수신할 수 있도록 inputs 필드를 업데이트하세요.

이 구성은 업스트림 Vector 파이프라인이 이미 대상 ClickHouse 스키마에 맞게 데이터를 준비했다고 가정합니다. 즉, 필드가 파싱되고 올바르게 명명되었으며 삽입에 적합한 타입으로 지정되어 있어야 합니다. 원시 로그 라인을 ClickStack에 적합한 스키마로 파싱하고 정규화하는 전체 예시는 아래 Nginx 예제를 참조하세요.

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

기본적으로 json_each_row 형식을 사용하는 것을 권장합니다. 이 형식은 각 이벤트를 행당 하나의 JSON 객체로 인코딩합니다. 이는 JSON 데이터를 수집할 때 ClickStack의 기본 권장 형식이며, 문자열로 인코딩된 JSON 객체와 같은 다른 형식보다 우선적으로 사용해야 합니다.

ClickHouse 싱크는 Arrow 스트림 인코딩(현재 베타)도 지원합니다. 이를 통해 더 높은 처리량을 제공할 수 있지만 중요한 제약 사항이 있습니다. 데이터베이스와 테이블은 정적이어야 하며(스키마는 시작 시 한 번만 가져옴), 동적 라우팅은 지원되지 않습니다. 이러한 이유로 Arrow 인코딩은 고정되고 명확하게 정의된 수집 파이프라인에 가장 적합합니다.

Vector 문서에서 사용 가능한 싱크(sink) 구성 옵션을 검토하십시오:

참고

위 예제는 Managed ClickStack의 기본 사용자를 사용합니다. 프로덕션 배포 환경에서는 적절한 권한과 제한이 설정된 전용 수집 사용자를 생성하는 것을 권장합니다.

ClickStack UI로 이동​

관리형 ClickStack 서비스로 이동하여 왼쪽 메뉴에서 「ClickStack」을 선택하세요. 온보딩을 이미 완료했다면 새 탭에서 ClickStack UI가 실행되며 자동으로 인증됩니다. 온보딩을 완료하지 않았다면 온보딩을 진행한 후 입력 소스로 Vector를 선택하고 "Launch ClickStack"을 선택하세요.

Vector용 ClickStack 시작하기

데이터 소스 생성하기​

로그 데이터 소스를 생성하세요. 데이터 소스가 없는 경우 첫 로그인 시 생성 안내가 표시됩니다. 데이터 소스가 이미 있는 경우 Team Settings로 이동하여 새 데이터 소스를 추가하세요.

데이터 소스 생성 - Vector

위 구성은 타임스탬프로 사용되는 time_local 컬럼을 포함한 Nginx 스타일 스키마를 가정합니다. 가능한 경우, 이 컬럼은 기본 키에 선언된 타임스탬프 컬럼이어야 합니다. 이 컬럼은 필수입니다.

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

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

다른 가능한 옵션은 구성 참조를 참조하십시오.

데이터 탐색하기​

로그 뷰로 이동하여 데이터를 탐색하고 ClickStack을 사용하세요.

ClickStack의 Nginx 로그

Vector를 사용한 예제 데이터 세트​

더 완전한 예제를 위해 아래에서는 Nginx 로그 파일을 사용합니다.

다음 가이드는 Managed ClickStack 서비스를 이미 생성하고 서비스 자격 증명을 기록한 상태를 가정합니다. 아직 완료하지 않았다면 Vector를 구성하도록 안내받기 전까지 Managed ClickStack의 시작하기 가이드를 따르십시오.

Vector 설치하기​

계속하기 전에 수집 파이프라인을 실행할 계획인 시스템에 Vector가 설치되어 있는지 확인하십시오. 환경에 맞는 미리 빌드된 바이너리 또는 패키지를 설치하려면 공식 Vector 설치 가이드를 따르십시오.

설치가 완료되면 아래의 구성 단계를 진행하기 전에 vector 바이너리가 경로(PATH) 상에서 사용 가능한지 확인하십시오.

이는 ClickStack OTel collector와 동일한 인스턴스에 설치할 수 있습니다.

Vector를 프로덕션 환경으로 이전할 때는 아키텍처와 보안 모범 사례를 준수하십시오.

샘플 데이터 다운로드하기​

샘플 데이터 세트로 실험해 보고 싶다면, 다음 nginx 예제를 다운로드하십시오.

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
참고

이 데이터는 파싱을 더 쉽게 하기 위해 로그를 JSON 형식으로 출력하도록 구성된 Nginx 인스턴스에서 수집되었습니다. 이러한 로그를 위한 Nginx 구성은 "ClickStack으로 Nginx 로그 모니터링"을 참조하십시오.

데이터베이스 및 테이블 생성하기​

Vector는 데이터를 수집하기 전에 테이블과 스키마를 정의해야 합니다.

먼저 데이터베이스를 생성하세요. ClickHouse Cloud 콘솔을 통해 수행할 수 있습니다.

logs 데이터베이스를 생성하세요:

CREATE DATABASE IF NOT EXISTS logs

데이터를 저장할 테이블을 생성하세요.

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)
Nginx 기본 키

위의 기본 키는 ClickStack UI에서 Nginx 로그에 대한 일반적인 접근 패턴을 가정합니다. 프로덕션 환경의 워크로드에 따라 조정해야 할 수 있습니다.

Vector 구성 복사하기​

vector 구성을 복사하고 nginx.yaml 파일을 생성한 후, CLICKHOUSE_ENDPOINT와 CLICKHOUSE_PASSWORD를 설정하세요.

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"
참고

위 예제는 Managed ClickStack의 기본 사용자를 사용합니다. 프로덕션 배포 환경에서는 적절한 권한과 제한이 설정된 전용 수집 사용자를 생성하는 것을 권장합니다.

Vector 시작​

파일 오프셋을 기록하기 위해 데이터 디렉토리를 먼저 생성한 후, 다음 명령으로 Vector를 시작하세요.

mkdir ./.vector-data
vector --config nginx.yaml

ClickStack UI로 이동​

관리형 ClickStack 서비스로 이동하여 왼쪽 메뉴에서 「ClickStack」을 선택하세요. 온보딩을 이미 완료했다면 새 탭에서 ClickStack UI가 실행되고 자동으로 인증됩니다. 온보딩을 완료하지 않았다면 온보딩을 진행한 후 Vector를 입력 소스로 선택하고 "Launch ClickStack"을 선택하세요.

Vector용 ClickStack 시작하기

데이터 소스 생성하기​

로그 데이터 소스를 생성하세요. 데이터 소스가 없는 경우 첫 로그인 시 생성 안내가 표시됩니다. 데이터 소스가 이미 있는 경우 Team Settings로 이동하여 새 데이터 소스를 추가하세요.

Vector용 데이터 소스 생성

이 구성은 타임스탬프로 사용되는 time_local 컬럼을 포함한 Nginx 스키마를 가정합니다. 이는 기본 키에 선언된 타임스탬프 컬럼입니다. 이 컬럼은 필수입니다.

또한 기본 select를 time_local, remote_addr, status, request로 지정하여 로그 뷰에서 반환되는 컬럼을 정의합니다.

위 예시에서 Body 컬럼은 데이터에 존재하지 않으며, 대신 다음과 같은 SQL 표현식으로 정의됩니다:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%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, '"'
)

구조화된 필드로부터 로그 라인을 재구성합니다.

다른 가능한 옵션은 구성 참조를 참고하세요.

데이터 탐색하기​

2025년 10월 20일의 검색 뷰로 이동하여 데이터를 탐색하고 ClickStack 사용을 시작하세요.

HyperDX UI