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

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

Что

Один из лучших способов отслеживания проблем в среде выполнения API — регистрация сообщений. Вы можете подключить и настроить политику регистрации сообщений в своем 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.

<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 записывает зарегистрированные сообщения в память в буфер. Регистратор сообщений считывает сообщения из буфера, а затем записывает их в указанное вами место назначения. Каждый пункт назначения имеет свой собственный буфер.

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

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, если предыдущий поток был потоком ошибок. Если вы хотите регистрировать информацию об ответе из PostClientFlow, используйте объект сообщения . Вы можете использовать этот объект для получения заголовков и другой информации из ответа независимо от того, произошла ли ошибка. См. Переменные сообщения для получения дополнительной информации и примера.

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

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

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

Это общесистемное значение по умолчанию можно переопределить для мест назначения системного журнала с помощью элемента DateFormat . Поведение этого шаблона описано в документации Java-класса SimpleDateFormat . Согласно этому определению, 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

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

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=гг/ММ/дд'Т'ЧЧ:мм:сс.SSSZ
3. Сохраните изменения.
4. Убедитесь, что файл свойств принадлежит пользователю apigee:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Перезапустите пограничный процессор сообщений:
   > /opt/apigee/apigee-service/bin/apigee-service перезапуск процессора Edge-message

Расположение файла журнала в 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

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 позволяет отправлять сообщения системного журнала в сторонние службы управления журналами, такие как Splunk, Sumo Logic и Loggly. Если вы хотите отправить системный журнал в одну из этих служб, см. документацию этой службы, чтобы настроить хост, порт и протокол службы, а затем соответствующим образом установите элемент Syslog в этой политике.

См. следующую документацию для настройки стороннего управления журналами:

• Splunk (выберите версию продукта)
  Также ознакомьтесь с этим сообщением сообщества Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html .
• Сумо Логика
  • Также ознакомьтесь с этим сообщением сообщества Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-that-host-shou.html .
  • Полный пример использования Sumo Logic в качестве службы ведения журналов см. в следующем сообщении сообщества Apigee. В решении используется единая политика JavaScript для отправки запросов HTTP POST к сборщику исходного кода HTTP Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html .
• Логгли
  При использовании Loggly в политике требуется <FormatMessage>true</FormatMessage> как дочерний элемент <Syslog> .
  Также ознакомьтесь с этим сообщением сообщества Apigee для получения дополнительной информации о регистрации сообщений в Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

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

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