Политика ведения журнала сообщений

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

Что

Один из лучших способов выявления проблем в среде выполнения API — это логирование сообщений. Вы можете прикрепить и настроить политику логирования сообщений для вашего API, чтобы записывать пользовательские сообщения на локальный диск (только для Edge for Private Cloud) или в syslog.

Образцы

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

В этом примере ошибка возникла из-за политики проверки ключа API, которая привела к сбою в работе из-за недействительного ключа.

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

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

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

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

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

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

Log message size exceeded. Increase the max message size setting

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

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

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

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

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

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

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

Этот общесистемный параметр по умолчанию можно переопределить для мест назначения syslog с помощью элемента 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 для частного облака

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.
• Логика сумо
  • Также ознакомьтесь с этой записью на форуме Apigee: Настройка логирования с помощью Sumo Logic: какой хост следует использовать?
  • Полный пример использования Sumo Logic в качестве службы логирования см. в следующем сообщении на форуме Apigee Community. Решение использует единую политику JavaScript для отправки HTTP POST-запросов к Sumo Logic HTTP Source Collector: Logging to Sumo Logic using JavaScript and HTTP
• Логгли
  При использовании Loggly в политике требуется, чтобы <FormatMessage>true</FormatMessage> был дочерним элементом элемента <Syslog> .
  Также ознакомьтесь с этой записью на форуме Apigee Community для получения дополнительной информации о записи сообщений в Loggly: Запись сообщений в Loggly

Ссылка на ошибку

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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: Справочник по переменным