Zasada MessageLogging

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

Co

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

Próbki

<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

Użyj poniższych elementów, aby skonfigurować typ zasady MessageLogging.

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

Schematy

Uwagi o wykorzystaniu

Gdy dołączasz zasadę MessageLogging do przepływu pracy serwera proxy interfejsu API, rozważ umieszczenie jej w odpowiedzi ProxyEndpoint w specjalnym procesie o nazwie PostClientFlow. Proces PostClientFlow jest wykonywany po wysłaniu odpowiedzi do klienta, który wysłał żądanie, dzięki czemu wszystkie wskaźniki są dostępne do logowania. Szczegółowe informacje o korzystaniu z PostClientFlow znajdziesz w dokumentacji konfiguracji serwera proxy interfejsu API.

Metoda PostClientFlow jest wyjątkowa pod dwoma względami:

1. Wykonano je tylko w ramach przepływu odpowiedzi.
2. Jest to jedyny proces wykonywany po przejściu serwera proxy w stan błędu.

Ponieważ jest on wykonywany niezależnie od tego, czy serwer proxy się powiódł, czy nie, możesz umieścić zasady MessageLogging w PostClientFlow i mieć pewność, że będą zawsze wykonywane.

Poniższy obraz logu czasu przedstawia zasadę MessageLogging wykonywaną w ramach PostClientFlow po wykonaniu reguły DefaultFaultRule:

W tym przykładzie błąd wynikał z zasady Verify API Key (Weryfikacja klucza interfejsu API) z powodu nieprawidłowego klucza.

Poniżej znajduje się definicja punktu końcowego serwera proxy, która zawiera interfejs PostClientFlow:

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

Komunikaty logów brzegowych mogą mieć postać zwykłego tekstu. Możesz skonfigurować logowanie, 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 itd. Komunikaty logów brzegowych są wysyłane asynchronicznie, co oznacza, że interfejs API nie ma opóźnień spowodowanych blokowaniem wywołań.

Zasada MessageLogging zapisuje zarejestrowane wiadomości w pamięci w buforze. Rejestrator wiadomości odczytuje komunikaty z bufora, a następnie zapisuje je w zdefiniowanym przez Ciebie miejscu docelowym. Każde miejsce docelowe ma własny bufor.

Jeśli szybkość zapisu w buforze przekroczy wartość odczytu, bufor się przepełni, a logowanie się nie uda. W takim przypadku w pliku logu możesz zobaczyć komunikat zawierający te informacje:

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 użyj tego rozwiązania:

Zwiększ właściwość 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 ponownie uruchom procesor wiadomości. Pamiętaj, że ta właściwość jest początkowo domyślnie komentowana.

Uwaga: zmienne wiadomości odpowiedzi w Edge nie są dostępne w przepływie błędów. Te zmienne są też niedostępne w PostClientFlow, jeśli poprzedni przepływ był procesem błędu. Jeśli chcesz rejestrować informacje o odpowiedziach z PostClientFlow, użyj obiektu message. Możesz użyć tego obiektu, aby 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 Zmienne wiadomości.

Kontrola sygnatury czasowej komunikatu logu w Edge dla Private Cloud

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

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

To domyślne ustawienie systemu można zastąpić dla miejsc docelowych protokołu Syslog za pomocą elementu DateFormat. Działanie tego szablonu zostało opisane w dokumentacji klasy SimpleDateFormat w języku Java. Zgodnie z tą definicją ciąg yyyy zostanie zastąpiony 4-cyfrowym numerem roku, MM zostanie zastąpiony dwucyfrowym numerem miesiąca itd. Powyższy format może spowodować utworzenie ciągu znaków w postaci takiej:

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 brzegowych. Możesz na przykład zmienić format wiadomości na:

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

..zastępowanie myślników ukośnikami i skrócenie do 2-cyfrowego roku powoduje zarejestrowanie sygnatury czasowej 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 odpowiednie właściwości:
   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 komunikatów brzegowych:
   > /opt/apigee/apigee-service/bin/apigee-service side-message-processor restart

Lokalizacja pliku logu w Edge dla Private Cloud

Edge dla Private Cloud w wersji 4.16.01 i nowszych

Domyślnie logi wiadomości Private Cloud znajdują się w węzłach procesora wiadomości w tym katalogu:

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

• bin_setenv_data_dir – ustawia ścieżkę główną do przechowywania plików logów. Na przykład: bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – jeśli ustawisz tutaj ś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 ścieżką bin_setenv_data_dir.
  
  Pamiętaj, że musisz odwoływać się do właściwości jako conf/message-logging.properties+log.root.dir, ponieważ domyślnie jest ona oznaczona komentarzem. Więcej informacji znajdziesz w sekcji Ustawianie tokena, który jest obecnie komentowany.

Jeśli chcesz przechowywać pliki dziennika w płaskiej strukturze, tak aby wszystkie pliki dziennika znajdowały się w tym samym katalogu, w pliku message-logging.properties ustaw parametr 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 odpowiednie właściwości:
   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. Ponownie uruchom komponent Edge:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

Edge dla Private Cloud w wersji 4.15.07 i starszych

Domyślnie logi wiadomości znajdują się w:

/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 – ustawia ścieżkę główną do przechowywania plików logów. Przykład: data.dir=/opt/apigee4/var/log
• log.root.dir – jeśli ustawisz tutaj ścieżkę względną, np. log.root.dir=custom/folder/, zostanie ona dodana do lokalizacji data.dir.

Na przykład kombinacja tych 2 właściwości ustawi katalog logowania na /opt/apigee4/var/log/custom/folder/messagelog/ (katalog /messagelog jest dodawany automatycznie).

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

Jeśli chcesz przechowywać pliki logów w postaci płaskiej struktury plików, tak aby wszystkie pliki dziennika znajdowały się w tym samym katalogu, ustaw dla właściwościenable.flat.directory.structure wartość true w pliku message-logging.properties w systemie przetwarzania wiadomości. 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}.

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 np. nie można znaleźć zmiennej request.header.id, jej wartość zostaje zastąpiona wartością unknown.

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

Wspólną wartość domyślną można określić dla wszystkich nierozstrzygniętych zmiennych, ustawiając w elemencie Message atrybut defaultVariableValue:

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

Konfigurowanie usług zarządzania dziennikami innych firm

Zasada MessageLogging umożliwia wysyłanie komunikatów syslog do usług zarządzania logami innych firm, takich jak Splunk, Sumo Logic i Loggly. Jeśli chcesz wysł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 tej zasadzie.

Aby dowiedzieć się więcej o konfiguracji zarządzania dziennikami w systemie innej firmy, zapoznaj się z tą dokumentacją:

• Splunk (wybierz wersję usługi)
  Zobacz też tego posta na karcie Społeczność Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Zobacz też tego posta na karcie Społeczność Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-That-host-shou.html
  • Pełny przykład wykorzystania Sumo Logic jako usługi logowania znajdziesz w poniższym poście na karcie Społeczność Apigee. To rozwiązanie używa jednej zasady JavaScript do wysyłania żądań HTTP POST do kolektora źródła HTTP Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Jeśli używasz Loggly, musisz umieścić w zasadzie <FormatMessage>true</FormatMessage> element podrzędny elementu <Syslog>.
  Zapoznaj się też z tym postem na karcie Społeczność Apigee, w którym znajdziesz więcej informacji o logowaniu komunikatów do Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Informacje o błędzie

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

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 te zasady.

Zmienne błędów

Te zmienne są ustawiane, gdy wystąpi błąd środowiska wykonawczego. Więcej informacji znajdziesz w artykule Co musisz wiedzieć 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 błędu zgodności z zasadami te zmienne są wypełniane.

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

Powiązane artykuły

• Zmienne wyświetlane przez krawędź: informacje o zmiennych