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>api</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 Opcionalmente, use o elemento |
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 |
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 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 |
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 |
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. |
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:
As informações geradas pela Apigee incluem:
Se definida como falsa (padrão), a mensagem não será anexada com os caracteres fixos. |
PayloadOnly |
Nã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á 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 |
SSLInfo |
Não |
Permite que você registre mensagens por SSL/TLS. Use com
o subelemento 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:
- Ele só é executado como parte do fluxo de resposta.
- 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:
- 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.
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. |
build |
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. |
build |
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
- Variáveis expostas pela Apigee: Referência de variáveis de fluxo