logstamp: сквозные ID в логах микросервисов за 10 минут

Андрей Отинов -

В офисе аналитики, когда сервис падает, команда ищет логи. С помощью logstamp можно быстро отфильтровать все сообщения, относящиеся к одному запросу. Это экономит время и снижает риск ошибок. Перед внедрением стоит проверить, как добавить зависимость и как генерировать ID.

Источник: Habr

Что предоставляет библиотека logstamp

  • Open‑source – исходный код доступен в GitHub: https://github.com/shurupov/logstamp.
  • Модуль для Spring Boot – добавляется как logstamp-core-starter в pom.xml: xml <dependency> <groupId>io.github.shurupov.logstamp</groupId> <artifactId>logstamp-core-starter</artifactId> <version>0.1.0</version> </dependency>
  • Система сквозных идентификаторов – каждый запрос получает «отпечаток» (stamp), который автоматически добавляется в MDC и в сообщения HTTP/Kafka.
  • Компоненты:
  • StampContext – хранит текущие отпечатки.
  • StampExtractor – извлекает отпечатки из входящих сообщений.
  • Interceptor – перехватывает отправку/приём сообщений и добавляет/вычитывает отпечатки.

Как это вписывается в микросервисную архитектуру

  1. Генерация ID – в точке входа (REST‑контроллер, Kafka‑консьюмер) вызывается stampContext.add("requestId", UUID.randomUUID().toString());.
  2. Передача – при отправке HTTP‑запроса или Kafka‑сообщения перехватчик автоматически добавляет все активные отпечатки в заголовки.
  3. Приём – другой сервис получает сообщение, перехватчик читает заголовки, извлекает отпечатки и кладёт их в свой StampContext.
  4. Логирование – все логи, созданные в рамках обработки запроса, автоматически содержат поле requestId, что позволяет быстро отфильтровать их в ELK, Loki или любом другом лог‑агрегаторе.

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

Как быстро проверить работу logstamp

Шаг Что сделать Что проверить
1 Добавить зависимость logstamp-core-starter в pom.xml. mvn dependency:tree показывает наличие пакета.
2 Создать @Bean для StampContext (если не создаётся автоматически). @Autowired StampContext доступен в контроллере.
3 В контроллере вызвать stampContext.add("requestId", UUID.randomUUID().toString());. Лог в консоли содержит поле requestId.
4 Отправить HTTP‑запрос к сервису. В логах сервера виден requestId.
5 В другом сервисе, который получает Kafka‑сообщение, убедиться, что StampContext заполняется автоматически. Логи второго сервиса содержат тот же requestId.
6 В Kibana/Elasticsearch выполнить поиск по полю requestId. Все логи, относящиеся к запросу, возвращаются в одном запросе.

Если все пункты пройдены успешно, библиотека работает корректно и готова к продакшн‑использованию.

Какие риски и ограничения

Риск Как проверить Что сделать
Неполная интеграция – перехватчики могут не работать с кастомными клиентами. Тестировать с реальными HTTP‑клиентами и Kafka‑производителями, которые вы используете. При необходимости написать собственный StampExtractor.
Перегрузка логов – слишком много отпечатков может замедлить запись. Сравнить время логирования с и без logstamp. Ограничить количество активных отпечатков (например, только requestId).
Совместимость с OpenTelemetry – если вы уже используете OT, может возникнуть конфликт. Проверить, не конфликтуют ли заголовки OT и logstamp. При необходимости отключить OT‑заголовки в конфигурации.
Обновления зависимостей – библиотека может не поддерживаться. Проверить актуальность репозитория и наличие открытых issue. Оценить риски поддержки и рассмотреть альтернативы.

Что делать дальше

  1. Пилот – внедрите logstamp в одном из небольших сервисов и измерьте экономию времени на отладку.
  2. Обучение – подготовьте короткую инструкцию для команды, чтобы каждый мог генерировать requestId в своих контроллерах.
  3. Мониторинг – настройте алерты в лог‑агрегаторе, чтобы быстро обнаруживать отсутствие requestId.
  4. Расширение – при успешном пилоте добавьте logstamp в остальные микросервисы, включая те, которые используют Kafka и HTTP.

Дополнительные рекомендации по внедрению

Для успешного внедрения logstamp в продакшн-среду рекомендуется выполнить следующие шаги:

  1. Настройка конфигурации логирования – добавьте в logback-spring.xml или аналогичный конфигурационный файл шаблон с включением MDC-полей, например: %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{requestId}] %msg%n. Это обеспечит отображение идентификатора в каждом логе.
  2. Тестирование в изолированной среде – перед развёртыванием в production проведите нагрузочное тестирование с logstamp, чтобы убедиться, что производительность не снижается. Используйте инструменты вроде JMeter или Gatling для симуляции реальной нагрузки.
  3. Интеграция с системами мониторинга – настройте автоматическое создание дашбордов в Grafana или Kibana, которые фильтруют логи по requestId. Это упростит отладку инцидентов.
  4. Документирование процесса – создайте внутреннюю wiki-страницу с примерами использования logstamp, включая обработку ошибок и edge cases (например, когда запрос не содержит заголовка с отпечатком).
  5. Обратная связь от команды – после пилотного внедрения соберите отзывы разработчиков и DevOps-инженеров, чтобы выявить возможные узкие места или неудобства в использовании.

Пример конфигурации для Spring Boot

Для автоматической настройки logstamp в Spring Boot приложении добавьте следующий bean в конфигурационный класс:

@Configuration
public class LogstampConfig {
    @Bean
    public StampContext stampContext() {
        return new StampContext();
    }
}

Если вы используете Kafka, убедитесь, что в application.yml добавлены настройки для перехватчиков:

spring:
  kafka:
    consumer:
      properties:
        interceptor.classes: io.github.shurupov.logstamp.interceptor.KafkaConsumerInterceptor
    producer:
      properties:
        interceptor.classes: io.github.shurupov.logstamp.interceptor.KafkaProducerInterceptor

Источники

Что почитать дальше