Один из стартовых фреймворков для исключений в Spring Boot: prometheus-spring-boot-starter

Введение

1. Разработка проекта неизбежно сопровождается различными ошибками, и чем больше объём кода, тем выше вероятность возникновения ошибок. Для небольших проектов, как правило, достаточно одного человека для разработки и поддержки; однако для крупных проектов часто требуется небольшая команда разработчиков. Когда проект будет завершён, начнётся развёртывание тестовой или производственной среды, эти среды не смогут быстро отлаживать и поддерживать, как среда разработки. Если в среде онлайн-проекта возникает исключение, команде разработчиков необходимо активно его обнаружить и скоординировать обработку. Конечно, люди не могут следить за онлайн-проектом 24 часа в сутки, поэтому необходим механизм автоматического уведомления об исключениях и точного определения того, кто отвечает за проблемный код. Это значительно облегчит последующее обслуживание. Поэтому этот проект запущен.
2. В настоящее время поддерживается только springboot3, поддержка springboot2 и более ранних версий прекращена, для просмотра версии springboot2 можно обратиться к ветке до 0.8.0.
3. Начиная с этой версии все последующие версии будут загружены в центральный репозиторий maven.

Требования к системе

Текущая версия

Описание системы

• В настоящее время вся система разделена на два больших модуля:
  1. Модуль уведомления об исключении: используется для обработки необработанных исключений, возникающих в проекте, путём активного уведомления через WeChat или электронную почту.
  2. Микросервисный модуль уведомления: используется для уведомления о проблемах с информацией о сервисах, отсутствии сервисов и других ситуациях в кластере микросервисов через WeChat или электронную почту.

Уведомление об исключении

Быстрый старт

• Скопируйте этот проект с помощью команды mvn clean install в локальный репозиторий. (Версия 0.8.0 уже добавлена в центральный репозиторий Maven, можно напрямую добавить зависимость).

• Добавьте следующую зависимость в файл pom.xml вашего проекта:

    <dependency>
        <groupId>top.codef</groupId>
        <artifactId>prometheus-spring-boot-starter</artifactId>
        <version>0.8.0</version>
    </dependency>

• Внесите следующие настройки в файлы application.properties или application.yml: (более подробное описание настроек приведено в следующем разделе)

prometheus:
  enabled: true
  exceptionnotice:
    enabled: true
    included-trace-package: com.havefun
  notice:
    dingding:
      user1:
        access-token: 在webhook中的参数：accessToken
        sign-secret: 钉钉的签名秘钥
        enable-signature-check: true
        phone-num: 
        - 通知人的手机号
  default-name: user1

• Что касается конфигурации WeChat, пожалуйста, перейдите по ссылке: WeChat Robot, здесь следует особо отметить, что WeChat провёл обновление своего робота WeChat в октябре 2019 года (примерно), это обновление сделало безопасность обязательной опцией, ранее настроенные роботы WeChat без настроенной безопасности не были затронуты.

• После завершения настройки вы можете написать демонстрационный тест. Сначала создайте первый компонент:

@Component
@ExceptionListener
public class SomeComponent {
    public String haveException() {
        throw new NullPointerException("Это исключение нулевого указателя");
    }
}

• После того как всё настроено, вы можете приступить к написанию модульных тестов:

@SpringBootTest
class PrometheusDemoApplicationTests {

    @Autowired
    private SomeComponent someComponent;

    @Test
    void contextLoads() {
        someComponent.haveException();
    }
}

После запуска модульного теста, если конфигурация WeChat верна, в вашем WeChat появится сообщение, подобное следующему:

Если в настроенном вами WeChat появляется сообщение, похожее на это, поздравляем, вам удалось создать уведомление об исключении.

• Таким образом, самый простой пример завершён.

Как это работает

Эта структура основана на автоматической конфигурации spring boot starter для создания автоматизированной структуры уведомлений об исключениях. Весь бизнес-процесс выглядит следующим образом:

Конфигурация

Конфигурация этой структуры в основном состоит из четырёх частей:

1. Глобальная конфигурация
2. Конфигурация исключений
3. Конфигурация уведомлений
4. Внешняя конфигурация

Глобальная конфигурация

• Глобальные параметры конфигурации включают:

prometheus:
  enabled: true
  project-enviroment: develop
  project-name: demo
  default-name: user1

Подробное описание следующее:

• project-enviroment в основном используется для различения проблем с окружающей средой в онлайн-среде проекта, независимо от того, передаётся ли традиционная конфигурация свойств проекта или централизованная конфигурация микросервисного центра конфигурации, необходимо различать проблемы с окружающей средой проекта, поэтому для удобства сравнения была добавлена эта конфигурация.

• Среда проекта делится на следующие пять типов:

  • Разработка: среда разработки
  • Тест: тестовая среда
  • Предварительный выпуск: предварительная среда выпуска
  • Релиз: производственная среда
  • Откат: откатная среда Эти пять сред обычно достаточны. |frequency-type|enum|Уведомления о частоте стратегии: showcount/timeout, по умолчанию timeout|Нет| |notice-show-count|int|Когда стратегия равна showcount, указывает, сколько раз должно пройти после предыдущего уведомления, прежде чем будет отправлено следующее уведомление|Нет| |notice-time-interval|duration|Когда стратегия равна timeout, указывает, через какое время после предыдущего уведомления будет отправлено следующее, по умолчанию 8 часов|Нет|

• Наиболее важным из уведомлений является exceptionnotice.listen-type, эта конфигурация определяет способ мониторинга проекта. В настоящее время существует два способа мониторинга: обычный мониторинг (common) и веб-мониторинг (web). Эти два метода мониторинга имеют свои преимущества, обычный мониторинг в основном использует метод АОП для мониторинга методов или классов с аннотациями, которые можно добавить к любому классу и методу. Веб-мониторинг может отслеживать только контроллер, но информация об исключениях более полная, включая не только всю информацию обычного мониторинга (без параметров), но также включает информацию о пути запроса (path), параметрах запроса (param), теле запроса (body) и заголовке тела запроса (header). Например:

@RestController
@RequestMapping("/havefun")
@ExceptionListener
public class HaveFunController {

    @PostMapping("/fun/{pathVal}")
    public String havefun(@PathVariable String pathVal, @RequestParam String queryParam,
            @RequestBody String bodyParam) {
        throw new NullPointerException("Запрос пустого указателя исключения");
    }
}

Конкретный эффект:

• Исключения в проекте обычно делятся на две категории: первая — необработанные исключения, вторая — бизнес-исключения. Бизнес-исключения обычно определяются пользователем, в javaweb-проекте, если запрос не соответствует условиям возврата результата, обычно необходимо активно генерировать пользовательское исключение, поэтому этот тип исключения не требует уведомления. Исключения, которые не требуют уведомления о конфигурации, следующие:

 prometheus.exceptionnotice.exclude-exceptions=java.lang.IllegalArgumentException,com.yourpackage.YourLogicException

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

• Стратегия уведомлений соответствует классу конфигурации ExceptionNoticeFrequencyStrategy.

• В настоящее время есть два типа стратегий уведомлений:

  • Стратегия времени
  • Стратегия частоты появления

Соответствующая конфигурация:

exceptionnotice.strategy.frequency-type=timeout/showcount

• Стратегия времени соответствует конфигурации exceptionnotice.strategy.notice-time-interval, тип — duration, что означает, что после времени, указанного в этом параметре, начиная с последнего уведомления, будет выдано следующее уведомление.
• Стратегия частоты соответствует конфигурации exceptionnotice.strategy.notice-show-count, которая представляет собой количество раз, когда возникает исключение после последнего уведомления, и будет выдано следующее уведомление после достижения этого числа. В целом, этих двух стратегий достаточно, но если есть лучшая стратегия конфигурации, вы можете связаться со мной.
• Если ничего не настроено, стратегия уведомления по умолчанию составляет 8 часов.

Конфигурация уведомлений

• Вышеупомянутое говорит обо всех конфигурациях, глобальных конфигурациях и конфигурациях исключений. После получения исключения проектом и после упаковки сообщения необходимо выполнить уведомление.

• Всего существует три типа уведомлений:

  1. Уведомления в чате
  2. Уведомления по электронной почте
  3. Пользовательские уведомления

• Ниже приведены все конфигурации уведомлений:

prometheus:
  notice:   
    enable-async: true
    dingding-text-type: text
    email-text-type: text
    dingding:
      user1:
        access-token: 钉钉webhook中的token参数
        enable-signature-check: true
        phone-num: 
        - 通知人手机号
        sign-secret: 签名秘钥
    email:
      user2: 
        to: 发给谁
        bcc: 秘密抄送给谁
        cc: 抄送给谁

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

• Когда включена проверка подписи, необходимо установить флажок «подписать» в настройках безопасности машины чата:

• Фреймворк сохраняет все необходимые интерфейсы для уведомлений, пользователи могут определять свои собственные уведомления, подробности см. ниже, сначала посмотрите вниз, позже будет введение.

• Вы можете посмотреть следующую конфигурацию:

prometheus:
  enabled: true
  default-name: user1
  exceptionnotice:
    enabled: true
    included-trace-package: Ваш собственный путь пакета
    listen-type: web
    include-header-name:
    - Content-Type
  notice:
    dingding:
      user1: 
        access-token: 
        sign-secret: Ваш
        phone-num: Номер мобильного телефона
    dingding-text-type: markdown

В этой конфигурации используется режим веб, и заголовок фильтруется, и при возникновении исключения уведомление отправляется через чат, и содержимое уведомления отображается в формате markdown:

По сравнению со строковым соединением структура markdown относительно сильнее. Аннотация @ExceptionListener

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
public @interface ExceptionListener {

    /**
     * 出错了找谁？？？
     *
     * @return
     */
    String value() default "";
}

Аннотация @ExceptionListener — это единственная аннотация в рамках, которая служит для конфигурации. Необходимо обратить внимание на то, что все классы и методы, которые требуют уведомления об исключениях, должны быть снабжены этой аннотацией.

В зависимости от типа конфигурации exceptionnotice.listen-type расположение аннотации будет отличаться:

• Если exceptionnotice.listen-type=common, то @ExceptionListener можно добавить к любому классу или методу.
• Если же exceptionnotice.listen-type=web, то @ExceptionListener может быть добавлен только к тем классам или методам, которые имеют аннотацию @Controller или @RestController. Также метод должен иметь аннотацию @RequestMapping.

Параметр аннотации представляет собой идентификатор получателя уведомления в конфигурациях exceptionnotice.listen-type. Это может быть ключ в конфигурации «dingding» или «email».

Конфигурация

На основе всех описанных конфигураций в систему были добавлены дополнительные расширения конфигурации, включающие несколько модулей:

1. Пользовательский компонент отправки сообщений.
2. Пользовательская структура текста уведомлений об исключениях.
3. Пользовательский HTTP-компонент.

Пользовательский компонент отправки сообщений реализуется через интерфейс INoticeSendComponent. Этот интерфейс отвечает за отправку сообщений:

public interface INoticeSendComponent extends Unique {

    void send(PromethuesNotice exceptionNotice, NoticeTextResolver noticeTextResolver);

}

Интерфейс Unique используется для идентификации каждого компонента отправки сообщений. Например, компонент отправки сообщений «DingDingNoticeSendComponent» имеет имя «dingding», а компонент «EmailNoticeSendComponent» — «email». Это позволяет пользователям заменять стандартные компоненты отправки сообщений (по умолчанию — «dingding» и «email») своими собственными. Для этого необходимо реализовать интерфейс NoticeSendComponentCustomer:

public interface NoticeSendComponentCustomer extends Ordered {

    void custom(NoticeSendComponentRegister register);
}

NoticeSendComponentRegister используется для регистрации компонентов отправки сообщений и их владельцев. Это позволяет находить соответствующий компонент отправки сообщений через параметр аннотации @ExceptionListener.

Кроме компонента отправки сообщений, важным модулем в системе является обработка текстовых форматов. В системе информация собирается и упаковывается в объект PromethuesNotice. Обработка этих объектов и форматирование текста выполняются через интерфейс NoticeTextResolver:

public interface NoticeTextResolver {

    public String resolve(PromethuesNotice notice);

    public boolean support(Class<? extends PromethuesNotice> clazz, INoticeSendComponent sendComponent);
}

В конфигурации dingding-text-type есть соответствующие резолверы, такие как ExceptionNoticeMarkdownMessageResolver. Эти резолверы также могут быть настроены программно через реализацию интерфейса NoticeTextResolverCustomer.

public interface NoticeTextResolverCustomer extends Ordered{

    public void custom(NoticeTextResolverProvider resolverProvider);

}

Для отправки сообщений с помощью OpenFeign в системе используется интерфейс DingdingHttpClient:

@FunctionalInterface
public interface DingdingHttpClient {

    DingDingResult doSend(DingDingNotice notice, DingDingNoticeProperty dingDingNoticeProperty);

}

Мониторинг микросервисов

Поскольку автор использует бесплатную версию Consul, мониторинг микросервисов не так эффективен. Однако, благодаря наличию интерфейсов для отправки уведомлений, появилась возможность интегрировать мониторинг микросервисов в эту систему. Это позволило сделать компоненты более согласованными.

Как это работает

При запуске сервиса мониторинга микросервисов выполняется инициализация, в ходе которой обнаруживаются все микросервисы в центре регистрации и определяются три типа проблем:

• Отсутствие сервиса.
• Недостаточное количество экземпляров сервиса.
• Непрохождение проверки работоспособности сервиса.

Информация о проблемах сервисов собирается и сохраняется с помощью ServiceNoticeRepository. Затем эти данные передаются соответствующим компонентам отправки уведомлений через ServiceNoticeTask.

Конфигурации

Все настройки мониторинга микросервисов хранятся в файле YAML. Ниже приведён пример конфигурации:

prometheus:
  enabled: true
  project-enviroment: develop
  dingding:
    enabled: true
    phone-num: 15129072758
    access-token: 
    sign-secret: 
    enable-signature-check: true 
  service-monitor:
    auto-discovery: true
    enabled: true
    service-check-notice-interval: 3m
    service-exist-check-interval: 3m
    monitor-services:
      have-fun: 
        service-count: 3
        health-check-url: /actuator/health
        health-check-headers:
          test: 
          - aaa
        check-interval: 2m
        enabled: true

Здесь представлены следующие параметры:

Это все настройки мониторинга сервисов.

Теоретически можно использовать любой реестр служб, но я работал только с Consul. Если вам нужно протестировать другие реестры, свяжитесь со мной. Чтобы добавить сервис в кластер микросервисов, нужен сервис, который будет выполнять мониторинг и управление микросервисами. После добавления сервиса через auto-discovery будут обнаружены все существующие сервисы кластера и получено их состояние работоспособности. В этот момент система будет считать кластер микросервисов завершённым. Если позже появятся новые сервисы, они будут автоматически добавлены в список сервисов для мониторинга.

Требования к уведомлениям микросервисов всё ещё находятся в разработке. Если у вас есть вопросы или проблемы, вы можете создать issue.

Что касается уведомлений, например, в WeChat: