37 
Содержание
- Что такое kafka-metadata-shell.sh и зачем она нужна
- Как устроена виртуальная файловая система метаданных
- Шаг 1. Запуск шелла с файлом снапшота
- Шаг 2. Запуск с работающим кластером
- Навигация в шелле. Основные команды
- Практика. Смотрим брокеры кластера
- Практика. Смотрим топики и партиции
- Практика. Читаем конфигурации и feature-флаги
- Поиск по метаданным через find
- Работа со снапшотом в автономном режиме
- Сравнение с альтернативными инструментами
- Ограничения kafka-metadata-shell.sh
- Что дальше
- Референсные ссылки
- Все уроки курса
В уроке 12 мы разобрали kafka-metadata-quorum.sh — как смотреть состояние кворума KRaft, кто сейчас лидер контроллера и насколько отстают фолловеры. Это взгляд на кворум снаружи: числа, статусы, смещения. Но иногда нужно заглянуть внутрь — буквально открыть метаданные кластера и посмотреть, что там хранится.
Для этого в Apache Kafka есть отдельный инструмент — kafka-metadata-shell.sh. Он даёт интерактивный шелл для навигации по метаданным KRaft как по файловой системе. Никаких брокеров, никаких сетевых запросов — просто вы и лог метаданных.
Этот урок полезен прежде всего администраторам Kafka, которые занимаются диагностикой кластера. В курсе «Администрирование кластера Kafka» разбираются реальные сценарии восстановления с использованием метаданных — когда именно этот инструмент помогает найти причину проблемы.
Что такое kafka-metadata-shell.sh и зачем она нужна
kafka-metadata-shell.sh — это интерактивный REPL для чтения метаданных KRaft. Утилита читает снапшот или лог из топика __cluster_metadata и представляет его содержимое в виде виртуальной файловой системы. Вы ходите по ней командами, которые знает любой пользователь Linux: ls, cd, cat, pwd.
Главное отличие от kafka-metadata-quorum.sh — глубина. Quorum-утилита показывает состояние самого Raft-кворума: кто лидер, какое смещение. Shell идёт дальше и даёт доступ к содержимому метаданных: конкретным записям о топиках, партициях, брокерах, правах доступа и feature-флагах.
Инструмент работает в двух режимах. Первый — автономный: читает файл снапшота с диска, брокер при этом может не работать вообще. Второй — интерактивный с живым кластером. Для диагностики после сбоя первый режим особенно ценен.
Как устроена виртуальная файловая система метаданных
После запуска шелла вы оказываетесь в корне виртуальной файловой системы. Её структура отражает всё, что KRaft хранит о кластере. Основные разделы выглядят так.
- /brokers/. Информация о каждом брокере: идентификатор, хост, порт, стойка. По одной директории на каждый broker ID.
- /topics/. Все топики кластера по именам. Внутри каждого — директория partitions/ с записями о каждой партиции, её лидере и репликах.
- /topicIds/. Те же топики, но с адресацией по UUID. Полезно, когда нужно найти топик по внутреннему идентификатору, а не по имени.
- /configs/. Переопределённые конфигурации для топиков и брокеров — те, которые менялись через kafka-configs.sh.
- /features/. Версии feature-флагов. Сюда записывается metadata.version и другие управляемые фичи.
- /clusterIds/. UUID кластера — тот самый, который генерировался в уроке 10 через kafka-storage.sh.
- /acls/. Правила контроля доступа, если ACL включены в кластере.
Это read-only срез состояния кластера на момент снапшота. Ничего изменить через шелл нельзя — только читать и анализировать.
Apache Kafka для инженеров данных
Код курса
DEVKI
Ближайшая дата курса
24 августа, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Шаг 1. Запуск шелла с файлом снапшота
Самый распространённый способ запуска — указать путь к файлу снапшота метаданных. Снапшоты хранятся в директории __cluster_metadata-0 внутри log.dirs вашего контроллера.
# Сначала найдём актуальный снапшот ls -lh /var/kafka/data/__cluster_metadata-0/
Вы увидите файлы с расширением .log и .snapshot. Для шелла нужен файл снапшота — он имеет вид XXXXXXXXX-YYYYY.checkpoint или файл с расширением .snapshot в зависимости от версии. Передаём его через флаг —snapshot.
kafka-metadata-shell.sh \ --snapshot /var/kafka/data/__cluster_metadata-0/00000000000000000000.snapshot
После запуска вы увидите приглашение командной строки шелла. Брокер при этом может быть остановлен — утилита читает файл с диска напрямую.
Loading snapshot at offset 0 with epoch 0 [ Kafka Metadata Shell ] >>
Шаг 2. Запуск с работающим кластером
Если кластер запущен и нужно видеть актуальное состояние метаданных, шелл можно подключить напрямую к брокеру. В этом случае он подгрузит последний снапшот через сетевое соединение.
kafka-metadata-shell.sh \ --controllers localhost:9093
Флаг —controllers принимает адрес controller listener, а не обычный bootstrap-server. В KRaft-режиме это порт 9093 по умолчанию. После подключения шелл подгружает снапшот и начинает получать обновления из лога метаданных.
Навигация в шелле. Основные команды
Набор команд небольшой, но покрывает все базовые сценарии. Работать с ним просто — интерфейс намеренно сделан похожим на bash.
- ls. Показывает содержимое текущей директории или указанного пути. Работает как в Linux: ls /brokers/ выводит список всех брокеров.
- cd. Переходит в указанную директорию. Поддерживает абсолютные и относительные пути. cd .. возвращает на уровень выше.
- pwd. Выводит текущий путь — полезно когда запутались в глубоких директориях.
- cat. Выводит содержимое записи или файла. Именно через cat вы читаете конкретные значения: хост брокера, лидер партиции, версию метаданных.
- find. Рекурсивный поиск по паттерну. find /topics/ replicas найдёт все записи о репликах во всех топиках.
- man. Краткая справка по командам прямо в шелле.
- exit или q. Выход из шелла.
Командная строка поддерживает автодополнение по Tab — это сильно ускоряет навигацию по длинным путям.
Практика. Смотрим брокеры кластера
Начнём с простого — посмотрим, какие брокеры зарегистрированы в метаданных. Это первое, что проверяют после расширения кластера или при диагностике потери брокера.
>> ls /brokers/
1
2
3
>> cd /brokers/1
/brokers/1 >> ls
Registration
Registrations
>> cat Registration
{
brokerId: 1
listenersCount: 1
listeners: [{
name: PLAINTEXT
host: broker1.example.com
port: 9092
}]
rack: rack-a
epoch: 5
fenced: false
}
Поле fenced — ключевое для диагностики. Если оно равно true, брокер исключён из кворума и не обслуживает трафик. Это может произойти после сбоя или ручного вмешательства.
Практика. Смотрим топики и партиции
Навигация по топикам — самый частый сценарий использования шелла. Здесь можно увидеть то, что не покажет kafka-topics.sh —describe: например, реальный leaderEpoch партиции или точный список реплик в ISR.
>> ls /topics/
__consumer_offsets
my-events
orders
>> cd /topics/my-events/partitions/0
/topics/my-events/partitions/0 >> ls
Partition
>> cat Partition
{
partitionId: 0
topicId: AbCdEfGh-1234-5678-abcd-ef1234567890
replicas: [1, 2, 3]
isr: [1, 2, 3]
leader: 1
leaderEpoch: 12
partitionEpoch: 3
}
leaderEpoch — номер эпохи лидера этой партиции. Если он резко вырос по сравнению с соседними партициями, значит эта партиция пережила больше выборов лидера — возможно, из-за нестабильности брокера-лидера.
Apache Kafka: администрирование кластера
Код курса
KAFKA
Ближайшая дата курса
13 июля, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800
Практика. Читаем конфигурации и feature-флаги
Через шелл удобно проверить переопределённые конфигурации топиков — те, что менялись через kafka-configs.sh (об этом подробнее в уроке 15).
>> ls /configs/topics/orders/ retention.ms max.message.bytes >> cat /configs/topics/orders/retention.ms 604800000
Раздел /features/ показывает текущую версию метаданных кластера и другие feature-флаги. Именно здесь хранится значение, которое управляет тем, какие функции KRaft активированы.
>> cat /features/metadata.version 20
Версия метаданных 20 соответствует Kafka 4.2.0. Подробнее о feature-версиях расскажем в уроке 14 про kafka-features.sh.
Поиск по метаданным через find
Команда find ищет по именам узлов в виртуальной файловой системе. Это удобно, когда нужно найти все вхождения определённого типа записи без ручного обхода директорий.
# Найти все записи о репликах во всех топиках >> find /topics/ replicas # Найти все партиции с брокером 2 в качестве лидера >> find /topics/ Partition
Для более сложного анализа — например, найти все партиции, где конкретный брокер в ISR — удобнее выгрузить вывод через перенаправление и обработать grep снаружи шелла. Шелл не поддерживает пайпы внутри себя.
Работа со снапшотом в автономном режиме
Самый ценный сценарий использования kafka-metadata-shell.sh — диагностика после сбоя, когда кластер не запускается. В этом случае снапшот читается прямо с диска.
Путь к снапшоту зависит от настройки log.dirs в конфигурации контроллера. Стандартная схема выглядит так.
# Проверено: Apache Kafka 4.2.0, Ubuntu 22.04 # Найти все снапшоты в директории метаданных find /var/kafka/data/__cluster_metadata-0/ -name "*.snapshot" | sort # Запустить шелл с последним снапшотом SNAPSHOT=$(find /var/kafka/data/__cluster_metadata-0/ -name "*.snapshot" | sort | tail -1) kafka-metadata-shell.sh --snapshot "$SNAPSHOT"
Если снапшотов несколько, берите самый последний — он содержит наиболее актуальное состояние. Имена файлов содержат offset и epoch в виде числового префикса, поэтому сортировка по имени даст правильный порядок.
Сравнение с альтернативными инструментами
Задачу просмотра метаданных можно решить несколькими способами. У каждого свои ограничения и сфера применения.
| Инструмент | Что показывает | Нужен живой брокер | Интерактивность |
|---|---|---|---|
| kafka-metadata-shell.sh | Полное содержимое метаданных KRaft | Нет (только для live-режима) | Да, REPL-шелл |
| kafka-metadata-quorum.sh | Состояние кворума и смещения | Да | Нет |
| kafka-dump-log.sh | Сырые записи лога в JSON/текст | Нет | Нет |
| kafka-topics.sh —describe | Информация о топиках и партициях | Да | Нет |
| kafka-storage.sh info | Состояние директории хранилища | Нет | Нет |
kafka-metadata-shell.sh уникален именно сочетанием: читает сырые метаданные и при этом даёт удобный интерактивный интерфейс. kafka-dump-log.sh из урока 17 тоже читает лог метаданных, но выдаёт неструктурированный поток JSON — удобнее для скриптинга, но сложнее для ручного анализа.
Ограничения kafka-metadata-shell.sh
Инструмент диагностический, и у него есть чёткие границы применения. Важно понимать, что через шелл нельзя сделать.
- Только чтение. Никаких изменений метаданных через шелл нет. Это принципиально: метаданные KRaft изменяются только через контроллер по протоколу Raft, а не прямой записью в файлы.
- Нет пайпов и перенаправлений внутри шелла. Стандартный cat /topics/my-topic | grep leader не сработает. Для фильтрации нужно использовать bash снаружи или команду find.
- Снапшот — это срез на момент времени. В автономном режиме данные актуальны на момент создания снапшота. Изменения, которые произошли после — только в логе, но не в снапшоте.
- Нет данных по сообщениям. Шелл показывает только метаданные кластера — топики, брокеры, партиции. Содержимое самих топиков здесь недоступно. Для этого есть kafka-console-consumer.sh из урока 8.
Для администраторов Kafka эти ограничения логичны: шелл — инструмент для чтения и диагностики, а не для управления. Управляющие операции — через kafka-topics.sh, kafka-configs.sh и другие утилиты, каждая из которых разбирается в отдельном уроке курса.
Что дальше
В уроке 14 разберём kafka-features.sh — утилиту для управления feature-флагами KRaft. Именно через неё включают новые возможности протокола и контролируют версию метаданных кластера — то самое значение, которое мы только что читали в /features/metadata.version.
Референсные ссылки
- Apache Kafka Documentation. KRaft Mode — официальная документация по KRaft и метаданным (2025)
- Confluent Developer. KRaft: Apache Kafka Without ZooKeeper — подробное объяснение архитектуры метаданных KRaft (2025)
- Apache Kafka Blog. Kafka 4.x Release Notes — изменения в KRaft и утилитах в версии 4.2.0 (2025)
- KIP-631. The Quorum-based Kafka Controller — оригинальный KIP, описывающий структуру метаданных KRaft (2025)