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

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

Что

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

Образцы

<MessageLogging name="LogToSy>slo<g">;
  S<yslog
 >   Message[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {re<quest.qu>erypa<ram.>w}./Message
    Ho<stlog>s-01.<logg>ly.<com/H>ost
 <   Port5>14/<Port
    >Proto<colTCP/Protoc>ol
 <   FormatMessa>getru<e/FormatMe>ssage
    DateFormatyyyy-M<M-dd'T&>#39<;HH:mm:>ss.<SSSZ/Dat>eForm<at
  /Sys>l<og
  logLevelAL>ERT/logLevel
/MessageLogging

<MessageLogging name="LogToSy>slo<g">;
  S<yslog
 >   Message[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {re<quest.qu>erypa<ram.>w}./Message
    Ho<stlog>s-01.<logg>ly.c<om/Ho>st
  <  Port65>14/<Port
    >Proto<colTCP/Protoc>ol
 <   FormatMessa>getru<e/Forma>tMessage
<    SSL>Info<
       > Enab<ledtrue/>Enabl<ed
    /SS>LInfo
    DateForma<tyyMMdd-HH:>mm:<ss.SSS/>Dat<eFormat
>  /S<yslog
  l>o<gLevelWARN/logL>evel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Mess<age
    >  FileNa<metest.lo>g/FileN<ame
      FileRotationOptions rotateFileOnStar>tup="<;true"
    >    <FileRotationTypeS>IZE/FileR<otationType
   >  <   MaxFileSizeIn>MB10/MaxF<ileSizeInMB
    >  <  MaxFilesToRetai>n10/Max<FilesToRetain
      >/Fi<leRot>ati<onOption>s
  /<File
  lo>g<LevelERROR/logL>evel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Me<ssage
  >  FileNa<metest.lo>g/Fil<eName
    FileRotationOptions rotateFileOnStar>tup=&qu<ot;true"
  >    <FileRotationTypeT>IME/Fil<eRotationType
      RotationFre>qu<ency unit="mi>nute&qu<ot;10/RotationFr>eq<uency
      MaxFi>lesTo<Retain10/MaxFilesToR>eta<in
  >  /<FileRota>tionO<ptions
  >/<File
  logLevel>ERROR/logLevel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Me<ssage
  >  FileNa<metest.lo>g/Fil<eName
    FileRotationOptions rotateFileOnStar>tup=&qu<ot;true"
  >    FileR<otationTypeTIME_S>IZE/Fil<eRotationType
 >  <   MaxFileSizeIn>MB10/Ma<xFileSizeInMB
  >  <  MaxFilesToRetai>n10/Max<FilesToRetain
      RotationFre>qu<ency unit="mi>nute&<quot;10/RotationFreq>uen<cy
  >  /<FileRota>tionO<ptions
  >/<File
  logLevel>ERROR/logLevel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
  File
  ....<
  ..>..
<  /File
  Buf>ferM<essagetrue/Buf>f<erMessage
/Mess>ageLogging

Ссылка на элемент

Используйте следующие элементы для настройки типа политики MessageLogging.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

Схемы

Заметки об использовании

При присоединении политики MessageLogging к потоку API proxy рассмотрите возможность ее размещения в ответе ProxyEndpoint, в специальном потоке, называемом PostClientFlow. PostClientFlow выполняется после отправки ответа запрашивающему клиенту, что гарантирует доступность всех метрик для регистрации. Подробнее об использовании PostClientFlow см. в Справочнике по настройке API proxy .

PostClientFlow имеет два особых преимущества:

1. Он выполняется только как часть потока ответов.
2. Это единственный поток, выполняемый после того, как прокси-сервер переходит в состояние ошибки.

Поскольку он выполняется независимо от того, успешно ли выполнился прокси-сервер или нет, вы можете поместить политики MessageLogging в PostClientFlow и быть уверенным, что они всегда будут выполняться.

На следующем изображении трассировки показана политика MessageLogging, выполняемая как часть PostClientFlow после выполнения DefaultFaultRule:

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

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

<ProxyEndpoint name="def>ault"<;
  ...
  Post>Clien<tFlow
  >  Respo<nse
>      Ste<p
  >      NameMessage<-Logg>ing-1/N<ame
 >     </Step
   > /R<esponse
  /Post>ClientF<low
  ...
/Pro>xyEndpoint

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 и перезапустите Message Processor. Обратите внимание, что это свойство изначально закомментировано по умолчанию.

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

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

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

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

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

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:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor перезапустить

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

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 на Message Processors. Сообщения хранятся в каталоге, указанном в свойствах выше, а имена файлов имеют вид {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="unk>nown"This is a test message. id = {request.<header.i>d}/Message

Настройка сторонних служб управления журналами

Политика MessageLogging позволяет отправлять сообщения syslog в сторонние службы управления журналами, такие как Splunk, Sumo Logic и Loggly. Если вы хотите отправлять syslog в одну из этих служб, см. документацию этой службы, чтобы настроить хост, порт и протокол службы, а затем соответствующим образом настроить элемент 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-which-host-shou.html
  • Полный пример использования Sumo Logic в качестве сервиса ведения журнала см. в следующем сообщении Apigee Community. Решение использует единую политику JavaScript для выполнения HTTP-запросов POST к Sumo Logic HTTP Source Collector: 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: Справочник переменных