관리형

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

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

collector 시작

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

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

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

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

기존 collector 구성

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

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

엔드포인트 및 password 자리 표시자를 ClickStack에서 생성한 자격 증명으로 대체하십시오:

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:
  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에서 연결된 관련 가이드로 이동하세요.

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

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

데모 데이터

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

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

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

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

다음 내용은 수집 파이프라인이 미리 구성되어 데이터를 전달하도록 설정된 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 싱크 문서를 확인하십시오.

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

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

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

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

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

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

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

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

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

collector 시작

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

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

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

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

기존 collector 구성

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

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

엔드포인트 및 password 자리 표시자를 ClickStack에서 생성한 자격 증명으로 대체하십시오:

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

다음 내용에서는 수집 파이프라인이 미리 구성되어 데이터를 전달하는 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에서 확인할 수 있습니다.

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

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

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

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

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

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

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

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