Política MessageLogging

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

Confira a documentação da Apigee Edge.

O quê?

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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa 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.
steps.messagelogging.InvalidGoogleCloudLogName	500	Esse erro é gerado quando o LogName não é avaliado para o formato válido de projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage	500	Esse erro é gerado quando o valor dos atributos contentType é selecionado como application/json, mas o valor da mensagem real não é uma string JSON válida.
steps.messagelogging.TooManyPendingLoggingRequest	500	Esse erro é gerado quando há mais de 2.500 solicitações pendentes que ainda não foram gravadas no Cloud Logging. O limite de 2.500 é para cada pod de ambiente de execução da Apigee. Por exemplo, se o tráfego for distribuído em duas instâncias de pods do ambiente de execução da Apigee, o limite efetivo será de 5.000 solicitações.

-

Erros na implantação

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

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Corrigir" para informações detalhadas sobre a solução de problemas.

Erro de nome	Causa	Correção
InvalidProtocol	A implantação da política MessageLogging poderá falhar com este 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 este erro se o número de porta não for especificado no elemento <Port> ou se ele 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.

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.

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

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

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