Política MessageLogging

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

O quê?

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

Exemplos

<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 de onde a solicitação foi enviada e assim por diante. A mensagem registra a mensagem de maneira assíncrona, o que significa que nenhuma latência que possa ser causada pelo bloqueio de chamadas de chamada é introduzida na 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 arquivo message-logging.properties e use 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:as variáveis da mensagem de resposta 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.

Como controlar o carimbo de data/hora da mensagem de registro 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 por destinos syslog usando o elemento DateFormat. O comportamento desse modelo é descrito na 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 a propriedade conf_system_apigee.syslogger.dateFormat no processador de mensagens do Edge para controlar esse formato. Por exemplo, mudar o formato das mensagens 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 conforme desejado:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Salve as mudanças.
4. Verifique se o arquivo de propriedades pertence ao usuário "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Reinicie o Edge Message Processor:
   > /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 estão localizados no seguinte diretório nos nós do processador de mensagens:

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

É possível alterar o local de registro padrão modificando as propriedades no 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ê definir 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 definir como um caminho absoluto, como conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, os registros de mensagens serão armazenados em /opt/apigee/var/log/messages/messagelog/. Um caminho absoluto tem precedência sobre bin_setenv_data_dir.
  
  Você precisa fazer referência à propriedade como conf/message-logging.properties+log.root.dir, porque ela recebe comentários por padrão. Para mais informações, consulte Como configurar um token que está comentado no momento.

Se você quiser armazenar arquivos de registro em uma estrutura simples para que todos os arquivos de registro sejam colocados no 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 pelas propriedades acima, e os nomes dos arquivos assumem o formato 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 conforme desejado:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Salve as mudanças.
4. Verifique se o arquivo de propriedades pertence ao usuário "apigee":
   > 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 localizados no seguinte local nos processadores de mensagens:

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

É possível alterar o local de registro padrão modificando as seguintes propriedades no arquivo message-logging.properties nos processadores de mensagens:

• data.dir: define o caminho raiz para o armazenamento do arquivo de registros. Por exemplo, data.dir=/opt/apigee4/var/log
• log.root.dir: se você definir um caminho relativo, como log.root.dir=custom/folder/, ele será anexado ao local data.dir.

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

Se você definir esse caminho como 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 em log.root.dir tem precedência sobre data.dir.

Se você quiser armazenar arquivos de registro em uma estrutura de arquivos simples para que todos os arquivos de registro sejam colocados no mesmo diretório, defina a enable.flat.directory.structure como verdadeira no arquivo message-logging.properties nos processadores de mensagens. As mensagens são armazenadas no diretório especificado pelas propriedades acima e os nomes dos arquivos assumem o formato de {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

Nesta seção, descrevemos os códigos e as mensagens de erro retornados, além das variáveis de falha definidas pelo Edge quando esta política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém essa política.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Exemplo de resposta de erro

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Exemplo de regra de falha

<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