Магический байт в сообщениях и реестр схем Apache Kafka: проблемы и решения

Что такое неизвестный магический байт, почему возникает эта ошибка и как предупредить такое исключение сериализации при работе с Kafka Streams, клиентами Apache Kafka и реестром схем.

Что такое магический байт в сообщении

Чтобы корректно обработать на стороне потребителя сообщение, считанное из Kafka, необходимо знать его формат, поскольку данные, публикуемые приложением-продюсером хранятся на платформе в сериализованном виде. Обойти исключение, связанное с несовпадением структуры данных, можно с помощью конструкции try-except, пример которой я показывала здесь. Однако, перед парсингом структуры данных необходимо десериализовать сообщение, т.е. перевести его из бинарного вида в исходный формат данных.

Если данные в Kafka не соответствуют ожидаемому формату, т.е. не были закодированы с использованием стандартного формата реестра Confluent Schema, были повреждены, закодированы в другом формате или случился конфликт используемой библиотеки с двоичной кодировкой, возникает исключение неизвестного магического байта:

Caused by: org.apache.kafka.common.errors.SerializationException:
Unknown magic byte!

Магический байт (Magic Byte) в сообщениях Kafka — это первые 8 бит, сериализованные с использованием реестра Confluent Schema, которые должны быть нулевыми. Реестры схем хранят определения схем, предоставляя API для управления схемами, а также сериализаторы и десериализаторы для чтения и записи данных в соответствии со схемами. Реестр Confluent Schema прикрепляет идентификатор схемы, сохраняя его как часть ключа сообщения Kafka или полезной нагрузки значения после Magic Byte , что увеличивает размер полезной нагрузки на 5 байт.

Почему магический байт так важен для реестра схем Apache Kafka

Реестр схем, о котором мы писали здесь и здесь, находится за пределами продюсеров, потребителей и топиков Kafka. Перед отправкой сообщения проверяются схемой. Реестр схем поддерживает формат AVRO, Protobuf и JSON, считывая подпись файла, чтобы определить формат. Если он не совпадает, выдается исключение неизвестный магический байт. Чтобы устранить эту ошибку, следует согласовать методы сериализации и проверить, что схемы используют один и тот же формат на стороне продюсера и потребителя.

Таким образом, при использовании реестра схем сериализатор встраивает идентификатор схемы в каждое сообщение, позволяя десериализатору использовать его при извлечении схемы из реестра во время десериализации. Поэтому процесс сквозной сериализации и десериализации в клиенте API, совместимом с Kafka выглядит так:

• продюсер передает сообщение соответствующему сериализатору ключей/значений;
• сериализатору необходимо выяснить, какую версию схемы следует использовать для сериализации. Для этого сериализатор сначала проверяет, существует ли идентификатор схемы для данного субъекта в локальном кэше схемы. На этом этапе сериализатор может получить имя субъекта на основе нескольких стратегий, таких как имя топика. При необходимости можно явно указать имя субъекта.
• Если идентификатор схемы отсутствует в кэше, сериализатор регистрирует схему в реестре схем и собирает полученный идентификатор схемы в ответе. Обычно сериализатор делает это автоматически.
• Когда сериализатор имеет идентификатор схемы, он добавляет в начало сообщения магический байт, всегда содержит значение 0 и SchemaID — целое число длиной 4 байта, содержащее идентификатор схемы.
• Наконец, сериализатор сериализует сообщение и возвращает последовательность байтов производителю.

Таким образом, исключение неизвестного магического байта говорит о том, что сообщение не было сериализовано с помощью сериализатора реестра схем, поэтому его не получается десериализовать. Чтобы исправить это, необходимо написать потребителя, который будет получать сообщения, выполнять десериализацию с использованием схем, а затем повторно сериализовать их с помощью сериализатора реестра схем.

Освойте администрирование и эксплуатацию Apache Kafka для потоковой аналитики больших данных на специализированных курсах в нашем лицензированном учебном центре обучения и повышения квалификации для разработчиков, менеджеров, архитекторов, инженеров, администраторов, Data Scientist’ов и аналитиков Big Data в Москве:

• Apache Kafka для инженеров данных
• Администрирование кластера Kafka
• Администрирование Arenadata Streaming Kafka

1. https://www.confluent.io/blog/how-to-fix-unknown-magic-byte-errors-in-apache-kafka/
2. https://croz.net/news/headers-vs-magic-byte-schema-registry/
3. https://itecnote.com/tecnote/unknown-magic-byte-with-kafka-avro-console-consumer/
4. https://redpanda.com/blog/schema-registry-kafka-streaming
5. https://www.conduktor.io/blog/my-application-crashed-in-production-why-what-how/
6. https://lenses.io/blog/2023/04/aws_glue_schema_registry_that_binds_apache_kafka/