Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Logowanie w ScriptCode

Dostępne metody logowania

W środowisku ScriptCode dostępny jest obiekt Logger, który umożliwia logowanie zdarzeń i danych z poziomu skryptu.

Wszystkie argumenty przekazane do metod Logger.<method>() są domyślnie traktowane jako dane sensytywne, czyli potencjalnie zawierające dane wrażliwe, i zostaną ukryte w logach niesensytywnych.

Dostępne metody logowania:

function callService(context) {
    Logger.info('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.debug('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.warn('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.error('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.trace('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
}

Wybór poziomu logowania

W ScriptCode używaj przede wszystkim poziomu INFO. Najważniejsze błędy i wyjątki są logowane automatycznie przez mechanizmy platformy.

Poziom

Zasada użycia w ScriptCode

INFO

Domyślny poziom logowania. Używaj do informacji diagnostycznych i biznesowych potrzebnych do prześledzenia działania skryptu.

WARN

Używaj tylko w uzasadnionych przypadkach. Przeznaczone dla istotnych i nietypowych sytuacji wymagających analizy.

ERROR

Nie używaj w ScriptCode. Błędy wymagające logowania na poziomie ERROR są obsługiwane i logowane przez platformę.

DEBUG, TRACE

Używaj do szczegółowej diagnostyki podczas developmentu. Logi te nie są dostępne na środowiskach testowych i produkcyjnych.

INFO - domyślny poziom logowania

Poziomu INFO używaj do logowania informacji potrzebnych do analizy przebiegu skryptu, np. wykonania istotnego kroku biznesowego lub podjęcia określonej ścieżki logiki.

Możesz korzystać z Logger.info(), gdy dodatkowy wpis rzeczywiście ułatwia diagnostykę. Pamiętaj jednak, aby nie duplikować danych logowanych automatycznie przez platformę i nie dodawać nadmiarowych informacji.

WARN - używany tylko w uzasadnionych przypadkach

Poziom WARN stosuj wyłącznie dla istotnych i nietypowych sytuacji, które powinny zostać zauważone i przeanalizowane.

Wpisy WARN są widoczne na środowiskach produkcyjnych i podlegają analizie, dlatego nie używaj tego poziomu jako domyślnego sposobu logowania błędów w skrypcie.

Jeżeli sytuacja jest standardowym elementem logiki biznesowej lub wpis służy wyłącznie diagnostyce działania skryptu, użyj INFO.

Jeżeli nie masz pewności, czy sytuacja wymaga użycia WARN, użyj INFO.

ERROR - nie używaj w ScriptCode

Wpisy ERROR wskazują na poważne błędy działania systemu i mogą powodować sytuację alarmową oraz powiadomienie linii wsparcia na środowisku produkcyjnym.

Błędy wymagające logowania na poziomie ERROR są obsługiwane i logowane przez mechanizmy platformy.

Wyjątki biznesowe

W ScriptCode wywołuj błędy biznesowe za pomocą mechanizmów platformy: Błędy biznesowe.

Jeżeli skrypt rzuca wyjątek biznesowy, platforma automatycznie loguje jego wystąpienie na poziomie WARN. Nie loguj tego samego zdarzenia dodatkowo za pomocą Logger.warn() ani Logger.error().

Logowanie w blokach try/catch

W blokach try/catch używaj przede wszystkim poziomu INFO.

Poziomu WARN użyj tylko wtedy, gdy przechwycona sytuacja jest na tyle istotna i nietypowa, że wymaga późniejszej analizy.

Domyślnie logowane dane

Platforma Eximee automatycznie loguje i traktuje jako sensytywne następujące elementy środowiska ScriptCode:

  • dane wejściowe formularzy (input),

  • dane wyjściowe (output),

  • treść żądań (request) wysyłanych do usług zewnętrznych, np. przez REST API,

  • treść odpowiedzi (response) otrzymywanych z tych usług.

Dane te nie są wypisywane w logach niesensytywnych w sposób umożliwiający odczytanie ich rzeczywistej zawartości. Zostają zastąpione znacznikami _SENSITIVE_DATA_START_ ... _SENSITIVE_DATA_STOP_ lub #hashed#, w zależności od typu aplikacji i kontekstu wykonania.

Logowanie sensytywne i niesensytywne

Jeśli chcemy, aby część danych została wypisana w logach niesensytywnych bez maskowania, należy użyć metody nonsensitive(), która oznacza przekazany argument jako niesensytywny.

Przykład:

W tym przykładzie:

  • arg1 zostanie zapisany w logu w formie jawnej,

  • arg2 zostanie ukryty (zastąpiony przez znacznik danych sensytywnych).

Używaj nonsensitive() tylko wtedy, gdy masz pewność, że przekazana wartość nie zawiera danych wrażliwych. Jeżeli masz wątpliwości, pozostaw wartość jako sensytywną.

Format logów

Poniżej przedstawiono przykłady formatów logów dla różnych aplikacji platformy Eximee.

Aplikacja process-handlers

Aplikacja webforms

Dobre praktyki

  • Do logowania w ScriptCode używaj wyłącznie obiektu Logger.

  • Domyślnie używaj poziomu INFO.

  • Poziomu WARN używaj bardzo rzadko i tylko dla istotnych, nietypowych sytuacji wymagających analizy.

  • Nie używaj Logger.error() - błędy na poziomie ERROR loguje platforma.

  • Nie loguj ponownie danych wejściowych, wyjściowych, requestów ani response'ów, jeżeli platforma już je loguje.

  • Nie loguj ponownie wyjątków biznesowych.

  • Używaj nonsensitive() tylko dla danych, co do których masz pewność, że nie są wrażliwe.

  • Unikaj logowania całych obiektów, dużych struktur danych i informacji, które nie są potrzebne do diagnostyki.

WsteczWprowadzenie do ScriptCode
DalejSkrypty (ScriptService)

Ostatnia aktualizacja

Czy to było pomocne?