Zasada MessageLogging

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. informacje

Co

Jednym z najlepszych sposobów na śledzenie problemów w środowisku uruchomienia interfejsu API jest rejestrowanie komunikatów. Możesz dołączyć i skonfigurować w interfejsie API zasadę MessageLogging, aby rejestrować wiadomości niestandardowe na dysku lokalnym (tylko Edge dla Private Cloud) lub w pliku syslog.

Przykłady

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Element referencyjny

Aby skonfigurować typ zasady MessageLogging, użyj tych elementów.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Schematy

Uwagi

Podczas dołączania zasady MessageLogging do przepływu proxy interfejsu API rozważ umieszczenie jej w odpowiedzi ProxyEndpoint w specjalnym przepływie o nazwie PostClientFlow. Funkcja PostClientFlow jest wykonywana po wysłaniu odpowiedzi do klienta, co zapewnia dostępność wszystkich danych do rejestrowania. Szczegółowe informacje o używaniu parametru PostClientFlow znajdziesz w artykule Referencje dotyczące konfiguracji serwera proxy interfejsu API.

PostClientFlow jest wyjątkowy z 2 powodów:

1. Jest ona wykonywana tylko w ramach przepływu odpowiedzi.
2. Jest to jedyny przepływ, który jest wykonywany po tym, jak serwer proxy przechodzi w stan błędu.

Jest ona wykonywana niezależnie od tego, czy wywołanie funkcji proxy zakończyło się powodzeniem czy nie. Możesz więc umieścić zasady MessageLogging w postClientFlow i mieć pewność, że będą one zawsze wykonywane.

Na tym obrazie z wynikiem działania funkcji śledzenia błędów widać, jak zasada MessageLogging jest wykonywana w ramach PostClientFlow po wykonaniu reguły DefaultFaultRule:

W tym przykładzie błąd spowodowała polityka weryfikacji klucza interfejsu API z powodu nieprawidłowego klucza.

Poniżej znajduje się definicja ProxyEndpoint, która obejmuje PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Edge rejestruje wiadomości jako zwykły tekst. Możesz skonfigurować rejestrowanie, aby obejmowało ono zmienne, takie jak: data i godzina otrzymania żądania lub odpowiedzi, tożsamość użytkownika, z którego wysłano żądanie, adres IP źródła, z którego wysłano żądanie, itp. Edge rejestruje wiadomości asynchronicznie, co oznacza, że nie wprowadza opóźnień w Twoim interfejsie API, które mogłyby być spowodowane blokowaniem wywołań.

Zasady MessageLogging zapisują zalogowane wiadomości w pamięci do bufora. Dziennik wiadomości odczytuje wiadomości z bufora, a następnie zapisze je w skonfigurowanym miejscu docelowym. Każde miejsce docelowe ma własny bufor.

Użytkownicy mogą odczuwać opóźnienia w otrzymywaniu komunikatów z dziennika wysyłanych do nowego punktu końcowego syslog. Wynika to z zamierzonego działania „zimnego startu” w ramach zasad. Gdy skonfigurowana zostanie nowa lokalizacja rejestrowania, oprócz istniejących lokalizacji rejestrowania procesor wiadomości (MP) może najpierw umieścić w kolejce 1000 wiadomości logowania w pamięci, zanim je wyśle. Może to spowodować początkowe opóźnienie w środowiskach o małej liczbie wizyt. Ta początkowa zwłoka jest niezauważalna w przypadku typowych zadań produkcyjnych, ponieważ wiadomości powinny gromadzić się szybko. Gdy zostanie osiągnięty limit, wiadomości z logu będą dostarczane zgodnie z oczekiwaniami. Ponowne uruchomienie usługi Message Processor może też spowodować dostarczenie wiadomości oczekujących w kolejce.

Jeśli szybkość zapisu do bufora wzrośnie ponad szybkość odczytu, bufor się przepełni i rejestrowanie nie powiedzie się. W takim przypadku w pliku dziennika może pojawić się komunikat:

Log message size exceeded. Increase the max message size setting

Jeśli napotkasz ten problem w Edge for Private Cloud w wersji 4.15.07 lub starszej, znajdź plik message-logging.properties i zastosuj to rozwiązanie:

Zwiększ wartość właściwości max.log.message.size.in.kb (wartość domyślna = 128 KB) w pliku message-logging.properties.

W przypadku Edge for Private Cloud w wersji 4.16.01 lub nowszej ustaw właściwość conf/message-logging.properties+max. log.message.size.in.kb w pliku /opt/apigee/customer/application/message-processor.properties i uruchom ponownie usługę Message Processor. Pamiętaj, że ta właściwość jest domyślnie skomentowana.

Uwaga: zmienne wiadomość odpowiedzi w Edge nie są dostępne w ramach procesu błędów. Te zmienne są też niedostępne w postClientFlow, jeśli poprzedni przepływ danych to ErrorFlow. Jeśli chcesz zarejestrować informacje o odpowiedzi z postClientFlow, użyj obiektu message. Za pomocą tego obiektu możesz uzyskać nagłówki i inne informacje z odpowiedzi, niezależnie od tego, czy wystąpił błąd. Więcej informacji i przykład znajdziesz w sekcji Zmienna wiadomości.

Sterowanie sygnaturą czasową wiadomości w Edge for Private Cloud

Domyślnie sygnatura czasowa we wszystkich komunikatach logowania ma format:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

Ta domyślna wartość systemowa może zostać zastąpiona w przypadku miejsc docelowych syslog za pomocą elementu DateFormat. Sposób działania tego szablonu jest opisany w dokumentacji klasy SimpleDateFormat w języku Java. Zgodnie z tą definicją yyyy zostanie zastąpione 4-cyfrowym rokiem, MM – 2-cyfrowym numerem miesiąca itd. Powyższy format może spowodować powstanie ciągu znaków w tym formacie:

2022-09-28T22:38:11.721+0000

Aby kontrolować ten format, możesz użyć właściwości conf_system_apigee.syslogger.dateFormat w procesorze wiadomości Edge. Na przykład zmiana formatu wiadomości na:

yy/MM/dd'T'HH:mm:ss.SSSZ

..zastąpienie myślników ukośnikami i skrócenie roku do 2 cyfr, rejestruje sygnaturę czasową w formacie:

22/09/28T22:38:11.721+0000

Aby zmienić format:

1. Otwórz plik message-processor.properties w edytorze. Jeśli plik nie istnieje, utwórz go:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Ustaw właściwości zgodnie z potrzebami:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Zapisz zmiany.
4. Upewnij się, że właścicielem pliku właściwości jest użytkownik „apigee”:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Uruchom ponownie Edge Message Processor:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Lokalizacja pliku z logami w Edge for Private Cloud

Edge for Private Cloud w wersji 4.16.01 lub nowszej

Domyślnie logi wiadomości z chmury prywatnej znajdują się w tym katalogu na węzłach procesora wiadomości:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Domyślną lokalizację dziennika możesz zmienić, modyfikując właściwości w pliku message-logging.properties w usługach przetwarzających wiadomości:

• bin_setenv_data_dir – ustawia ścieżkę katalogu głównego do przechowywania plików dziennika. Na przykład:bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – jeśli ustawisz ścieżkę względną, np. conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  , a jeśli ustawisz ścieżkę bezwzględną, np. conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, dzienniki wiadomości będą przechowywane w /opt/apigee/var/log/messages/messagelog/. Ścieżka bezwzględna ma pierwszeństwo przed bin_setenv_data_dir.
  
  Pamiętaj, że musisz odwołać się do właściwości jako conf/message-logging.properties+log.root.dir, ponieważ domyślnie jest ona skomentowana. Więcej informacji znajdziesz w sekcji Ustawianie tokena, który jest obecnie skomentowany.

Jeśli chcesz przechowywać pliki dziennika w strukturze plików prostych, aby wszystkie pliki dziennika były umieszczane w tym samym katalogu, ustaw wartość conf/message-logging.properties+enable.flat.directory.structure na true w pliku message-logging.properties. Wiadomości są przechowywane w katalogu określonym przez te właściwości, a nazwy plików mają postać {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Aby ustawić te właściwości:

1. Otwórz plik message-processor.properties w edytorze. Jeśli plik nie istnieje, utwórz go:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Ustaw odpowiednie właściwości:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Zapisz zmiany.
4. Upewnij się, że właścicielem pliku właściwości jest użytkownik „apigee”:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Ponownie uruchom komponent Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud w wersji 4.15.07 i starszych

Domyślnie dzienniki wiadomości znajdują się w tych procesorach wiadomości:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Domyślną lokalizację dziennika możesz zmienić, modyfikując te właściwości w pliku message-logging.properties w procesorach wiadomości:

• data.dir – określa ścieżkę do katalogu głównego, w którym są przechowywane pliki dziennika. Na przykład data.dir=/opt/apigee4/var/log.
• log.root.dir – jeśli ustawisz tę opcję jako ścieżkę względną, np. log.root.dir=custom/folder/, ścieżka zostanie dołączona do lokalizacji data.dir.

Na przykład połączenie tych 2 usług spowoduje ustawienie katalogu rejestrowania na poziomie /opt/apigee4/var/log/custom/folder/messagelog/ (uwaga: parametr /messagelog jest dodawany automatycznie).

Jeśli ustawisz ścieżkę bezwzględną, np. log.root.dir=/opt/apigee4/var/log/messages, dzienniki wiadomości będą przechowywane w katalogu /opt/apigee4/var/log/messages/messagelog/. Ścieżka bezwzględna w log.root.dir ma pierwszeństwo przed ścieżką data.dir.

Jeśli chcesz przechowywać pliki dziennika w strukturze plików prostych, aby wszystkie pliki dziennika były umieszczane w tym samym katalogu, ustaw właściwość enable.flat.directory.structure na wartość true w pliku message-logging.properties na procesorach wiadomości. Komunikaty są przechowywane w katalogu określonym przez te właściwości, a nazwy plików mają postać {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Domyślne wartości zmiennych w szablonie wiadomości

Wartości domyślne można określić oddzielnie dla każdej zmiennej w szablonie wiadomości. Jeśli na przykład nie uda się rozwiązać zmiennej request.header.id, jej wartość zostanie zastąpiona wartością unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Wspólna wartość domyślna może być określana dla wszystkich nierozwiązanych zmiennych przez ustawienie atrybutu defaultVariableValue w elemencie Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Konfigurowanie zewnętrznych usług zarządzania logami

Polityka MessageLogging umożliwia wysyłanie wiadomości syslog do zewnętrznych usług zarządzania logami, takich jak Splunk, Sumo Logic i Loggly. Jeśli chcesz wysyłać syslog do jednej z tych usług, zapoznaj się z dokumentacją tej usługi, aby skonfigurować hosta, port i protokół tej usługi, a następnie odpowiednio skonfiguruj element Syslog w tej polityce.

Aby dowiedzieć się więcej o konfiguracji zarządzania logami w usłudze innej firmy, zapoznaj się z tą dokumentacją:

• Splunk (wybierz wersję usługi)
  Zobacz też ten post na forum społeczności Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Zapoznaj się też z tym wpisem w społeczności Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • Pełny przykład użycia Sumo Logic jako usługi rejestrowania logów znajdziesz w tym poście na forum społeczności Apigee. Rozwiązanie korzysta z pojedynczej reguły JavaScript do wysyłania żądań HTTP POST do źródła danych Sumo Logic HTTP Collector: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Jeśli używasz Loggly, w zasadach musisz umieścić element <FormatMessage>true</FormatMessage> jako element podrzędny elementu <Syslog>.
  Aby dowiedzieć się więcej o rejestrowaniu wiadomości w Loggly, przeczytaj ten post na forum społeczności Apigee: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Odniesienie do błędu

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania serwera proxy zawierającego tę zasadę.

Zmienne błędów

Te zmienne są ustawiane po wystąpieniu błędu działania. Więcej informacji znajdziesz w artykule Podstawowe informacje o błędach związanych z naruszeniem zasad.

Przykładowa odpowiedź na błąd

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Przykładowa reguła błędu

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

Zmienne przepływu

Po wystąpieniu błędu w zasadach są wypełniane te zmienne:

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

Powiązane artykuły

• Zmienne udostępnione przez Edge: odwołania do zmiennych