Zasada MessageLogging

Wyświetlasz dokumentację Apigee Edge.
Zapoznaj się z dokumentacją Apigee X. info

Co

Jednym z najlepszych sposobów na wykrywanie problemów w środowisku wykonawczym interfejsu API jest rejestrowanie komunikatów. Możesz dołączyć do interfejsu API zasadę MessageLogging i skonfigurować ją tak, aby rejestrowała niestandardowe wiadomości na dysku lokalnym (tylko Edge dla chmury prywatnej) lub w syslogu.

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>

Odwołanie do elementu

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

Zastosowanie

Gdy dołączasz zasadę MessageLogging do przepływu proxy interfejsu API, rozważ umieszczenie jej w odpowiedzi ProxyEndpoint w specjalnym przepływie o nazwie PostClientFlow. PostClientFlow jest wykonywany po wysłaniu odpowiedzi do klienta, który wysłał żądanie. Dzięki temu wszystkie dane są dostępne do rejestrowania. Więcej informacji o używaniu PostClientFlow znajdziesz w dokumentacji konfiguracji proxy interfejsu API.

PostClientFlow jest wyjątkowy z 2 powodów:

1. Została ona wykonana tylko w ramach przepływu odpowiedzi.
2. Jest to jedyny przepływ wykonywany po przejściu serwera proxy w stan błędu.

Jest on wykonywany niezależnie od tego, czy serwer proxy działa prawidłowo, czy nie. Dlatego możesz umieścić zasady MessageLogging w PostClientFlow i mieć pewność, że zawsze będą wykonywane.

Obraz śledzenia poniżej pokazuje zasadę MessageLogging wykonywaną w ramach PostClientFlow po wykonaniu zasady DefaultFaultRule:

W tym przykładzie zasada Verify API Key spowodowała błąd z powodu nieprawidłowego klucza.

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

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

Edge rejestruje komunikaty jako zwykły tekst. Możesz skonfigurować rejestrowanie tak, aby obejmowało zmienne, takie jak data i godzina otrzymania żądania lub odpowiedzi, tożsamość użytkownika w żądaniu, źródłowy adres IP, z którego zostało wysłane żądanie, i tak dalej. Usługa Edge Logs wysyła wiadomości asynchronicznie, co oznacza, że do interfejsu API nie są wprowadzane żadne opóźnienia, które mogłyby być spowodowane blokowaniem wywołań.

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

Użytkownicy mogą napotykać opóźnienia w odbieraniu wiadomości z logami wysyłanych do nowego punktu końcowego syslog. Wynika to z zamierzonego działania „zimnego startu” w zasadach. Gdy skonfigurowane zostanie nowe miejsce docelowe logowania, oprócz istniejących miejsc docelowych logowania procesor wiadomości może najpierw umieścić w pamięci 1000 wiadomości dziennika w kolejce przed ich wysłaniem. Może to spowodować początkowe opóźnienie w środowiskach o niskim natężeniu ruchu. Początkowe opóźnienie jest niewidoczne w przypadku typowych zadań produkcyjnych, ponieważ wiadomości powinny gromadzić się szybko. Gdy osiągniesz próg, wiadomości dziennika będą dostarczane zgodnie z oczekiwaniami. Płynne ponowne uruchomienie procesora wiadomości może również spowodować dostarczenie wiadomości w kolejce, gdy będą z niej usuwane.

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

Log message size exceeded. Increase the max message size setting

Jeśli ten problem występuje w Edge for Private Cloud w wersji 4.15.07 lub starszej, znajdź plik message-logging.properties i skorzystaj z tego rozwiązania:

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 i nowszych ustaw właściwość conf/message-logging.properties+max. log.message.size.in.kb w pliku /opt/apigee/customer/application/message-processor.properties i ponownie uruchom procesor wiadomości. Pamiętaj, że ta właściwość jest domyślnie zakomentowana.

Uwaga: zmienne komunikatu odpowiedzi w Edge nie są dostępne w przypadku przepływu błędów. Te zmienne nie są też dostępne w PostClientFlow, jeśli poprzednim przepływem był przepływ błędów. Jeśli chcesz rejestrować informacje o odpowiedziach z funkcji PostClientFlow, użyj obiektu message. Możesz użyć tego obiektu, aby uzyskać dostęp do nagłówków i innych informacji z odpowiedzi, niezależnie od tego, czy wystąpił błąd. Więcej informacji i przykład znajdziesz w sekcji Zmienne wiadomości.

Kontrolowanie sygnatury czasowej wiadomości dziennika w Edge for Private Cloud

Domyślnie sygnatura czasowa we wszystkich wiadomościach dziennika ma format:

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

Systemową wartość domyślną można zastąpić w przypadku miejsc docelowych syslog za pomocą elementu DateFormat. Działanie tego szablonu opisano w dokumentacji klasy SimpleDateFormat w języku Java. Zgodnie z tą definicją yyyy zostanie zastąpiony 4-cyfrowym rokiem, MM – 2-cyfrowym numerem miesiąca itd. Powyższy format może dać ciąg znaków w tej postaci:

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

Format ten możesz kontrolować za pomocą 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ępując kreski ukośnikami i skracając rok do 2 cyfr, rejestruje znacznik czasu 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 w odpowiedni sposób:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Zapisz zmiany.
4. Sprawdź, czy plik właściwości należy do użytkownika „apigee”:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Uruchom ponownie procesor wiadomości Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Lokalizacja pliku logu w Edge for Private Cloud

Edge for Private Cloud w wersji 4.16.01 i nowszej

Domyślnie logi wiadomości w chmurze prywatnej znajdują się w tym katalogu na węzłach Message Processor:

/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 na procesorach wiadomości:

• bin_setenv_data_dir - Ustawia ścieżkę główną 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.
  
  jeśli ustawisz ścieżkę bezwzględną, np. conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, logi 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ż jest ona domyślnie zakomentowana. Więcej informacji znajdziesz w sekcji Ustawianie tokena, który jest obecnie zakomentowany.

Jeśli chcesz przechowywać pliki dziennika w strukturze płaskiej, tak aby wszystkie pliki dziennika były umieszczane w tym samym katalogu, w pliku message-logging.properties ustaw wartość conf/message-logging.properties+enable.flat.directory.structure na true. Wiadomości są przechowywane w katalogu określonym przez powyższe 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 właściwości w odpowiedni sposób:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Zapisz zmiany.
4. Sprawdź, czy plik właściwości należy do użytkownika „apigee”:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Uruchom ponownie komponent Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 i starsze

Domyślnie dzienniki wiadomości znajdują się w tych miejscach na 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 na procesorach wiadomości:

• data.dir – ustawia ścieżkę główną do przechowywania plików dziennika. Na przykład data.dir=/opt/apigee4/var/log
• log.root.dir – jeśli ustawisz ś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 właściwości spowoduje ustawienie katalogu logowania na /opt/apigee4/var/log/custom/folder/messagelog/ (zauważ, że /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 parametrze log.root.dir ma pierwszeństwo przed parametrem data.dir.

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

Wartości domyślne 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 można rozpoznać zmiennej request.header.id, jej wartość zostanie zastąpiona wartością unknown.

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

Możesz określić wspólną wartość domyślną dla wszystkich nierozwiązanych zmiennych, ustawiając atrybut defaultVariableValue w elemencie Message:

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

Konfigurowanie usług zarządzania logami innych firm

Zasady MessageLogging umożliwiają 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ć jej hosta, port i protokół, a następnie odpowiednio ustaw element Syslog w tych zasadach.

Informacje o konfiguracji zarządzania logami innych firm znajdziesz w tych dokumentach:

• Splunk (wybierz wersję produktu)
  Zobacz też ten post na forum Apigee Community: Log messages into Splunk (Logowanie wiadomości w Splunk)
• Sumo Logic
  • Zobacz też ten post na forum społeczności Apigee: Setting up logging with Sumo Logic, which host should I use?
  • Pełny przykład korzystania z usługi Sumo Logic jako usługi rejestrowania znajdziesz w tym poście na forum społeczności Apigee. Rozwiązanie korzysta z jednej zasady JavaScriptu do wysyłania żądań HTTP POST do kolektora źródła HTTP Sumo Logic: Logowanie do Sumo Logic za pomocą JavaScriptu i HTTP
• Loggly
  W przypadku korzystania z usługi Loggly element <FormatMessage>true</FormatMessage> jest wymagany w zasadach jako element podrzędny elementu <Syslog>.
  Więcej informacji o rejestrowaniu wiadomości w Loggly znajdziesz w tym poście na forum społeczności Apigee:Rejestrowanie wiadomości w Loggly

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

W przypadku niepowodzenia zasad wypełniane są te zmienne:

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

Powiązane artykuły

• Zmienne udostępniane przez Edge: Dokumentacja zmiennych