Przejdź do treści

Logowanie komunikatów do pliku

Do logowania komunikatów do pliku używane jest narzędzie Serilog.

Domyślna konfiguracja dostarczana z Neosem

Z Neosem jest dostarczany plik neos_logger.json, który odpowiada za konfigurację logowania komunikatów do pliku. 

{
   "Neos":{
      "LogMode":"ALL"
   },
   "Serilog":{
      "MinimumLevel":"Information",
      "WriteTo":[
         {
            "Name":"Conditional",
            "Args":{
               "expression":"@Level in ['Warning','Error','Fatal']",
               "configureSink":[
                  {
                     "Name":"File",
                     "Args":{
                        "path":"logs/err-.log",
                        "rollingInterval":"Day",
                        "rollOnFileSizeLimit":true,
                        "fileSizeLimitBytes":1073741824,
                        "retainedFileCountLimit":7,
                        "outputTemplate":"{Timestamp:yyyy-MM-dd HH:mm:ss.fff} <pid {ProcessId,5} tid {ThreadId,4} mem {MemoryUsage}> {SourceContext,35} [{Level:u3}] {Message:lj}{NewLine}{Exception}",
                        "formatter":"Serilog.Formatting.Json.JsonFormatter"
                     }
                  }
               ]
            }
         },
         {
            "Name":"Conditional",
            "Args":{
               "expression":"@Level in ['Debug','Verbose','Information']",
               "configureSink":[
                  {
                     "Name":"File",
                     "Args":{
                        "path":"logs/log-.log",
                        "rollingInterval":"Day",
                        "rollOnFileSizeLimit":true,
                        "fileSizeLimitBytes":1073741824,
                        "retainedFileCountLimit":7,
                        "outputTemplate":"{Timestamp:yyyy-MM-dd HH:mm:ss.fff} <pid {ProcessId,5} tid {ThreadId,4} mem {MemoryUsage}> {SourceContext,35} [{Level:u3}] {Message:lj}{NewLine}{Exception}",
                        "formatter":"Serilog.Formatting.Json.JsonFormatter"
                     }
                  }
               ]
            }
         }
      ]
   }
}
Ta konfiguracja pozwala zapisywać komunikaty, które są błędami i ostrzeżeniami do pliku err-yyyymmdd.log, a mniej ważne komunikaty do osobnego pliku log-yyyymmdd.log.

Konfiguracja logowania

Konfiguracja logowania jest dwustopniowa, poziomy konfiguracji mogą być zmieniane lub rozszerzane względem siebie, uzyskując bardziej szczegółową konfiguracje. Rozróżniamy dwa poziomy konfiguracji:

  1. Poziom domyślny - konfiguracja jest osadzona w pliku neos_logger.json wraz z podstawową konfiguracją opisaną w dalszej części dokumentacji.
  2. Poziom instancji - konfiguracja dla Neos.Runtime lub poszczególnych usług z Neos.Service

Konfiguracja domyślna

  • Lokalizacja plików: logs
  • Nazwa plików: err-yyyymmdd.log oraz log-yyyymmdd.log, gdzie yyyymmdd to data.
  • Retencja logów: 7 dni
  • Partycjonowanie logów: co 24h i/lub co 1GB
  • Minimalny poziom logowania: Information
  • Tryb logowania: ALL

Konfiguracja Instancji

Do skonfigurowania konkertnej instancji serwera, należy utworzyć plik konfiguracyjny na bazie neos_logger.json, o nazwie zgodnej z nazwą usługi, dla np. Neos.Service.Teneum - Neos.Service.Teneum.json. Dla Neos.Runtime - Neos.Runtime.json.

Opis poszczególnych parametrów w pliku neos_logger

  • rollingInterval - Interwał partycjonowania kolejnego pliku loga
  • rollOnFileSizeLimit - Parametr odpowiadający za dodanie kolejnego pliku loga, w przypadku, gdy limit wielkości pliku zostanie osiągnięty, kolejny plik będzie rozszerzony w nazwie o wartość _001, _002 etc. Jeżeli wartość będzie ustawiona na false, kolejny plik nie zostanie dodany, w konsekwencji czego logi nie będą zapisywane.
  • fileSizeLimitBytes - wielkość pliku w bajtach
  • retainedFileCountLimit - Retencja logów
  • outputTemplate - Templatka zapisu logów w pliku, jeśli parametr nie zostanie ustawiony, to w pliku dostaniemy zapis json
  • path - ścieżka oraz nazwa pliku do którego będą zrzucane logi.
  • formatter - sposób zapisu logów do pliku.

Poziomy logowania

Opcja MinimumLevel pozwala ustawić z jakiego poziomu logowania komunikaty bedą zapisywane do pliku. Domyślnie jest to Information. Jeśli chcemy mieć komunikaty, które pozwolą do prześledzenia działania jakiejś funkcji to wtedy możemy ustawić MinimumLevel na Debug. Takie ustawienie jednak może spowolnić działanie Neosa, ponieważ będzie zapisywana do pliku o wiele większa ilość komunikatów.

Poniżej lista dostępnych poziomów logowania:

Verbose - Informacje bardzo szczegółowe, poziom powinno się stosować bardzo rzadko, tylko w uzasadnionych przypadkach, gdy potrzebujemy prześledzić dokładnie wykonanie funkcji serwera.

Debug - Informacje logowane do prześledzenia działania funkcji.

Information - Informacje ogólne o działaniu systemu.

Warning - Informacje o błędach, które zostały obsłużone i nie wpływają w znaczący sposób na działanie systemu.

Error - Błędy, które uniemożliwiają poprawne działanie systemu.

Fatal - Jest fatalnie...

Tryby logowania

To z jakiego obszaru Neosa będą zapisywane logi do pliku odpowiada opcja LogMode. Domyślnie LogMode jest ustawiony na ALL, czyli komunikaty są zapisywane do pliku ze wszystkich obszarów Neosa. Jeśli jednak chcemy ograniczyć zapis komunikatów to możemy wybrać poszczególne LogMode. Oddzielamy poszczególne LogMode znakiem logicznej alternatywy '|' bez spacji.

Poniżej lista trybów logowania:

PID - włącza mechanizm dołączania informacji o numerze procesu i wątku który dopisuje komunikat.

WORKFLOW - włącza logowanie informacji związanych z workflow.

APPSRVFUNC - włącza logowanie obszarów związanych z serwerem aplikacji.

CONNECTBIN - włącza logowanie operacji dotyczących połączenia z klientem VCL.

CONNECTWWW - włącza logowanie operacji dotyczących połączenia z klientem WEB.

ODATA - włącza logowanie obszaru ODATA.

WEBAPI - włącza logowanie obszaru WEBAPI.

WORKINGCTX - włącza logowanie funkcji obsługujących kontekst roboczy.

THREADPOOL - włącza logowanie mechanizmu obsługującego pulę wątków.

DB - Włacza logowanie funkcji obsługujących bazę danych i od 4.7 także treści zapytań.

DBDETAILED - Od 4.7 włącza logowanie wszystkich szczegółów funkcji bazy danych i numery transakcji[4].

DBCONNSTR - Od 4.7 włącza zapis do loga connection stringów użytych do połączenia do bazy, na której została wykonana operacja.

SCHEDULER - włącza logowanie w schedulerze.

BASICGUI - włącza zapisywanie w logu informacji generowanych przez mechanizm BasicGui.

PERFORMANCE - włącza zapisywanie w logu informacji wydajnościowych.

TEST - włącza zapisywanie w logu informacji generowanych przez moduł testowy.

IMAP - włącza mechanizm dołączania informacji module pobierania wiadomości pocztowych z serwerów IMAP.

SESSIONS - zarządzanie sesjami neosa, usuwanie bezczynnych itp.

Jeśli np. chcemy zobaczyć jakie zapytania są wykonywane do bazy danych to możemy ustawić LogMode i MinimumLevel w ten sposób:

"Neos":{
      "LogMode":"DB"
   },
   "Serilog":{
      "MinimumLevel":"Debug",

Zapis logów tylko do jednego pliku

Jeśli chcemy by logi zapisywały się tylko do jednego pliku to wtedy nasz przykładowy plik neos_logger powinien wyglądać tak:

{
  "Neos": {
    "LogMode": "ALL"
  },
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "logs/log-.log",
          "rollingInterval": "Day",
          "rollOnFileSizeLimit": true,
          "fileSizeLimitBytes": 1073741824,
          "retainedFileCountLimit": 7,
          "outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} <pid {ProcessId,5} tid {ThreadId,4} mem {MemoryUsage}> {SourceContext,35} [{Level:u3}] {Message:lj}{NewLine}{Exception}",
          "formatter": "Serilog.Formatting.Json.JsonFormatter"
        }
      }
    ]
  }
}

W powyższym przypadku wszystkie komunikaty (błędy, ostrzeżenia i informacje) będą zapisywane do pliku log-yyyymmdd.log.

Filtrowanie kontekstu

Filtrowanie korzysta z rozszerzenia Serilog Filter Expressions. Pod linkiem znajduje się dokumentacja dostępnych funkcji filtrujących.

Zewnętrzny system persystencji

Seq (zastosowania deweloperskie)

Można skonfigurować zapisywanie logów do zewnętrznego systemu gromadzenia i analizy logów Seq. Licencja darmowa pozwala na instalacje na środowisku pojedynczego dewelopera. 

    {
      "Serilog": {
        "WriteTo": [
          { "Name": "Seq", "Args": { "serverUrl": "http://localhost:5341" } }
        ]
      }
    }