dead_letter_queue 시스템 테이블

dead_letter_queue 시스템 테이블은 스트리밍 엔진을 통해 수신되어 오류와 함께 파싱된 메시지에 대한 정보를 담고 있어요. 현재 Kafka와 RabbitMQ에 대해 구현되어 있어요.

출처: 문서

본문

Description (설명)

스트리밍 엔진을 통해 수신되어 오류와 함께 파싱된 메시지에 대한 정보를 담고 있어요. 현재 Kafka와 RabbitMQ에 대해 구현되어 있어요.

가용성 system.dead_letter_queue는 서버 구성에 dead_letter_queue 섹션이 있을 때만 생성돼요. 스트리밍 엔진도 거부된 메시지를 쓰려면 handle_error_mode 설정을 dead_letter_queue로 설정해야 해요. 서버 구성 섹션이 없으면 테이블에 대한 쿼리는 UNKNOWN_TABLE로 실패해요.

<clickhouse>
    <dead_letter_queue>
        <database>system</database>
        <table>dead_letter_queue</table>
        <partition_by>toYYYYMM(event_date)</partition_by>
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    </dead_letter_queue>
</clickhouse>

로깅은 엔진별 handle_error_mode 설정에 dead_letter_queue를 지정하여 활성화돼요. 데이터의 플러시 주기는 dead_letter_queue 서버 설정 섹션의 flush_interval_milliseconds 매개변수로 설정돼요. 강제로 플러시하려면 SYSTEM FLUSH LOGS 쿼리를 사용해요. ClickHouse는 테이블에서 데이터를 자동으로 삭제하지 않아요. 자세한 내용은 Introduction을 참고해요. 언제든지 이 테이블을 잘라내거나 드롭해도 안전해요.

Columns (열)

clickhouse_version (LowCardinality(String)) — 행을 생성한 ClickHouse 서버의 버전.
system_processor (LowCardinality(String)) — 행을 생성한 ClickHouse 서버의 CPU 아키텍처.
table_engine (Enum8(‘Kafka’ = 1, ‘RabbitMQ’ = 2)) — 스트림 유형. 가능한 값: ‘Kafka’, ‘RabbitMQ’.
event_date (Date) — 메시지 소비 날짜.
event_time (DateTime) — 메시지 소비 날짜와 시간.
event_time_microseconds (DateTime64(6)) — 쿼리 시작 시간(마이크로초 정밀도).
database (LowCardinality(String)) — Kafka 테이블이 속한 ClickHouse 데이터베이스.
table (LowCardinality(String)) — ClickHouse 테이블 이름.
error (String) — 오류 텍스트.
raw_message (String) — 메시지 본문.
kafka_topic_name (String) — Kafka 토픽 이름.
kafka_partition (UInt64) — 토픽의 Kafka 파티션.
kafka_offset (UInt64) — 메시지의 Kafka 오프셋.
kafka_key (String) — 메시지의 Kafka 키.
rabbitmq_exchange_name (String) — RabbitMQ exchange 이름.
rabbitmq_message_id (String) — RabbitMQ 메시지 id.
rabbitmq_message_timestamp (DateTime) — RabbitMQ 메시지 타임스탬프.
rabbitmq_message_redelivered (UInt8) — RabbitMQ redelivered 플래그.
rabbitmq_message_delivery_tag (UInt64) — RabbitMQ delivery tag.
rabbitmq_channel_id (String) — RabbitMQ channel id.

Example (예제)

Query (쿼리)

SELECT * FROM system.dead_letter_queue LIMIT 1 \G;

Response (응답)

Row 1:
──────
table_engine:                  Kafka
event_date:                    2025-05-01
event_time:                    2025-05-01 10:34:53
event_time_microseconds:       2025-05-01 10:34:53.910773
database:                      default
table:                         kafka
error:                         Cannot parse input: expected '\t' before: 'qwertyuiop': (at row 1)
:
Row 1:
Column 0,   name: key,   type: UInt64, ERROR: text "qwertyuiop" is not like UInt64
raw_message:                   qwertyuiop
kafka_topic_name:              TSV_dead_letter_queue_err_1746095689
kafka_partition:               0
kafka_offset:                  0
kafka_key:
rabbitmq_exchange_name:
rabbitmq_message_id:
rabbitmq_message_timestamp:    1970-01-01 00:00:00
rabbitmq_message_redelivered:  0
rabbitmq_message_delivery_tag: 0
rabbitmq_channel_id:

Row 2:
──────
table_engine:                  Kafka
event_date:                    2025-05-01
event_time:                    2025-05-01 10:34:53
event_time_microseconds:       2025-05-01 10:34:53.910944
database:                      default
table:                         kafka
error:                         Cannot parse input: expected '\t' before: 'asdfghjkl': (at row 1)
:
Row 1:
Column 0,   name: key,   type: UInt64, ERROR: text "asdfghjkl" is not like UInt64
raw_message:                   asdfghjkl
kafka_topic_name:              TSV_dead_letter_queue_err_1746095689
kafka_partition:               0
kafka_offset:                  0
kafka_key:
rabbitmq_exchange_name:
rabbitmq_message_id:
rabbitmq_message_timestamp:    1970-01-01 00:00:00
rabbitmq_message_redelivered:  0
rabbitmq_message_delivery_tag: 0
rabbitmq_channel_id:

Row 3:
──────
table_engine:                  Kafka
event_date:                    2025-05-01
event_time:                    2025-05-01 10:34:53
event_time_microseconds:       2025-05-01 10:34:53.911092
database:                      default
table:                         kafka
error:                         Cannot parse input: expected '\t' before: 'zxcvbnm': (at row 1)
:
Row 1:
Column 0,   name: key,   type: UInt64, ERROR: text "zxcvbnm" is not like UInt64
raw_message:                   zxcvbnm
kafka_topic_name:              TSV_dead_letter_queue_err_1746095689
kafka_partition:               0
kafka_offset:                  0
kafka_key:
rabbitmq_exchange_name:
rabbitmq_message_id:
rabbitmq_message_timestamp:    1970-01-01 00:00:00
rabbitmq_message_redelivered:  0
rabbitmq_message_delivery_tag: 0
rabbitmq_channel_id:
 (test.py:78, dead_letter_queue_test)

더 알아보기 (Learn more)

Kafka

dead_letter_queue 시스템 테이블