Actuator та логи в Spring Boot

1. Обмеження «хороших логів»

Після того як ви налаштували логування і перестали друкувати все через println, настає дивний момент зрілості: ви бачите, що логи — не магічна куля. Вони дають послідовність подій, але не завжди швидку відповідь на запитання «що відбувається зараз», особливо якщо ви хочете перевірити конкретний параметр конфігурації або стан підсистеми.

Уявіть типову ситуацію. Ви змінили application-local.yaml, очікуєте одну поведінку, а застосунок поводиться інакше. У логах можна знайти підказки, але іноді вони розмазуються по стартових повідомленнях, а іноді потрібного рядка просто немає, бо ви ж діяли правильно: не логували все підряд. І ось ви стоїте, як людина з ліхтариком, який світить рівно туди, куди ви здогадалися посвітити, а не туди, де справді проблема.

Actuator — це інший ліхтарик. Він не розповідає історію. Він дає вам змогу запитати в застосунку: «Покажи мені поточний стан» — і отримати структуровану відповідь, найчастіше у JSON.

2. Spring Boot Actuator

Actuator у Spring Boot — це набір вбудованих «службових вікон» у застосунок. Ви додаєте одну starter-залежність, а Boot, як він уміє, поруч із вашим звичайним вебзастосунком піднімає додаткову діагностичну поверхню. Вона складається зі спеціальних кінцевих точок, які не про домен — не про курси, треки та рівні, — а про сам застосунок: чи він живий, яку конфігурацію бачить, які компоненти піднято.

Важливо втримати в голові просту думку: Actuator — це не «ще один контролер» і не «ще одне API для користувачів». Це окремий шар для розробника та експлуатації, а в навчальному проєкті — передусім для розробника. Якщо ваше доменне API — це «вітрина каталогу», то Actuator — це «службові двері для персоналу», які ведуть у підсобку: там не так красиво, зате можна швидко зрозуміти, що у вас з електрикою.

Найприємніше в Actuator для новачка: підключення починається максимально просто — із залежності.

Мінімальний крок: підʼєднуємо starter

dependencies {
    // MVC-стек для HTTP-контролерів і JSON
    implementation("org.springframework.boot:spring-boot-starter-webmvc")

    // Actuator — службові кінцеві точки для діагностики застосунку
    implementation("org.springframework.boot:spring-boot-starter-actuator")
}

Тут не відбувається «підʼєднали бібліотеку — самі все руками налаштували». Саме в цьому й філософія Boot: starter приносить набір залежностей і вмикає автонастроювання, яке створює потрібні інфраструктурні біни.

3. Логи й Actuator: один «розповідає», інший «показує»

Дуже легко помилитися й почати ставитися до Actuator як до заміни логів: «Навіщо писати логи, якщо можна відкрити endpoint?». Але це приблизно як замінити камеру відеоспостереження на фотокартку «в цей момент». І камера, і фото корисні — просто розвʼязують різні задачі.

Логи — це потік подій у часі. Вони відповідають на запитання «Що сталося?» або «Як ми дійшли до поточного стану?». Actuator — це знімок стану. Він відповідає на запитання «Що видно зараз?» або «У якому стані система перебуває саме в цей момент?».

Щоб закріпити різницю, зручно подивитися на це як на дві різні моделі діагностики.

З цього випливає дуже практичне правило для catalog-service: хороші логи ми залишаємо як основу історії та причин, а Actuator використовуємо як швидкий спосіб перевірити стан і конфігурацію без тимчасових «налагоджувальних логів на пару хвилин» (які, як відомо, живуть у коді приблизно до 2038 року).

4. Службові HTTP‑кінцеві точки Actuator

Коли у нас є spring-boot-starter-webmvc, ми вже живемо у світі «HTTP-запит → controller → JSON». Actuator вбудовується в цю саму модель, але логічно відокремлюється: його кінцеві точки живуть під окремим префіксом, найчастіше /actuator. Це допомагає не змішувати «продуктові» URL зі «службовими».

Для початківця це важливо ще й психологічно. Якщо ви змішаєте все в одну купу, швидко зʼявиться думка: «Ну це ж теж API, отже можна туди додати ще трохи бізнес-даних». А потім раптом у вас у /actuator/something опиниться «список курсів тижня», і життя почне пахнути пригодами, зазвичай не тими, якими хочеться.

У нашому проєкті картина має залишатися простою:

# Доменне API (для каталогу)
GET /api/catalog/...

# Службова діагностика (для розробника та середовища)
GET /actuator/...

І це розділення допомагає нам мислити сервіс як «застосунок + операційна поверхня», а не як набір випадкових контролерів.

5. Робимо Actuator помітним у catalog-service

Коли ви підʼєднали Actuator, головна проблема для навчального проєкту — навіть не налаштування, а discoverability: «А де це взагалі шукати?». Якщо розробник щоразу муситиме згадувати URL або лізти в документацію, Actuator не стане звичним інструментом. Тому ми робимо маленьку, але важливу річ: додаємо посилання на службові кінцеві точки прямо на початкову сторінку.

Ця ідея дуже корисна для початківця: ви відкрили /, побачили посилання і відразу розумієте, які діагностичні точки у вас є. Це знімає зайву напругу і перетворює Actuator на частину повсякденного робочого процесу, а не на «щось для продакшну».

Якщо наша початкова сторінка — це src/main/resources/static/index.html, то можна додати туди, наприклад, такий фрагмент:

  
 
    
   
health
 
   
info
 
  

Ці посилання передбачають базовий варіант проєкту, де Actuator живе на тому самому порту, що й сам застосунок. Такий сценарій і залишається тут основним: відкрили / — і відразу бачите службові точки поруч із доменним API. Якщо потім ви винесете Actuator на окремий порт керування, відносні посилання зі звичайної початкової сторінки вже перестануть бути корисними, і тоді краще залишити на сторінці просто підказку про шлях /actuator, а не мертві URL.

Зверніть увагу на тонкий момент: сам факт посилання не гарантує, що кінцева точка прямо зараз «відкрита назовні» по HTTP. Spring Boot досить консервативний і не любить за замовчуванням відкривати діагностику всьому світу. Тому десь ви можете побачити відповідь, а десь — заборону чи недоступність, і це нормально: ми вмикатимемо доступ свідомо. Але посилання тримати корисно, щоб памʼятати «точки входу» і перевіряти їх у потрібному середовищі.

6. Обережність із доступом до Actuator

Actuator дуже легко полюбити, бо він миттєво дає відчуття контролю: «Вау, я бачу стан застосунку». Але в нього є й зворотний бік: деякі кінцеві точки можуть показувати дуже багато внутрішньої інформації, зокрема конфігурацію, джерела значень та інші речі, які в неправильному середовищі розкривати не можна.

Зараз не потрібно йти в глибоку безпеку та інфраструктуру — ми в цьому курсі свідомо не будуємо Security-шар. Але здорова обережність має зʼявитися вже тут: Actuator — це інструмент діагностики, і його видимість має бути обмеженою. У local і dev ми можемо дозволити собі більше спостережуваності, бо це середовище розробки. У бойовій конфігурації ми зазвичай залишаємо мінімальний набір службових точок.

Найчастіша помилка новачка — увімкнути «все й одразу», бо «так простіше». За відчуттями це схоже на те, ніби ви повісили на двері квартири список: «Ключ під килимком, сейф у шафі, пароль Wi‑Fi: 12345678». Діагностувати життя стане зручніше, але ненадовго.

Тут краще йти від меншого до більшого: спочатку зрозуміти, навіщо Actuator взагалі потрібен, потім використовувати найпростіші точки, і лише після цього обережно керувати тим, що саме і де ми показуємо.

7. Типові помилки під час роботи з Actuator

Помилка №1: очікувати, що Actuator замінить логування.
Коли ви вперше бачите службові кінцеві точки, виникає спокуса перестати логувати важливі події та сподіватися, що «потім подивлюся в Actuator». На практиці це ламає розслідування: Actuator покаже стан «зараз», але не розповість, чому ви до нього дійшли. Правильна звʼязка виглядає так: логи фіксують події та причини, Actuator допомагає швидко перевірити поточний стан.

Помилка №2: змішувати продуктові кінцеві точки та службові кінцеві точки в одну смислову купу.
Якщо ви почнете ставитися до /actuator/... як до «ще одного API», дуже скоро туди почнуть просочуватися доменні ідеї, а ваш проєкт втратить межу між «каталогом» і «діагностикою». Дотримуйтеся правила: усе доменне живе під /api/catalog/..., усе службове — під окремим префіксом.

Помилка №3: вмикати максимальну видимість Actuator «про всяк випадок».
Actuator дає багато потужних інструментів, але деякі з них чутливі до середовища. Якщо бездумно відкрити все в будь-якому середовищі, ви ризикуєте розкрити те, що розкривати не хотіли, або просто отримати шумний, незручний набір даних. Набагато здоровіше починати з мінімального набору і розширювати його лише тоді, коли є зрозуміле діагностичне завдання.

Помилка №4: намагатися розвʼязувати проблеми конфігурації тимчасовими логами, ігноруючи ідею runtime‑інтроспекції.
Новачок часто додає «тимчасовий log.info» у три місця, щоб зрозуміти, яке значення властивості «перемогло». Це іноді допомагає, але залишає сміття в коді та витрачає час на перезапуски. Actuator якраз і потрібен, щоб частину таких запитань розвʼязувати без правок Java-коду: ви запитуєте застосунок через службову кінцеву точку і отримуєте відповідь структуровано.

Помилка №5: не робити Actuator зручним для себе в повсякденній розробці.
Якщо Actuator підʼєднано, але ви забуваєте, що він є, користі від нього не буде. Просте посилання на початковій сторінці та звичка іноді зазирати до службових точок перетворюють Actuator із «галочки в залежностях» на реальний інструмент, який прискорює вашу роботу і знижує стрес.