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

Вы просматриваете документацию 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

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

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются 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: Справочник по переменным