Zasada MessageLogging

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

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 w przypadku 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ć w postClientFlow zasady MessageLogging, mając pewność, że będą one zawsze wykonywane.

Na poniższym obrazie śledzenia 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 prosty tekst. Możesz skonfigurować rejestrowanie, aby obejmowało ono zmienne, takie jak: data i godzina otrzymania żądania lub odpowiedzi, tożsamość użytkownika w żądaniu, adres IP źródłowy, 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.

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 był przepływem Error. Jeśli chcesz rejestrować 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 dziennika 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ępując myślniki 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 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, 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 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. Zrestartuj komponent Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud w wersji 4.15.07 i wcześniejszych

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 mają być przechowywane pliki 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 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 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 wpisie w społeczności Apigee. Rozwiązanie korzysta z pojedynczej reguły JavaScript do wysyłania żądań HTTP POST do źródła danych HTTP Sumo Logic: 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

Odwołania do błędów

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

Gdy wystąpi błąd w zasadach, zostaną wypełnione te zmienne.

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

Powiązane artykuły

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