W trzeciej części cyklu o logowaniu w serwerach aplikacji z rodziny EuroAP w dalszym ciągu zgłębiamy podsystem logowania. W części drugiej opowiedzieliśmy o root logerze i handlerach. Dziś skupimy się na kategoriach i specyfikacjach filtrów, a także na konfiguracji podsystemu logowania przez CLI.
W związku z tym, że serwer aplikacji EuroAP jest zgodny z JBoss® EAP, artykuł ten dotyczy także tego rozwiązania.
Kategorie
Gdy otworzymy konfigurację podsystemu logowania (Configuration > Subsystems > Logging > Configuration) to obok omówionych już root logera, handlerów i formaterów widnieje zakładka kategorii „Categories”.
Kategorie definiują wiadomości, które mają zostać przekazane do handlera. Konfiguracja kategorii odpowiada na pytanie, co zostanie obsłużone, natomiast konfiguracja handlerów odpowiedzialna jest za sposób obsługi. Można powiedzieć, że kategorie są sitkiem, przez które wiadomości przechodzą, zanim zostaną obsłużone przez handlery. Decyzja, co powinno „przejść przez sitko”, albo inaczej mówiąc, należeć do danej kategorii, jest podejmowana na podstawie poziomu logowania oraz nazwy pakietu javowego, z którego pochodzi wiadomość.
Konfiguracja kategorii
Aby poprawnie skonfigurować kategorię, potrzebujemy określić jej nazwę i poziom logowania. Dodatkowo możemy ustawić jej własne handlery oraz wskazać, czy ma używać handlerów rodzica. Nazwa kategorii pokrywa się zazwyczaj z nazwą pakietu javowego, z którego dane wiadomości pochodzą. Opcjonalnie można też używać wartości zwracanej przez LOGGER.getLogger(LogerName). Domyślnie nowa kategoria nie ma przypisanych własnych handlerów. Ma za to ustawiony parametr use-parent-handlers na true, co oznacza, że dziedziczy handlery po rodzicu (czyli po root loggerze, jeżeli nie skonfigurowaliśmy inaczej).
Poniżej przykład utworzenia nowej kategorii – skupionej na wiadomościach z pakietu com.example mających poziom co najmniej INFO. Ponadto nowo utworzona kategoria nie używa handlerów rodzica, ma za to dodany handler CONSOLE.
[[email protected]:9990 /] /subsystem=logging/logger=com.example:add
{"outcome" => "success"}
[[email protected]:9990 /] /subsystem=logging/logger=com.example:write-attribute(name=level, value=INFO)
{"outcome" => "success"}
[[email protected]:9990 /] /subsystem=logging/logger=com.example:write-attribute(name=use-parent-handlers, value=false)
{"outcome" => "success"}
[[email protected]:9990 /] /subsystem=logging/logger=com.example:add-handler(name=CONSOLE)
{"outcome" => "success"}Aby usunąć kategorię, należy wywołać polecenie:
[[email protected]:9990 /] /subsystem=logging/logger=com.example:remove
{"outcome" => "success"}Filtry
Ostatnim już tematem w podsystemie logowania są filtry. Mechanizm ten jest obecny w każdym omawianym wcześniej elemencie – w root logerze, kategoriach i handlerach. Specyfikacja filtra to wyrażenie, na podstawie którego możemy jeszcze precyzyjniej wyizolować interesujące nas logi, a nawet zmienić ich treść. Filtr zawsze sprawdzany jest na surowej niesformatowanej wiadomości. Filtry możemy ustawić zarówno na kategorii, jak i na handlerze. Specyfikacje filtrów nie są dziedziczone po root loggerze.
Kolejność
Jako iż wiadomości najpierw są sprawdzane przez kategorię, a dopiero później przekazywane do handlerów, filtry używane przy kategorii mają pierwszeństwo nad filtrami przy handlerach. Inaczej mówiąc, wiadomość przebywa drogę: kategoria → filtr kategorii → handler → filtr handlera → formatter. Zatem jeżeli wiadomość zostanie odsiana przez filtr kategorii, to ani handler, ani jego filtr czy formatter nie będą wiedziały, że wiadomość w ogóle istniała.
Konfiguracja filtra — wyrażenie
Poniżej przedstawiamy wyrażenia, których możemy używać w specyfikacji filtra.
| wyrażenie | wytłumaczenie |
|---|---|
| accept | wszystkie wiadomości są akceptowane |
| deny | wszystkie wiadomości są odrzucane |
| not[wyrażenie] | zaprzeczenie danego wyrażenia |
| all[wyrażenie] | wiadomość musi spełniać wszystkie wyrażenia |
| any[wyrażenie] | wiadomość musi spełniać którekolwiek z wyrażeń |
| match[„wzorzec”] | wiadomość zawiera dany wzorzec. Proszę zwrócić uwagę na obecność cudzysłowów |
| substitute[„wzorzec”,”wartość zastępcza” | uaktualnia wiadomość, podmieniając wzorzec (tylko pierwsze wystąpienie) na wartość zastępcz |
| substituteAll[„wzorzec”,„wartość zastępcza” | uaktualnia wiadomość, podmieniając wzorzec (wszystkie wystąpienia) na wartość zastępczą |
| levels[poziomy_logowania] | odfiltrowuje wiadomości z podanymi poziomami logowania. Można podać więcej niż jeden poziom oddzielające je przecinkiem |
| levelRange[minimalny_poziom, maksymalny_poziom] | odfiltrowuje wiadomości o poziomie logowania w podanym zakresie |
| levelChange[poziom] | uaktualnia wiadomość, zmieniając jej poziom logowania |
Pokazane wyrażenia można łączyć. Na przykład: any(match("ejb3"),match("undertow"))
Konfiguracja filtra – CLI
Aby ustawić specyfikację filtra przez CLI, należy użyć polecenia write-attribute(name=filter-spec,value="SPECYFIKACJA_FILTRA") na tym elemencie, do którego chcemy przypisać specyfikację filtra. Jeżeli specyfikacja zawiera ", należy pamiętać o ich zneutralizowaniu na potrzeby CLI przy pomocy \. Na przykład, żeby dodać filtr do utworzonej wcześniej kategorii, należy użyć polecenia:
[[email protected]:9990 /] /subsystem=logging/logger=com.example:write-attribute(name=filter-spec,value="substituteAll(\"WFLY\"\,\"EUROAP\")")Podsumowanie
Druga i trzecia część cyklu o logowaniu w serwerze EuroAP i pokrewnych serwerach aplikacji wyczerpała temat konfiguracji podsystemu logowania. Pokazaliśmy w nich elementy, które składają się na ten podsystem – root logger, kategorie, handlery i formatery oraz omówiliśmy ich właściwości. Zaprezentowaliśmy także, jak skonfigurować ten podsystem zarówno przez graficzną konsolę, jak i linię komend CLI. W następnej części cyklu przyjrzymy się ostatniemu z 3 mechanizmów odpowiedzialnych za logowanie – profilom logowania.