Política MessageLogging

Você está vendo a documentação do Apigee Edge.
Acesse a 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. É possível anexar e configurar uma política MessageLogging na API para registrar mensagens personalizadas em um disco local (somente no Edge para nuvem privada) ou no syslog.

Exemplos

Syslog

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

Um uso comum do tipo de política MessageLogging é registrar em uma conta syslog. Quando configurado para syslog, um proxy de API vai encaminhar mensagens de registro do Apigee Edge para um servidor syslog remoto. É preciso que o servidor syslog esteja disponível. Caso contrário, os serviços de gerenciamento de registros públicos, como Splunk, Sumo Logic e Loggly, estão disponíveis. consulte Como configurar serviços de gerenciamento de registros de terceiros.

Por exemplo, imagine que você precisa registrar informações sobre cada mensagem de solicitação que sua API recebe dos apps do consumidor. O valor 3f509b58 representa um valor de chave específico para o serviço logolog. Se você tiver uma conta do Logly, substitua a chave. A mensagem de registro gerada será preenchida com quatro valores: a organização, o proxy de API e o nome do ambiente associado à transação, além do valor de um parâmetro de consulta na mensagem de solicitação.

Se você tiver um Edge para implantação de nuvem privada, também poderá gravar mensagens de registro em um arquivo.

Syslog por TLS/SSL

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

É possível enviar mensagens para provedores de registro de mensagens de terceiros por TLS/SSL. Para isso, adicione o bloco <SSLInfo>.

Rotação de arquivos: tamanho

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

Rotação de arquivos com base no tamanho do arquivo.

Rotação de arquivos: tempo

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

Rotação de arquivos com base no horário.

Rotação de arquivos: horário e tamanho

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

Rotação de arquivos com base em tempo e tamanho.

Habilitado para streaming

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

Geração de registros de mensagens compatíveis com streaming


Referência de elemento

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

Nome do campo Descrição do campo

File

Destino do arquivo local. A geração de registros de arquivos só é compatível com o Edge para implantações de nuvem privada. Para informações sobre onde os arquivos são armazenados, consulte Local do arquivo de registros no Edge para nuvem privada.

Message Crie a mensagem a ser enviada ao arquivo de registros, combinando texto com variáveis para capturar as informações desejadas. Ver as amostras
FileName Nome do arquivo de registro em que a mensagem é registrada.
FileRotationOptions
rotateFileOnStartup

Atributo. Valores válidos: true/false

Se definido como verdadeiro, o arquivo de registro será girado sempre que o mecanismo de mensagens for reiniciado.

FileRotationType Especifica a política de rotação (size ou time) de um arquivo de registros.
MaxFileSizeInMB (Ao selecionar size como tipo de rotação) Especifica o tamanho de um arquivo de registro que aciona o servidor para mover mensagens de registro para um arquivo separado. Depois que o arquivo de registros atinge o tamanho especificado, o servidor renomeia o arquivo de registro atual.
RotationFrequency Ao selecionar time como tipo de rotação, especifica o tempo em minutos que aciona o servidor para mover as mensagens de registro para um arquivo separado. Após o intervalo especificado, o arquivo de registro atual é renomeado.
MaxFilesToRetain

Especifica o número máximo de arquivos a serem retidos no contexto das configurações de rotação. O valor padrão é 8.

Se você especificar zero (0), os arquivos de registros serão retidos por tempo indefinido, mas sujeitos às configurações de rotação de arquivos, embora nenhum dos arquivos seja excluído ou renomeado. Portanto, para evitar futuros erros de disco cheio, defina um valor maior que zero ou implemente um sistema automatizado regular de limpeza ou arquivamento de arquivos de registros retidos mais antigos.

BufferMessage

Se o streaming HTTP estiver ativado para o proxy, as mensagens de solicitação/resposta não serão armazenadas em buffer. Se você quiser registrar um conteúdo que exija que a mensagem de fluxo seja analisada, defina BufferMessage como verdadeiro. Consulte a guia de exemplo "Ativado para streaming" para ter um exemplo. Padrão: false

Syslog

Um destino syslog. Para enviar o syslog para o Splunk, Sumo Logic ou Loggly, consulte Como configurar serviços de gerenciamento de registros de terceiros.

Message

Crie a mensagem a ser enviada ao syslog, combinando texto com variáveis para capturar as informações que você quer. Ver as amostras

Observação: as variáveis de resposta não estarão disponíveis no PostClientFlow após um fluxo de erro. Use as variáveis de mensagem para registrar informações de resposta para situações de erro e sucessos. Consulte também as observações sobre o uso.

Host O nome do host ou endereço IP do servidor para onde o syslog precisa ser enviado. Se você não incluir esse elemento, o padrão será localhost.
Port Porta onde o syslog está sendo executado. Se você não incluir esse elemento, o padrão será 514.
Protocol TCP ou UDP (padrão). Enquanto o UDP tem melhor desempenho, o protocolo TCP garante o envio de registros de mensagens ao servidor syslog. Para enviar mensagens syslog por TLS/SSL, apenas TCP é aceito.
FormatMessage

true ou false (padrão).

Opcional, mas <FormatMessage>true</FormatMessage> é obrigatório para uso com o Loggly.

Esse elemento permite controlar o formato do conteúdo gerado pela Apigee precedendo a mensagem. Se for definida como verdadeira, a mensagem syslog será anexada com um número fixo de caracteres, o que permite filtrar essa informação das mensagens. Veja um exemplo do formato fixo:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee-Edge - - - Message starts here

As informações geradas pela Apigee incluem:

  • <14>: uma pontuação de prioridade (consulte o protocolo Syslog) com base no nível de registro e no nível da instalação da mensagem.
  • 1: a versão atual do syslog.
  • Data com uma compensação de UTC (UTC = +0000).
  • UUID do processador de mensagens.
  • "Apigee-Edge - - - "

Se definida como falsa (padrão), a mensagem não será anexada com os caracteres fixos.

PayloadOnly

true ou false (padrão).

Esse elemento define o formato das mensagens geradas pela Apigee para conter apenas o corpo da mensagem do syslog, sem os caracteres prefixados especificados por FormatMessage.

Se você não incluir esse elemento ou deixá-lo vazio, o valor padrão será false.

Consulte FormatMessage.

DateFormat

Opcional.

Uma string de modelo de formatação para formatar o carimbo de data/hora de cada mensagem de registro. Por padrão, a Apigee usa yyyy-MM-dd'T'HH:mm:ss.SSSZ. O comportamento desse modelo é descrito na documentação da classe SimpleDateFormat do Java.

SSLInfo

Permite que você registre mensagens por SSL/TLS. Use com o subelemento <Enabled>true</Enabled>.

Se você não incluir esse elemento ou deixá-lo vazio, o valor padrão será "false" (sem TLS/SSL).

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

É possível configurar o<SSLInfo> marcar da mesma forma que você faz em um TargetEndpoint, incluindo a ativação do TLS/SSL bidirecional, conforme descrito em Referência de configuração de proxy da API. Apenas o protocolo TCP é compatível.

logLevel

Opcional.

Valores válidos: INFO (padrão), ALERT, WARN e ERROR

Defina um nível específico de informações a serem incluídas no registro da mensagem.

Se você estiver usando o elemento FormatMessage (definindo-o como "true"), sua configuração de logLevel afetará a pontuação de prioridade calculada (o número dentro dos colchetes angulares) nas informações geradas pela Apigee à mensagem.

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. O Edge registra a mensagem de maneira assíncrona, o que significa que nenhuma latência causada pelo bloqueio de chamadas é 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 para a nuvem privada 4.15.07 e anteriores, 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 a nuvem privada 4.16.01 e mais recentes, defina a propriedade conf_message-logging_max.log.message.size.in.kb no arquivo /opt/apigee/customer/application/message-processor.properties e reinicie o processador de mensagens.

Observação:as variáveis de mensagens 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 das mensagens de registro no Edge para a nuvem privada

Por padrão, o carimbo de data/hora em todas as mensagens de registro tem o 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 4 dígitos, MM será substituído por um número de mês com 2 dígitos e assim por diante. O formato acima pode resultar em uma string desta forma:

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

É possível usar a propriedade conf_system_apigee.syslogger.dateFormat no processador de mensagens de borda para controlar esse formato. Por exemplo, alterando o formato da mensagem para:

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

..substituir os traços por barras e reduzir para um ano de 2 dígitos registra um carimbo de data/hora no formato:

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

Para alterar 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 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 processador de mensagens do Edge:
    > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Localização do arquivo de registros no Edge para a nuvem privada

Edge para nuvem privada 4.16.01 e mais recentes

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/

Você pode 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 de arquivos 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 você definir 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.

    É preciso referenciar a propriedade como conf/message-logging.properties+log.root.dir porque ela é comentada por padrão. Para saber mais, consulte Como configurar um token que está sendo comentado no momento.

Se você quiser armazenar arquivos de registro em uma estrutura simples para que todos os arquivos sejam colocados no mesmo diretório, defina conf/message-logging.properties+enable.flat.directory.structure como verdadeiro no arquivo message-logging.properties. As mensagens são armazenadas no diretório especificado pelas propriedades acima, e os nomes dos arquivos têm 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 como quiser:
    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 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 de arquivos de registros. Por exemplo, data.dir=/opt/apigee4/var/log.
  • log.root.dir - se você definir como um caminho relativo, como log.root.dir=custom/folder/, o caminho 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 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 no log.root.dir tem precedência sobre data.dir.

Se você quiser armazenar arquivos de registro em uma estrutura simples para que todos os arquivos sejam colocados no mesmo diretório, defina a propriedade enable.flat.directory.structure como verdadeiro 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 a forma 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:

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.

Código de falha Status HTTP Causa
steps.messagelogging.StepDefinitionExecutionFailed 500 Consulte string de falha.

Erros de implantação

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

Erro de nome Causa Corrigir
InvalidProtocol A implantação da política MessageLogging poderá falhar com esse erro se o protocolo especificado no elemento <Protocol> não for válido. Os protocolos válidos são TCP e UDP. Para enviar mensagens syslog por TLS/SSL, apenas TCP é aceito.
InvalidPort A implantação da política MessageLogging poderá falhar com esse erro se o número da porta não for especificado no elemento <Port> ou se não for válido. O número da porta precisa ser um número inteiro maior que zero.

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.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name é o nome especificado pelo usuário da política que causou a falha. messagelogging.ML-LogMessages.failed = true

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