Política de Registo de Mensagens

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone de política

O quê

A política MessageLogging permite-lhe registar mensagens personalizadas no Cloud Logging ou no syslog. Pode usar as informações nos registos para várias tarefas, como localizar problemas no ambiente de tempo de execução da API.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Existem duas formas de usar a política MessageLogging:

  • O elemento <CloudLogging> regista mensagens no Cloud Logging. Para usar este método, tem de ativar as APIs Cloud Logging para o seu projeto do Google Cloud. Para mais informações sobre a ativação de APIs para um projeto do Google Cloud, consulte Ativar e desativar serviços.
  • O elemento <Syslog> regista mensagens no syslog, um protocolo padrão para o envio de mensagens de registo do sistema ou de eventos para um servidor específico. Para usar este método, tem de ter um servidor syslog disponível. Se não o fizer, pode usar serviços públicos de gestão de registos, como o Splunk, o Sumo Logic e o Loggly. Consulte o artigo Configurar serviços de gestão de registos de terceiros.

Nota: não pode usar o elemento <CloudLogging> e o elemento <Syslog> na mesma política.

<MessageLogging> elemento

Define uma política de <MessageLogging>.

Valor predefinido Consulte o separador Política predefinida abaixo
Obrigatório? Obrigatória
Tipo TIPO
Elemento principal N/A
Elementos secundários <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>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

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

Atributo Predefinição Obrigatório? Descrição
name N/A Obrigatório

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

continueOnError falso Opcional Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
enabled verdadeiro Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async   falso Descontinuado Este atributo foi descontinuado.

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <MessageLogging>:

Nome do campo Descrição do campo
CloudLogging

Configure as mensagens para serem registadas no Cloud Logging.

Syslog

Configure as mensagens para serem registadas em 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>api</ResourceType>
    </CloudLogging>
</MessageLogging>

Este exemplo ilustra a utilização de modelos de mensagens. Uma vez que 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 registo resultante seria {"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 precisa de registar informações sobre cada mensagem de pedido que a sua API recebe de apps de consumidor. O valor 3f509b58 representa um valor-chave específico do serviço Loggly. Se tiver uma conta do Loggly, substitua a chave do Loggly. A mensagem de registo gerada é preenchida com quatro valores: a organização, o proxy da API e o nome do ambiente associados à transação, juntamente com o valor de um parâmetro de consulta na mensagem de pedido. O formato das indicações de tempo é semelhante a 230704-13:42:17.376, de acordo com o formato especificado no elemento DateFormat.

Syslog através de 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>

Pode enviar mensagens a fornecedores de registo de mensagens de terceiros através de TLS/SSL adicionando o bloco <SSLInfo>.

Referência de elemento secundário

As secções seguintes descrevem os elementos secundários de <MessageLogging>.

<CloudLogging>

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

Nome do campo Obrigatório? Descrição
LogName Sim Nome do registo. O nome do registo deve estar no formato projects/{PROJECT_ID}/logs/{LOG_ID}. Pode usar variáveis em vez de {PROJECT_ID} e {LOG_ID}.
Message Sim

A mensagem a ser registada. A mensagem tem um atributo contentType, cujo valor pode ser text/plain ou application/json para mensagens de texto e JSON, respetivamente. Veja os exemplos.

Label Não Etiqueta a anexar à mensagem de registo, se existir. Estes vão estar no formato de um par de chave-valor, como o seguinte:
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType Não (predefinição global) Representa o recurso monitorizado que está a gerar os registos.

Autenticação para o Cloud Logging

Para usar o elemento <CloudLogging>, tem de implementar o proxy de API para usar a autenticação Google. O Apigee usa credenciais correspondentes à identidade da conta de serviço que especificar nos pedidos de saída para o Cloud Logging. Para mais detalhes, consulte o artigo Usar a autenticação Google.

A conta de serviço que associa ao proxy de API no momento da implementação tem de ter uma função com a autorização logging.logEntries.create. A menos que precise de um controlo mais detalhado, recomendamos que use a função predefinida mais inclusiva roles/logging.logWriter para a conta de serviço. Para mais informações acerca das funções de gestão de identidade e de acesso (IAM) para <CloudLogging>, consulte o guia de controlo de acesso.

Implementação de proxy no Apigee Hybrid

Se estiver a usar o Apigee hybrid, a conta de serviço de tempo de execução que criar para o Apigee hybrid tem de se fazer passar pela conta de serviço do proxy para fazer chamadas autenticadas em seu nome. Como resultado, a conta de serviço do tempo de execução híbrido do Apigee tem de ter a função iam.serviceAccountTokenCreator para a conta de serviço do proxy.

<Syslog>

Use o elemento <Syslog> para configurar as mensagens a registar em syslog. Quando usa o <Syslog>, um proxy de API encaminha mensagens de registo do Apigee para um servidor syslog remoto. Para usar este método, tem de ter um servidor syslog disponível. Se não o fizer, estão disponíveis serviços de gestão de registos públicos, como o Splunk, o Sumo Logic e o Loggly. Consulte o artigo Configurar serviços de gestão de registos de terceiros.

Nome do campo Obrigatório? Descrição do campo
Message Sim

A mensagem a ser registada. A mensagem tem um atributo contentType, cujo valor pode ser text/plain ou application/json para mensagens de texto e JSON, respetivamente. Veja os exemplos.

Host Não O nome de anfitrião ou o endereço IP do servidor para onde o syslog deve ser enviado. Se não incluir este elemento, a predefinição é localhost.
Port Não Porto onde o syslog está em execução. Se não incluir este elemento, a predefinição é 514.
Protocol Não TCP ou UDP (predefinição). Embora o UDP tenha um melhor desempenho, o protocolo TCP garante a entrega do registo de mensagens ao servidor syslog. Para enviar mensagens syslog através de TLS/SSL, apenas o TCP é suportado.
FormatMessage Não, mas o <FormatMessage>true</FormatMessage> é necessário para utilização com o Loggly.

true ou false (predefinição)

Este elemento permite-lhe controlar o formato do conteúdo gerado pelo Apigee anteposto à mensagem. Se estiver definida como verdadeira, a mensagem syslog é precedida por um número fixo de carateres, o que lhe permite filtrar essas informações das mensagens. Segue-se um exemplo para o formato fixo:

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

As informações geradas pelo Apigee incluem:

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

Se for definida como falsa (predefinição), a mensagem não é precedida desses carateres fixos.

PayloadOnly Não

true ou false (predefinição)

Este elemento define o formato das mensagens geradas pelo Apigee para conter apenas o corpo da mensagem syslog, sem os carateres antepostos especificados por FormatMessage.

Se não incluir este elemento ou o deixar vazio, o valor predefinido é false.

Consulte FormatMessage.

DateFormat Não

Uma string de modelo de formatação a usar para formatar a data/hora de cada mensagem de registo. Por predefinição, o Apigee usa yyyy-MM-dd'T'HH:mm:ss.SSSZ. O comportamento deste modelo é descrito na documentação da classe SimpleDateFormat do Java. De acordo com essa definição, yyyy na string de formato é substituído por um ano de 4 dígitos, MM é substituído por um número de mês de 2 dígitos e assim sucessivamente.

SSLInfo Não

Permite-lhe registar mensagens através de SSL/TLS. Use com o subelemento <Enabled>true</Enabled>.

Se não incluir este elemento ou o deixar vazio, o valor predefinido é falso (sem TLS/SSL).

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

Pode configurar a etiqueta <SSLInfo> da mesma forma que num TargetEndpoint, incluindo a ativação do TLS/SSL bidirecional, conforme descrito na referência de configuração do proxy de API. Apenas o protocolo TCP é suportado.


<logLevel>

Os valores válidos para o elemento <logLevel> são: INFO (predefinição), ALERT, WARN, ERROR.

Define um nível específico de informações a incluir no registo de mensagens.

Se estiver a usar o elemento FormatMessage (definindo-o como verdadeiro), a definição de <logLevel> afeta a pontuação de prioridade calculada (o número entre parênteses angulares) nas informações geradas pelo Apigee antepostas à mensagem.

Notas de utilização

Quando anexar uma política MessageLogging a um fluxo de proxy de API, pondere colocá-la na resposta ProxyEndpoint, num fluxo especial denominado PostClientFlow. O PostClientFlow é executado depois de a resposta ser enviada para o cliente que fez o pedido, o que garante que todas as métricas estão disponíveis para registo. Para ver detalhes sobre a utilização do PostClientFlow, consulte a referência de configuração do proxy de API.

O PostClientFlow é especial de duas formas:

  1. Só foi executado como parte do fluxo de respostas.
  2. É o único fluxo executado depois de o proxy entrar no estado de erro.

Uma vez que é executada independentemente de o proxy ter sido bem-sucedido ou não, pode colocar políticas de MessageLogging no PostClientFlow e ter a garantia de que são sempre executadas.

A imagem de depuração seguinte mostra uma política MessageLogging a ser executada como parte do PostClientFlow, após a execução da DefaultFaultRule:

Neste exemplo, a política Verify API Key causou a falha devido a uma chave inválida.

Abaixo, é apresentada 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 Apigee regista mensagens como texto simples e pode configurar o registo para incluir variáveis, como: a data e a hora em que o pedido ou a resposta foi recebido, a identidade do utilizador no pedido, o endereço IP de origem a partir do qual o pedido foi enviado, entre outros.

O Apigee regista a mensagem de forma assíncrona: a resposta é devolvida enquanto os registos ainda estão a ser escritos. Como resultado, não é introduzida latência na sua API ao bloquear pedidos de lances. Pode haver ocasiões em que não é escrito um registo sem ser devolvido um erro, mas estes eventos são raros.

A política MessageLogging escreve mensagens registadas na memória para um buffer. O registador de mensagens lê mensagens do buffer e, em seguida, escreve no destino que configurar. Cada destino tem o seu próprio buffer.

Se a taxa de gravação no buffer aumentar além da taxa de leitura, o buffer transborda e o registo falha. Se isto acontecer, pode encontrar uma das seguintes mensagens no ficheiro de registo:

  • Usar o <CloudLogging>:
    steps.messagelogging.TooManyPendingLoggingRequest
  • Usar o <Syslog>:
    Log message size exceeded. Increase the max message size setting

Aumente a propriedade max.log.message.size.in.kb (valor predefinido = 128 KB) no ficheiro message-logging.properties.

Valores predefinidos para variáveis no modelo de mensagem

Os valores predefinidos podem ser especificados para cada variável no modelo de mensagem separadamente. Por exemplo, se não for possível resolver a variável request.header.id, o respetivo valor é substituído pelo valor unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Pode especificar um valor predefinido comum para todas as variáveis não resolvidas definindo o atributo defaultVariableValue no elemento Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

Configurar serviços de gestão de registos de terceiros

A política MessageLogging permite-lhe enviar mensagens syslog para serviços de gestão de registos de terceiros, como Splunk, Sumo Logic e Loggly. Se quiser enviar o syslog para um desses serviços, consulte a documentação do serviço para configurar o anfitrião, a porta e o protocolo do serviço e, em seguida, defina o elemento Syslog nesta política em conformidade.

Consulte a seguinte documentação para a configuração da gestão de registos de terceiros:

  • Splunk (selecione a versão do produto)
    Consulte também esta publicação da comunidade do Apigee: Registe mensagens no Splunk
  • Sumo Logic
  • Loggly
    Quando usar o Loggly, <FormatMessage>true</FormatMessage> é obrigatório na política como um elemento secundário do elemento <Syslog>.
    Consulte também esta publicação da comunidade Apigee para mais informações acerca do registo de mensagens no Loggly: Registe mensagens no Loggly

Referência de erro

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 em caso de falha da política.

  • messagelogging.failed
  • messagelogging.{stepdefinition-name}.failed

Tópicos relacionados