Política MessageLogging

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que

Uma das melhores maneiras de rastrear problemas no ambiente de execução da API é registrar mensagens. Você pode anexar e configurar uma política MessageLogging em sua API para registrar mensagens personalizadas em um disco local (somente no Edge para nuvem privada) ou no syslog.

Amostras

<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>

Referência de elemento

Use os elementos a seguir para configurar o tipo de política MessageLogging.

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

Esquemas

Observações sobre o uso:

Ao anexar uma política MessageLogging a um fluxo de proxy da API, considere colocá-la na resposta ProxyEndpoint, em um fluxo especial chamado PostClientFlow. O PostClientFlow é executado depois que a resposta é enviada ao cliente solicitante. Isso garante que todas as métricas estejam disponíveis para geração de registros. Para detalhes sobre como usar o PostClientFlow, consulte a referência de configuração de proxy da API.

O PostClientFlow é especial de duas maneiras:

1. Ele só é executado como parte do fluxo de resposta.
2. Esse é o único fluxo executado depois que o proxy entra no estado de erro.

Como ele é executado, independentemente de o proxy ter êxito ou falha, é possível colocar as políticas MessageLogging no PostClientFlow e garantir que elas sejam sempre executadas.

A imagem do Trace a seguir mostra uma política MessageLogging em execução como parte do PostClientFlow, após a execução de DefaultFailRule:

Neste exemplo, a política "Verificar chave de API" causou a falha devido a uma chave inválida.

Veja abaixo a definição de ProxyEndpoint que inclui o PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

O Edge registra mensagens como texto simples, e é possível configurar a geração de registros para incluir variáveis, como a data e a hora em que a solicitação ou a resposta foi recebida, a identidade do usuário na solicitação, o endereço IP de origem do qual a solicitação foi enviada e assim por diante. Mensagem de registros do Edge de forma assíncrona, o que significa que nenhuma latência que possa ser causada pelo bloqueio de chamadas é introduzida à sua API.

A política MessageLogging grava mensagens registradas na memória em um buffer. O registrador lê as mensagens do buffer e grava no destino que você configura. Cada destino tem seu próprio buffer.

Se a taxa de gravação no buffer aumentar além da taxa de leitura, o buffer será sobrecarregado e o registro falhará. Se isso acontecer, você verá uma mensagem contendo as seguintes informações no arquivo de registros:

Log message size exceeded. Increase the max message size setting

Se você encontrar esse problema no Edge for Private Cloud 4.15.07 e anterior, localize o message-logging.properties e usar esta solução:

Aumente a propriedade max.log.message.size.in.kb (valor padrão = 128 KB) no arquivo message-logging.properties.

No Edge para nuvem privada 4.16.01 e posterior, defina a propriedade conf/message-logging.properties+max. log.message.size.in.kb no arquivo /opt/apigee/customer/application/message-processor.properties e reinicie o processador de mensagens. Observe que essa propriedade é inicialmente comentada por padrão.

Observação: a mensagem de resposta variáveis no Edge não estão disponíveis no fluxo de erros. Essas variáveis também não estarão disponíveis no PostClientFlow se o fluxo anterior for o Fluxo de erros. Se você quiser registrar informações de resposta do PostClientFlow, use o objeto message. É possível usar esse objeto para conseguir cabeçalhos e outras informações da resposta, mesmo que não tenha ocorrido um erro. Consulte Variáveis de mensagem para ver mais informações e um exemplo.

Controlando mensagem de registro carimbo de data/hora no Edge para nuvem privada

Por padrão, o carimbo de data/hora em todas as mensagens de registro tem o seguinte formato:

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

Esse padrão do sistema pode ser substituído para destinos syslog usando o método DateFormat. O comportamento desse modelo está descrito nas documentação da classe SimpleDateFormat do Java. De acordo com essa definição, yyyy será substituído por um ano de quatro dígitos, MM será substituído por um número de mês de dois dígitos e assim por diante. O formato acima pode resultar em uma string neste formato:

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

É possível usar o método conf_system_apigee.syslogger.dateFormat no processador de mensagens de borda para controlar esse formato. Por exemplo, mudar a mensagem formatar para:

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

...substituindo os traços por barras e encurtando o ano para um ano com 2 dígitos, o carimbo de data/hora é registrado no formato:

22/09/28T22:38:11.721+0000

Para mudar o formato:

1. Abra o arquivo message-processor.properties em um editor. Se o arquivo não existir, crie-o:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Defina as propriedades como quiser:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Salve as alterações.
4. Verifique se o arquivo de propriedades é de propriedade da Apigee usuário:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicie o processador de mensagens de borda:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

Local do arquivo de registros no Edge para nuvem privada

Edge para nuvem privada 4.16.01 e posterior

Por padrão, os registros de mensagens da nuvem privada ficam localizados no seguinte diretório do Message Nós do processador:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

Você pode alterar o local padrão do registro modificando as propriedades no o arquivo message-logging.properties nos Processadores de mensagens:

• bin_setenv_data_dir: Define o caminho raiz para o armazenamento do arquivo de registros. Por exemplo, bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir: se Você define isso como um caminho relativo, como conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  Se você o definir como um caminho absoluto, como conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, mensagem registros serão armazenados em /opt/apigee/var/log/messages/messagelog/. Um caminho absoluto tem precedência sobre bin_setenv_data_dir.
  
  Você precisa referenciar a propriedade como conf/message-logging.properties+log.root.dir porque ele é comentado por padrão. Consulte Como configurar um token que está comentado no momento para saber mais.

Se você deseja armazenar arquivos de registro em uma estrutura de arquivos simples, para que todos os arquivos de registro sejam colocados mesmo diretório, defina conf/message-logging.properties+enable.flat.directory.structure como true no arquivo message-logging.properties. As mensagens são armazenadas no diretório especificado pelo as propriedades acima e os nomes dos arquivos assumem a forma de {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}:

Para definir essas propriedades:

1. Abra o arquivo message-processor.properties em um editor. Se o arquivo não existir, crie-o:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Defina as propriedades como quiser:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Salve as alterações.
4. Verifique se o arquivo de propriedades é de propriedade da Apigee usuário:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicie o componente Edge:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

Edge para nuvem privada 4.15.07 e anteriores

Por padrão, os registros de mensagens ficam no seguinte local da mensagem processadores:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Você pode alterar o local padrão do registro modificando as seguintes propriedades na message-logging.properties nos processadores de mensagens:

• data.dir: define a raiz caminho para o armazenamento do arquivo de registro. Por exemplo, data.dir=/opt/apigee4/var/log
• log.root.dir: se você configurar para um caminho relativo, como log.root.dir=custom/folder/, o caminho é anexado ao data.dir.

Por exemplo, a combinação das duas propriedades definiria o diretório de registro em /opt/apigee4/var/log/custom/folder/messagelog/ (observe que /messagelog foi adicionado automaticamente).

Se você definir esse caminho como um caminho absoluto, como log.root.dir=/opt/apigee4/var/log/messages, Os registros de mensagens serão armazenados em /opt/apigee4/var/log/messages/messagelog/. Um caminho absoluto na log.root.dir tem precedência sobre data.dir.

Se você deseja armazenar arquivos de registro em uma estrutura de arquivos simples, para que todos os arquivos de registro sejam colocados mesmo diretório, defina a propriedadeenable.flat.directory.structure como verdadeiro no arquivo message-logging.properties do Message Processadores. As mensagens são armazenadas no diretório especificado pelas propriedades acima, e o arquivo Os nomes têm o formato {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Valores padrão para variáveis no modelo de mensagens

É possível especificar valores padrão para cada variável no modelo de mensagem separadamente. Por exemplo, se a variável request.header.id não puder ser resolvida, seu valor será substituído pelo valor unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

É possível especificar um valor padrão comum para todas as variáveis não resolvidas. Para isso, defina o atributo defaultVariableValue no elemento Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Como configurar serviços de gerenciamento de registros de terceiros

A política MessageLogging permite enviar mensagens de syslog para serviços de gerenciamento de registros de terceiros, como Splunk, Sumo Logic e Loggly. Se você quiser enviar o syslog para um desses serviços, consulte a documentação desse serviço para configurar o host, a porta e o protocolo do serviço. Em seguida, defina o elemento Syslog nessa política adequadamente.

Consulte a seguinte documentação para configuração de gerenciamento de registros de terceiros:

• Splunk (selecione a versão do produto)
  Consulte também esta postagem da comunidade da Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • Veja também esta postagem da comunidade da Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html (em inglês)
  • Para ver um exemplo completo usando o Sumo Logic como o serviço de geração de registros, consulte a seguinte postagem da comunidade Apigee. A solução usa uma única política JavaScript para fazer solicitações HTTP POST para o coletor de origem HTTP do Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html (em inglês)
• Loggly
  Ao usar o Loggly, <FormatMessage>true</FormatMessage> é obrigatório na política como filho do elemento <Syslog>.
  Veja também esta postagem da comunidade da Apigee para mais informações sobre a geração de registros de mensagens no Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html (em inglês)

Referência de erros

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>

Variáveis de fluxo

As seguintes variáveis são preenchidas na falha da política.

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

Temas relacionados

• Variáveis expostas pelo Edge: referência de variáveis