OpenTelemetry로 ClickHouse 추적하기 - ClickHouse Documentation

OpenTelemetry는 분산 애플리케이션의 트레이스와 메트릭을 수집하기 위한 개방형 표준입니다. ClickHouse는 OpenTelemetry를 일부 지원합니다.

ClickHouse에 추적 컨텍스트 제공하기

ClickHouse는 W3C 권고안에 설명된 추적 컨텍스트 HTTP 헤더를 허용합니다. 또한 ClickHouse 서버 간 또는 클라이언트와 서버 간 통신에 사용되는 네이티브 프로토콜을 통한 추적 컨텍스트도 허용합니다. 수동으로 테스트할 때는 Trace Context 권고안을 준수하는 추적 컨텍스트 헤더를 --opentelemetry-traceparent 및 --opentelemetry-tracestate 플래그를 사용해 clickhouse-client에 전달할 수 있습니다. 부모 추적 컨텍스트가 제공되지 않거나 제공된 추적 컨텍스트가 위의 W3C 표준을 준수하지 않으면, ClickHouse는 opentelemetry_start_trace_probability 설정으로 제어되는 확률에 따라 새 trace를 시작할 수 있습니다.

추적 컨텍스트 전파

추적 컨텍스트는 다음과 같은 경우 다운스트림 서비스로 전파됩니다.

분산 테이블 엔진을 사용할 때와 같이 원격 ClickHouse 서버로 쿼리를 보낼 경우
url 테이블 함수. 추적 컨텍스트 정보는 HTTP 헤더에 담겨 전송됩니다.

ClickHouse Keeper 요청 추적

ClickHouse는 ClickHouse Keeper 요청(ZooKeeper와 호환되는 조정 서비스)에 대한 OpenTelemetry 추적을 지원합니다. 이 기능을 사용하면 클라이언트가 요청을 제출하는 시점부터 서버 측에서 처리되는 과정까지 Keeper 작업의 전체 수명 주기를 세부적으로 파악할 수 있습니다.

Keeper 추적 활성화

Keeper 요청에 대한 추적을 활성화하려면 ZooKeeper/Keeper 클라이언트 구성에서 다음 설정을 지정하십시오:

<clickhouse>
    <zookeeper>
        <node>
            <host>keeper1</host>
            <port>9181</port>
        </node>
        <!-- OpenTelemetry 추적 컨텍스트 전파 활성화 -->
        <pass_opentelemetry_tracing_context>true</pass_opentelemetry_tracing_context>
    </zookeeper>
</clickhouse>

Keeper 스팬 타입

추적이 활성화되면 ClickHouse는 클라이언트 측과 서버 측 Keeper 작업 모두에 대해 스팬을 생성합니다. 클라이언트 측 스팬:

zookeeper.create — 새 노드 생성
zookeeper.get — 노드 데이터 가져오기
zookeeper.set — 노드 데이터 설정
zookeeper.remove — 노드 제거
zookeeper.list — 하위 노드 목록 조회
zookeeper.exists — 노드 존재 여부 확인
zookeeper.multi — 여러 작업을 원자적으로 실행
zookeeper.client.requests_queue — 전송 전 요청이 큐에서 대기한 시간

서버 측 스팬 (Keeper):

keeper.receive_request — 클라이언트의 요청을 수신하고 구문 분석
keeper.dispatcher.requests_queue — dispatcher에서 요청이 큐에 대기하는 시간
keeper.write.pre_commit — Raft commit 전 쓰기 요청 전처리
keeper.write.commit — Raft commit 후 쓰기 요청 처리
keeper.read.wait_for_write — 종속된 쓰기 작업을 기다리는 읽기 요청
keeper.read.process — 읽기 요청 처리
keeper.dispatcher.responses_queue — dispatcher에서 응답이 큐에 대기하는 시간
keeper.send_response — 클라이언트에 응답 전송

샘플링 및 성능

추적 오버헤드를 관리하기 위해 Keeper는 동적 샘플링을 사용합니다. 샘플링 비율은 요청 크기에 따라 1/10,000에서 1/10 사이로 자동 조정됩니다. 샘플링된 요청과 샘플링되지 않은 요청을 포함한 모든 요청의 소요 시간은 성능 모니터링을 위해 히스토그램 메트릭에 기록됩니다.

ClickHouse 자체 추적

ClickHouse는 각 쿼리와 쿼리 계획, 분산 쿼리 같은 일부 쿼리 실행 단계에 대해 trace spans를 생성합니다. 이 추적 정보를 실제로 활용하려면 Jaeger 또는 Prometheus처럼 OpenTelemetry를 지원하는 모니터링 시스템으로 내보내야 합니다. ClickHouse는 특정 모니터링 시스템에 대한 종속성을 피하기 위해 추적 데이터를 시스템 테이블을 통해서만 제공합니다. 표준에서 요구하는 OpenTelemetry trace span 정보는 system.opentelemetry_span_log 테이블에 저장됩니다. 이 테이블은 서버 구성에서 활성화되어 있어야 합니다. 기본 구성 파일 config.xml의 opentelemetry_span_log 요소를 참조하십시오. 기본적으로 활성화되어 있습니다. 태그 또는 속성은 키와 값을 담는 2개의 병렬 배열로 저장됩니다. 이를 다루려면 ARRAY JOIN을 사용하십시오.

쿼리 설정 로그

log_query_settings 설정을 사용하면 쿼리 실행 중 쿼리 설정 변경 사항을 기록할 수 있습니다. 이 설정을 활성화하면 쿼리 설정에 가해진 모든 변경 사항이 OpenTelemetry 스팬 로그에 기록됩니다. 이 기능은 특히 프로덕션 환경에서 쿼리 성능에 영향을 줄 수 있는 구성 변경을 추적하는 데 유용합니다.

모니터링 시스템과의 통합

현재 ClickHouse에서 모니터링 시스템으로 추적 데이터를 내보내는 즉시 사용 가능한 도구는 없습니다. 테스트 목적으로는 system.opentelemetry_span_log 테이블에 대해 URL 엔진을 사용하는 materialized view를 통해 export를 구성할 수 있습니다. 이렇게 하면 유입되는 로그 데이터를 트레이스 collector의 HTTP endpoint로 푸시할 수 있습니다. 예를 들어, 최소한의 스팬 데이터를 http://localhost:9411에서 실행 중인 Zipkin 인스턴스로 Zipkin v2 JSON 포맷으로 푸시하려면 다음과 같습니다:

CREATE MATERIALIZED VIEW default.zipkin_spans
ENGINE = URL('http://127.0.0.1:9411/api/v2/spans', 'JSONEachRow')
SETTINGS output_format_json_named_tuples_as_objects = 1,
    output_format_json_array_of_rows = 1 AS
SELECT
    lower(hex(trace_id)) AS traceId,
    CASE WHEN parent_span_id = 0 THEN '' ELSE lower(hex(parent_span_id)) END AS parentId,
    lower(hex(span_id)) AS id,
    operation_name AS name,
    start_time_us AS timestamp,
    finish_time_us - start_time_us AS duration,
    cast(tuple('clickhouse'), 'Tuple(serviceName text)') AS localEndpoint,
    cast(tuple(
        attribute.values[indexOf(attribute.names, 'db.statement')]),
        'Tuple("db.statement" text)') AS tags
FROM system.opentelemetry_span_log

오류가 발생하면 해당 오류가 발생한 로그 데이터의 일부는 별도의 알림 없이 유실됩니다. 데이터가 도착하지 않으면 서버 로그에서 오류 메시지를 확인하십시오.

블로그: ClickHouse로 관측성 솔루션 구축하기 - 2부 - 트레이스

​ClickHouse에 추적 컨텍스트 제공하기

​추적 컨텍스트 전파

​ClickHouse Keeper 요청 추적

​Keeper 추적 활성화

​Keeper 스팬 타입

​샘플링 및 성능

​ClickHouse 자체 추적

​쿼리 설정 로그

​모니터링 시스템과의 통합

​관련 콘텐츠