Zasada MessageLogging

Wyświetlasz dokumentację Apigee Edge.
Otwórz 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. Funkcja PostClientFlow jest wykonywana 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 ona wykonywana niezależnie od tego, czy proxy działa prawidłowo, czy nie. Dlatego możesz umieścić zasady MessageLogging w PostClientFlow i mieć pewność, że zawsze zostaną wykonane.

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

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

Poniżej znajduje się definicja punktu końcowego proxy, 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 logów wysyłanych do nowego punktu końcowego syslog. Wynika to z zamierzonego działania „uruchomienia „na zimno”” w zasadach. Gdy skonfigurujesz nowe miejsce docelowe logowania, Procesor komunikatów (MP) może najpierw umieścić w pamięci 1000 komunikatów logu w kolejce, zanim je wyśle. 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. Wykonanie restartu bez utraty danych procesora komunikatów 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 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 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 komunikatów. 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 poprzedni przepływ był przepływem błędu. Jeśli chcesz rejestrować informacje o odpowiedzi z 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 komunikatu logu w Edge for Private Cloud

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

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

To domyślne ustawienie systemowe 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 komunikatów 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 komunikatów 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 w wersji 4.15.07 i starszych

Domyślnie dzienniki wiadomości znajdują się w tym miejscu 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/ (pamiętaj, ż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 wartość właściwości enable.flat.directory.structure na true w pliku message-logging.properties na procesorach wiadomości. Wiadomości są przechowywane w katalogu określonym przez powyższe właściwości, a nazwy plików mają format {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ć dla każdej zmiennej w szablonie wiadomości osobno. Jeśli na przykład zmienna request.header.id nie może zostać rozpoznana, jej wartość jest zastępowana 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ć hosta, port i protokół usługi, 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 społeczności Apigee: 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, aby wysyłać żądania HTTP POST do kolektora źródła HTTP Sumo Logic: Logowanie do Sumo Logic za pomocą JavaScriptu i HTTP
• Loggly
  W przypadku korzystania z 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

Odwołanie 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