Правило MessageLogging

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Что

Один из лучших способов выявить проблемы в среде выполнения API – это регистрировать сообщения. Вы можете прикрепить и настроить правило MessageLogging к API, чтобы регистрировать специальные сообщения на локальном диске (только в Edge для частного облака) или в системном журнале.

Примеры

<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>

Сведения об элементах

Чтобы настроить тип правил MessageLogging, используйте следующие элементы:

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

<FileName>mylog.log</FileName>

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

Схемы

Замечания по использованию

При прикреплении правила MessageLogging к потоку прокси-сервера API рассмотрите возможность размещения его в ответе ProxyEndpoint в специальном потоке PostClientFlow. Функция PostClientFlow выполняется после того, как ответ отправлен клиенту, запросившему его. Это гарантирует, что все показатели будут доступны для регистрации. Подробнее об использовании PostClientFlow можно узнать в справочнике по конфигурации прокси-сервера API.

PostClientFlow отличается от других потоков двумя особенностями:

1. Она выполнялась только в рамках процесса ответа.
2. Это единственный поток, который выполняется после того, как прокси-сервер переходит в состояние ошибки.

Поскольку он выполняется независимо от того, удалось ли прокси-серверу подключиться, вы можете разместить правила MessageLogging в PostClientFlow и быть уверенными, что они всегда будут выполняться.

На изображении ниже показан трассировочный файл, в котором политика MessageLogging выполняется как часть PostClientFlow после выполнения DefaultFaultRule:

В этом примере сбой произошел из-за недопустимого ключа, который был обнаружен правилом Verify API Key.

Ниже приведено определение ProxyEndpoint, включающее PostClientFlow:

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

Edge регистрирует сообщения в виде обычного текста. Вы можете настроить ведение журнала так, чтобы в него включались переменные, например дата и время получения запроса или ответа, идентификатор пользователя в запросе, исходный IP-адрес, с которого был отправлен запрос, и т. д. Сообщения в журналы Edge записываются асинхронно, поэтому задержки, которые могут быть вызваны блокировкой вызовов, не влияют на ваш API.

Правило MessageLogging записывает зарегистрированные сообщения в буфер в памяти. Регистратор сообщений считывает сообщения из буфера и записывает их в настроенный вами пункт назначения. У каждого пункта назначения есть свой буфер.

Пользователи могут столкнуться с задержками при получении сообщений журнала, отправленных в новую конечную точку syslog. Это связано с предусмотренным правилом поведением при холодном запуске. Когда наряду с существующими целевыми папками для журналов настраивается новая, процессор сообщений может сначала поместить в память 1000 сообщений журнала, прежде чем отправить их. В средах с низким трафиком это может привести к начальной задержке. Эта начальная задержка не заметна при типичных рабочих нагрузках, поскольку сообщения должны накапливаться быстро. После достижения порогового значения сообщения журнала будут доставляться как обычно. При корректном перезапуске обработчика сообщений также может быть запущена доставка сообщений, находящихся в очереди.

Если скорость записи в буфер превышает скорость чтения, буфер переполняется и ведение журнала прекращается. В этом случае в файле журнала может появиться сообщение следующего содержания:

Log message size exceeded. Increase the max message size setting

Если вы столкнулись с этой проблемой в Edge для частного облака версии 4.15.07 или более ранней, найдите файл message-logging.properties и воспользуйтесь следующим решением:

Увеличьте значение свойства max.log.message.size.in.kb (по умолчанию 128 КБ) в файле message-logging.properties.

В Edge для частного облака версии 4.16.01 и более поздних задайте свойство conf/message-logging.properties+max. log.message.size.in.kb в файле /opt/apigee/customer/application/message-processor.properties и перезапустите процессор сообщений. Обратите внимание, что по умолчанию это свойство закомментировано.

Примечание. переменные сообщения ответа в Edge недоступны в потоке ошибок. Эти переменные также недоступны в PostClientFlow, если предыдущим был Error Flow. Если вы хотите зарегистрировать информацию об ответе из PostClientFlow, используйте объект message. Этот объект можно использовать для получения заголовков и другой информации из ответа независимо от того, произошла ли ошибка. Подробнее о переменных сообщений…

Управление временной меткой сообщения в журнале в Edge для частного облака

По умолчанию временная метка во всех сообщениях журнала имеет следующий формат:

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

Системное значение по умолчанию можно переопределить для целевых системных журналов с помощью элемента DateFormat. Поведение этого шаблона описано в документации по классу SimpleDateFormat в Java. Согласно этому определению, yyyy будет заменено на четырехзначный год, MM – на двузначный номер месяца и т. д. В результате может получиться строка следующего вида:

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

Чтобы задать формат, используйте свойство conf_system_apigee.syslogger.dateFormat в процессоре сообщений Edge. Например, можно изменить формат сообщения на:

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

..заменяя дефисы косой чертой и сокращая год до двух цифр, записывает временную метку в следующем формате:

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

Чтобы изменить формат:

1. Откройте файл message-processor.properties в редакторе. Если файла нет, создайте его:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Задайте нужные свойства:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Сохраните изменения.
4. Убедитесь, что файл свойств принадлежит пользователю apigee:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Перезапустите процессор сообщений Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Местоположение файлов журналов в Edge для Private Cloud

Edge for Private Cloud 4.16.01 и более поздние версии

По умолчанию журналы сообщений частного облака находятся в следующем каталоге на узлах обработчика сообщений:

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

Вы можете изменить местоположение журнала по умолчанию, изменив свойства в файле message-logging.properties на процессорах сообщений:

• bin_setenv_data_dir – задает корневой путь для хранения файлов журналов. Пример: bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – если вы зададите относительный путь, например conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  Если вы зададите абсолютный путь, например conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, журналы сообщений будут храниться в /opt/apigee/var/log/messages/messagelog/. Абсолютный путь имеет приоритет над правилом bin_setenv_data_dir.
  
  Обратите внимание, что вам нужно указать свойство как conf/message-logging.properties+log.root.dir, поскольку по умолчанию оно закомментировано. Подробнее о том, как задать токен, который в настоящее время закомментирован…

Если вы хотите хранить файлы журналов в неструктурированном виде, чтобы все файлы журналов помещались в один каталог, задайте для параметра conf/message-logging.properties+enable.flat.directory.structure значение true в файле message-logging.properties. Письма хранятся в каталоге, указанном в свойствах выше, а имена файлов имеют вид {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Чтобы задать эти свойства:

1. Откройте файл message-processor.properties в редакторе. Если файла нет, создайте его:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Задайте нужные свойства:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Сохраните изменения.
4. Убедитесь, что файл свойств принадлежит пользователю apigee:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Перезапустите компонент Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 и более ранние версии

По умолчанию журналы сообщений находятся в следующем расположении на процессорах сообщений:

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

Вы можете изменить местоположение журнала по умолчанию, изменив следующие свойства в файле message-logging.properties на процессорах сообщений:

• data.dir – задает корневой путь для хранения файлов журналов. Пример: data.dir=/opt/apigee4/var/log
• log.root.dir – если вы зададите относительный путь, например log.root.dir=custom/folder/, он будет добавлен к местоположению data.dir.

Например, если объединить эти два свойства, каталог регистрации будет установлен на уровне /opt/apigee4/var/log/custom/folder/messagelog/ (обратите внимание, что /messagelog добавляется автоматически).

Если вы зададите абсолютный путь, например log.root.dir=/opt/apigee4/var/log/messages, журналы сообщений будут храниться в каталоге /opt/apigee4/var/log/messages/messagelog/. Абсолютный путь в log.root.dir имеет приоритет над data.dir.

Если вы хотите хранить файлы журналов в плоской структуре, чтобы все файлы журналов помещались в один каталог, задайте для свойства enable.flat.directory.structure значение true в файле message-logging.properties на процессорах сообщений. Сообщения хранятся в каталоге, указанном в свойствах выше, а названия файлов имеют формат {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Значения по умолчанию для переменных в шаблоне письма

Значения по умолчанию можно задать для каждой переменной в шаблоне сообщения отдельно. Например, если переменная request.header.id не может быть разрешена, ее значение заменяется на unknown.

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

Для всех неразрешенных переменных можно задать общее значение по умолчанию, указав атрибут defaultVariableValue в элементе Message:

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

Как настроить сторонние сервисы управления журналами

Правило MessageLogging позволяет отправлять сообщения syslog в сторонние сервисы управления журналами, такие как Splunk, Sumo Logic и Loggly. Если вы хотите отправлять syslog в один из этих сервисов, ознакомьтесь с документацией к нему, чтобы настроить хост, порт и протокол сервиса, а затем задайте элемент Syslog в этих правилах.

Информацию о настройке сторонних систем управления журналами можно найти в следующих документах:

• Splunk (выберите версию продукта)
  Также ознакомьтесь с записью в сообществе Apigee: Как записывать сообщения журнала в Splunk
• Sumo Logic
  • Также ознакомьтесь с записью в сообществе Apigee: Setting up logging with Sumo Logic, which host should I use? (Настройка ведения журналов с помощью Sumo Logic: какой хост следует использовать?).
  • Полный пример использования Sumo Logic в качестве сервиса ведения журналов приведен в следующем сообщении на форуме Apigee Community. В решении используется одно правило JavaScript для отправки HTTP-запросов POST в коллектор источников HTTP Sumo Logic: Ведение журналов в Sumo Logic с помощью JavaScript и HTTP.
• Loggly
  При использовании Loggly в правилах в качестве дочернего элемента элемента <Syslog> требуется указать <FormatMessage>true</FormatMessage>.
  Также ознакомьтесь с записью на форуме сообщества Apigee, в которой рассказывается о том, как регистрировать сообщения в Loggly: Как регистрировать сообщения в Loggly

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются Edge, когда это правило вызывает ошибку. Эта информация важна, если вы разрабатываете правила обработки ошибок. Подробнее о том, что нужно знать об ошибках в правилах и об обработке ошибок…

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Ошибки развертывания

Эти ошибки могут возникать при развертывании прокси-сервера, содержащего это правило.

Переменные ошибок

Эти переменные задаются при возникновении ошибки выполнения. Подробнее о нарушениях правил…

Пример ответа об ошибке

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

Пример правила обработки ошибок

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

Переменные процесса

При нарушении правил заполняются следующие переменные:

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

Статьи по теме

• Переменные, доступные в Edge: справочник по переменным