Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
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 Opcionalmente, use o elemento |
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 |
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 |
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 |
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. |
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:
As informações geradas pelo Apigee incluem:
Se for definida como falsa (predefinição), a mensagem não é precedida desses carateres fixos. |
PayloadOnly |
Nã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 é 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 |
SSLInfo |
Não |
Permite-lhe registar mensagens através de SSL/TLS. Use com o subelemento 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:
- Só foi executado como parte do fluxo de respostas.
- É 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
- 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 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. |
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 em caso de falha da política.
messagelogging.failed
messagelogging.{stepdefinition-name}.failed
Tópicos relacionados
- Variáveis expostas pelo Apigee: referência de variáveis de fluxo