Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Vector를 사용한 수집

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

ClickStack과 함께 Vector를 사용할 때는 사용자가 자체 스키마를 정의해야 합니다. 이러한 스키마는 OpenTelemetry 규약을 따를 수도 있지만, 사용자 정의 이벤트 구조를 나타내는 완전히 맞춤형 형태일 수도 있습니다. 실제로 Vector 수집은 가장 일반적으로 로그에 사용되며, 이때 사용자는 데이터가 ClickHouse에 기록되기 전에 파싱과 보강을 완전히 제어하려고 합니다.

이 가이드는 ClickStack Open Source와 Managed ClickStack 모두에서 Vector를 사용해 데이터를 ClickStack에 수집하는 방법에 중점을 둡니다. 간단히 설명하기 위해 Vector 소스나 파이프라인 구성은 자세히 다루지 않습니다. 대신 데이터를 ClickHouse에 기록하는 싱크를 구성하고, 그 결과 생성되는 스키마가 ClickStack과 호환되도록 하는 데 초점을 맞춥니다.

오픈 소스 배포와 관리형 배포 중 어떤 ClickStack를 사용하든, ClickStack의 유일한 엄격한 요구 사항은 데이터에 타임스탬프 컬럼(또는 이에 해당하는 시간 필드)이 포함되어 있어야 한다는 점입니다. 이 값은 ClickStack UI에서 데이터 소스를 구성할 때 지정할 수 있습니다.

Vector를 사용해 데이터 전송하기


이 가이드는 Managed ClickStack 서비스를 이미 생성하고 서비스 자격 증명을 기록해 두었다고 가정합니다. 아직 완료하지 않으셨다면, Vector 구성 단계가 나타날 때까지 Managed ClickStack의 시작하기 가이드를 따라 진행하십시오.

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

Vector에서 데이터를 수집하기 전에 테이블(table)과 스키마(schema)가 미리 정의되어 있어야 합니다.

먼저 데이터베이스(database)를 생성합니다. 이 작업은 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)

Vector 구성에 ClickHouse 싱크 추가

기존 파이프라인에서 이벤트를 수신할 수 있도록 inputs 필드를 업데이트하여 Vector 구성에 ClickHouse 싱크를 추가하십시오.

이 구성은 상위 Vector 파이프라인이 이미 대상 ClickHouse 스키마(schema)에 맞게 데이터를 준비해 두었다고 가정합니다. 즉, 필드가 파싱되고, 이름이 올바르게 지정되며, 삽입에 적합한 유형으로 지정되어 있어야 합니다. 원시 로그 라인을 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 객체로 인코딩하는 json_each_row 포맷 사용을 권장합니다. 이 포맷은 JSON 데이터를 수집할 때 ClickStack에서 기본값이자 권장 포맷이며, 문자열로 인코딩한 JSON 객체 같은 대체 포맷보다 우선해서 사용하는 것이 좋습니다.

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

사용 가능한 싱크 구성 옵션은 Vector 문서에서 검토하는 것을 권장합니다:

데이터 소스 생성

로그 데이터 소스를 생성하세요. 아직 데이터 소스가 없으면 처음 로그인할 때 데이터 소스를 만들라는 안내가 표시됩니다. 이미 있다면 Team Settings로 이동해 새 데이터 소스를 추가하세요.

데이터 소스 생성 - vector

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

또한 로그 뷰에 어떤 컬럼을 반환할지 명확히 정의하도록 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

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

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)

Vector 구성 복사

Vector 구성을 복사한 뒤 CLICKHOUSE_ENDPOINT와 CLICKHOUSE_PASSWORD를 설정하여 nginx.yaml 파일을 만드세요.

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>"

Vector 시작

다음 명령으로 Vector를 시작합니다. 그에 앞서 파일 오프셋을 기록할 데이터 디렉터리를 먼저 생성하십시오.

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

데이터 소스 생성

로그 데이터 소스를 생성합니다. 데이터 소스가 없으면 처음 로그인할 때 생성하라는 안내가 표시됩니다. 그렇지 않으면 Team Settings로 이동해 새 데이터 소스를 추가하세요.

데이터 소스 생성 - vector

이 구성은 time_local 컬럼을 timestamp로 사용하는 Nginx 스키마(schema)를 가정합니다. 이 컬럼은 프라이머리 키(primary key)에 선언된 timestamp 컬럼입니다. 이 컬럼은 필수입니다.

또한 기본 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, '"'
)

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

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

데이터 탐색

데이터를 탐색하고 ClickStack 사용을 시작하려면 October 20th, 2025의 Search view로 이동하십시오.

HyperDX UI
Navigation