Política MessageLogging

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

Confira a documentação da Apigee Edge.

Ícone da política

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

Nome do erro 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.

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