Política MessageLogging

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que

A política MessageLogging permite registrar mensagens personalizadas no Cloud Logging ou syslog. É possível usar as informações nos registros para várias tarefas, como rastrear problemas no ambiente de execução da API.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Há duas maneiras de usar a política MessageLogging:

• O elemento <CloudLogging> registra mensagens no Cloud Logging. Para usar esse método, é necessário ativar as APIs Cloud Logging para o projeto do Google Cloud. Para mais informações sobre como ativar APIs para um projeto do Google Cloud, consulte Como ativar e desativar serviços.
• O elemento <Syslog> registra mensagens no syslog, um protocolo padrão para enviar mensagens de eventos ou de registros do sistema para um servidor específico. Para usar esse método, você precisa ter um servidor syslog disponível. Caso contrário, use serviços de gerenciamento de registros públicos, como Splunk, Sumo Logic e Loggly. Veja Como configurar serviços de gerenciamento de registros de terceiros.

Observação: não é possível usar o elemento <CloudLogging> e o <Syslog> na mesma política.

Elemento <MessageLogging>

Define uma política <MessageLogging>.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	TYPE
Elemento pai	n/a
Elementos filhos	<CloudLogging> <Syslog> <logLevel>

O elemento <MessageLogging> usa a seguinte sintaxe:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <MessageLogging>:

Nome do campo	Descrição do campo
CloudLogging	Configure as mensagens a serem registradas no Cloud Logging.
Syslog	Configure as mensagens a serem registradas no syslog.

Amostras

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
</MessageLogging>

Este exemplo ilustra o uso de modelos de mensagem. Como o elemento Message contém as variáveis de fluxo

{"{message.queryparam.key}": "{message.queryparam.value}"}

quando alguém chama o proxy com os valores message.queryparam.key = "fruit" e message.queryparam.value = "apple", a entrada de registro resultante será {"fruit": "apple"}.

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>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Neste exemplo, suponha que você precise registrar informações sobre cada mensagem de solicitação recebida pela API pelos apps para o consumidor. O valor 3f509b58 representa um valor de chave específico para o serviço Loggly. Se você tiver uma conta do Loggly, 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. O formato dos carimbos de data/hora será semelhante a 230704-13:42:17.376, de acordo com o formato especificado no elemento DateFormat.

Observação: os elementos Host e Port não podem se referir a variáveis. Eles precisam conter valores estáticos.

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

Referência a elementos filhos

As seções a seguir descrevem os elementos filhos de <MessageLogging>.

<CloudLogging>

Use o elemento <CloudLogging> para registrar mensagens no Cloud Logging.

Observação: para usar <CloudLogging>, você precisa ativar as APIs Cloud Logging no projeto do Google Cloud. Para ativar APIs em um projeto do Google Cloud, consulte Como ativar e desativar serviços. O elemento <CloudLogging> da política MessageLogging está disponível na Apigee e Apigee híbrido versões v1.7.0 e posteriores.

Nome do campo	Obrigatório?	Descrição
LogName	Sim	Nome do registro. O nome do tópico precisa estar no formato projects/{PROJECT_ID}/logs/{LOG_ID}. É possível usar variáveis no lugar de {PROJECT_ID} e {LOG_ID}.
Message	Sim	A mensagem a ser registrada. A mensagem tem um atributo contentType, que tem um valor text/plain ou application/json para mensagens de texto e JSON, respectivamente. 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 um message. para registrar as informações das respostas nas situações de erro e de sucesso. Consulte também as Observações sobre o uso. Observação: o elemento <Message> é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem,
Label	Não	Rótulo a ser anexado à mensagem de registro, se houver. Eles estarão na forma de um par de chave-valor, como o seguinte: <Label> <Key>key1</Key> <Value>value1</Value> </Label>
ResourceType	Não (o padrão é global)	Representa o recurso monitorado que está gerando os registros.

Autenticação para o Cloud Logging

Para usar o elemento <CloudLogging>, é necessário implantar seu proxy de API para usar a autenticação do Google. A Apigee usará as credenciais correspondentes à identidade da conta de serviço especificada nas solicitações de saída para o Cloud Logging. Para detalhes, consulte Como usar a autenticação do Google. A conta de serviço anexada ao seu proxy de API no momento da implantação precisa ter um papel com a permissão logging.logEntries.create. Para mais informações sobre os papéis de gerenciamento de identidade e acesso (IAM) de <CloudLogging>, consulte o Guia de controle de acesso.

<Syslog>

Use o elemento <Syslog> para configurar as mensagens que serão registradas em syslog. Quando você usa o <Syslog>, um proxy de API encaminha mensagens de registro da Apigee para um servidor syslog remoto. Para usar esse método, você precisa ter um servidor syslog disponível. Se você não fizer isso, estarão disponíveis os serviços de gerenciamento de registros públicos, como Splunk, Sumo Logic e Loggly. Consulte Como configurar serviços de gerenciamento de registros de terceiros.

Nome do campo	Obrigatório?	Descrição do campo
Message	Sim	A mensagem a ser registrada. A mensagem tem um atributo contentType, que tem um valor text/plain ou application/json para mensagens de texto e JSON, respectivamente. Ver as amostras. Observação: o elemento <Message>> é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem, Observação: Variáveis de resposta não estarão disponíveis no PostClientFlow após um fluxo de erros. Use message para registrar as informações das respostas nas situações de erro e de sucesso. Consulte também as Observações sobre o uso.
Host	Não	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	Não	Porta onde o syslog está sendo executado. Se você não incluir esse elemento, o padrão será 514.
Protocol	Não	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	Não, mas o <FormatMessage>true</FormatMessage> é necessário para uso com o Loggly.	true ou false (padrão). 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 - - - 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 - - - " Se definida como falsa (padrão), a mensagem não será anexada com os caracteres fixos. Observação: se você definir <FormatMessage>false</FormatMessage>, a mensagem de registro ainda incluirá a pontuação de prioridade e a data. Para formatar a mensagem de registro para incluir apenas o corpo da mensagem, defina <PayloadOnly>true</PayloadOnly>. Consulte PayloadOnly.
PayloadOnly	Não	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. Observação: a configuração <PayloadOnly>true</PayloadOnly> substitui a configuração de FormatMessage.
DateFormat	Não	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 está descrito na documentação da classe SimpleDateFormat do Java. De acordo com essa definição, yyyy na string de formato será substituída 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.
SSLInfo	Não	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>

Os valores válidos para o elemento <logLevel> são: INFO (padrão), ALERT, WARN, 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.

Observações sobre o uso:

Ao anexar uma política MessageLogging a um fluxo de proxy de API, considere colocá-la na resposta ProxyEndpoint, localizada 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.

Observação: é importante observar que a variável do fluxo de resposta não fica disponível no PostClientFlow depois que o processamento entra no estado de erro. Em vez disso, é possível usar a variável message para definir valores na política MessageLogging no PostClientFlow, garantindo que eles sejam definidos, independentemente de o estado de erro ser ou não o contexto anterior. Para mais informações e exemplos, consulte a Referência de variáveis de fluxo.

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

A Apigee 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.

A mensagem de registros da Apigee é assíncrona: a resposta é retornada enquanto os registros ainda estão sendo gravados. Como resultado, nenhuma latência é introduzida na API ao bloquear frases de destaque. Pode haver ocasiões em que um registro não é gravado sem um erro ser retornado, mas esses eventos são raros.

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.

Observação: as chamadas de proxy são bem-sucedidas quando há falha na geração de registros

Como o registro de mensagens é gravado pela primeira vez no buffer, o proxy da API continuará com êxito mesmo se o registro de mensagens falhar (por exemplo, se houver uma falha de conexão com o destino).

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, será possível encontrar uma das seguintes mensagens no arquivo de registro:

• Utilizando <CloudLoggingg>:

  steps.messagelogging.TooManyPendingLoggingRequest

• Utilizando <Syslog>:

  Log message size exceeded. Increase the max message size setting

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

Observação: as variáveis de mensagem de resposta na Apigee 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 as informações de resposta do PostClientFlow, use 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 a Referência de variáveis de fluxo para ver mais informações e um exemplo.

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>

Observação: o valor da variável padrão não pode conter espaços.

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 (seleciona a versão do produto, link em inglês)
  Consulte também esta postagem na comunidade da Apigee: Registrar mensagens no Splunk (em inglês)
• Sumo Logic
  • Veja também esta postagem na comunidade da Apigee: Como configurar a geração de registros com o Sumo Logic (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: Registrar no Sumo Logic usando JavaScript e HTTP (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 na comunidade da Apigee para conferir mais informações sobre o registro de mensagens no Loggly: Registrar mensagens no Loggly (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 Apigee 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.

Fault code	HTTP status	Cause
steps.messagelogging.StepDefinitionExecutionFailed	500	See fault string.
steps.messagelogging.InvalidGoogleCloudLogName	500	This error is thrown when the LogName does not evaluate to the valid format of projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage	500	This error is thrown when the contentType attributes value has been chosen as application/json but the actual message value is not a valid JSON string,
steps.messagelogging.TooManyPendingLoggingRequest	500	This error is thrown when there are more than 2500 pending requests that are yet to be written to Cloud Logging. The 2500 limit is for each Apigee runtime pod. For example, if the traffic is distributed over two instances of Apigee runtime pods, the effective limit is 5000 requests.

-

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
InvalidProtocol	The deployment of the MessageLogging policy can fail with this error if the protocol specified within the <Protocol> element is not valid. The valid protocols are TCP and UDP. For sending syslog messages over TLS/SSL, only TCP is supported.
InvalidPort	The deployment of the MessageLogging policy can fail with this error if the port number is not specified within the <Port> element or if it is not valid. The port number must be an integer greater than zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Note: Proxy calls succeed when logging fails

There's a difference between policy errors and message logging errors. The flow variables here are populated only when the policy itself fails, not when message logging fails. Because message logging is first written to buffer, the API proxy will continue successful execution even if message logging ultimately fails (for example, if there's a connection failure to the external syslog provider). Be sure to check your logs on a regular basis to make sure logging is happening as expected.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	messagelogging.ML-LogMessages.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Observação: as chamadas de proxy são bem-sucedidas quando há falha na geração de registros

Há uma diferença entre erros de política e erros de registro de mensagens. As variáveis de fluxo aqui são preenchidas apenas quando a própria política falha, não quando a geração de registros de mensagens falha. Como o registro de mensagens é gravado pela primeira vez no buffer, o proxy da API continuará com êxito mesmo se o registro de mensagens falhar (por exemplo, se houver uma falha de conexão com o provedor syslog externo). Verifique seus registros regularmente para garantir que a geração de registros esteja acontecendo como esperado.

---

Temas relacionados

• Variáveis expostas pela Apigee: Referência de variáveis de fluxo