Política de Registo de Mensagens

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

Veja a documentação do Apigee Edge.

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> registra 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: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
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.

Nota: os elementos Host e Port não podem fazer referência a variáveis. Têm de conter valores estáticos.

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.

Nota: para usar <CloudLogging> tem de ativar as APIs Cloud Logging para o seu projeto do Google Cloud. Para ativar APIs para um projeto do Google Cloud, consulte Ativar e desativar serviços. O elemento <CloudLogging> da política MessageLogging está disponível no Apigee e nas versões híbridas do Apigee v1.7.0 e posteriores.

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}. Nota: LogName especifica o nome do recurso de um registo do Cloud Logging para o qual enviar a entrada do registo. Através da utilização de variáveis, a política MessageLogging permite-lhe inserir dinamicamente um valor de nome diferente e exclusivo para cada entrada LogName . No entanto, recomendamos que não siga esta prática e que não crie dinamicamente nomes de registos exclusivos com valores que possam mudar de pedido para pedido, uma vez que pode causar problemas de cardinalidade elevada. Em alternativa, recomendamos que use um nome fixo e significativo de um conjunto fixo de nomes para o LogName.
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. Nota: as variáveis de resposta não vão estar disponíveis no PostClientFlow após um fluxo de erros. Use um message. Para registar informações de resposta para situações de erro e de sucesso. Consulte também as Notas de utilização. Nota: o elemento <Message> suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens
Label	Não	Etiqueta a anexar à mensagem de registo, se existir. Estes vão estar sob a forma 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 tiver, estão disponíveis serviços de gestão de registos públicos, como Splunk, Sumo Logic e 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. Nota: o elemento <Message>> suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens. Nota: as variáveis de resposta não vão estar disponíveis no PostClientFlow após um fluxo de erros. Use um message. Para registar informações de resposta para situações de erro e de sucesso. Consulte também as Notas de utilização.
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. Nota: se definir <FormatMessage>false</FormatMessage>, a mensagem de registo continua a incluir a classificação de prioridade e a data. Para formatar a mensagem de registo de forma a incluir apenas o corpo da mensagem, defina <PayloadOnly>true</PayloadOnly>. Consulte PayloadOnly.
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. Nota: a definição de <PayloadOnly>true</PayloadOnly> substitui a definição de 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 após o envio da resposta ao 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 da API.

Nota: é importante ter em atenção que a variável de fluxo de resposta não está disponível no PostClientFlow assim que o processamento entra no estado de erro. Em alternativa, pode usar a variável message para definir valores na política MessageLogging no PostClientFlow, garantindo que são definidos independentemente de o estado de erro ter sido o contexto anterior. Para mais informações e exemplos, consulte a Referência de variáveis de fluxo.

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 recebida, 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 um registo não é escrito sem que seja 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.

Nota: as chamadas de proxy são bem-sucedidas quando o registo falha

Uma vez que o registo de mensagens é escrito primeiro no buffer, o proxy da API continua a execução com êxito, mesmo que o registo de mensagens falhe (por exemplo, se houver uma falha de ligação ao destino).

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.

Nota: as variáveis de mensagem de resposta no Apigee não estão disponíveis a partir do fluxo de erros. Estas variáveis também não estão disponíveis no PostClientFlow se o fluxo anterior tiver sido o fluxo de erros. Se quiser registar informações de resposta do PostClientFlow, use o message. Pode usar este objeto para aceder aos cabeçalhos e a outras informações da resposta, quer tenha ocorrido ou não um erro. Consulte a referência de variáveis de fluxo para ver mais informações e um exemplo.

Valores predefinidos para variáveis no modelo de mensagem

Os valores predefinidos podem ser especificados para cada variável no modelo de mensagem em separado. 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>

Nota: o valor predefinido da variável não pode conter espaços.

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 desse 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
  • Consulte também esta publicação da comunidade do Apigee: Configurar o registo com o Sumo Logic
  • Para ver um exemplo completo que usa o Sumo Logic como o serviço de registo, consulte a seguinte publicação da comunidade do Apigee. A solução usa uma única política de JavaScript para fazer pedidos HTTP POST ao coletor de origem HTTP do Sumo Logic: Registo no Sumo Logic através de JavaScript e HTTP
• Loggly
  Quando usar o Loggly, <FormatMessage>true</FormatMessage> é obrigatório na política como elemento secundário do elemento <Syslog>.
  Consulte também esta publicação da comunidade do Apigee para mais informações sobre o registo de mensagens no Loggly: Registe mensagens no Loggly

Referência de erro

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

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

Nota: as chamadas de proxy são bem-sucedidas quando o registo falha

Existe uma diferença entre os erros de política e os erros de registo de mensagens. As variáveis de fluxo aqui são preenchidas apenas quando a própria política falha e não quando o registo de mensagens falha. Uma vez que o registo de mensagens é escrito primeiro no buffer, o proxy da API continua a execução com êxito, mesmo que o registo de mensagens falhe em última instância (por exemplo, se ocorrer uma falha de ligação ao fornecedor de syslog externo). Certifique-se de que verifica os registos regularmente para garantir que o registo está a ocorrer conforme esperado.

---

Tópicos relacionados

• Variáveis expostas pelo Apigee: referência de variáveis de fluxo