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

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

Что

Один из лучших способов отслеживания проблем в среде выполнения 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:

В этом примере политика проверки ключа 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

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

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

Для управления этим форматом можно использовать свойство conf_system_apigee.syslogger.dateFormat в Edge Message Processor. Например, можно изменить формат сообщения на:

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

..заменив тире на косые черты и сократив год до 2 цифр, можно записать временную метку в форме:

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 Message:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

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

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