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

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

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

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