Cloud Monitor:Extraia parâmetros de negócio para sua aplicação Python

Configuração da regra

Métodos de processamento de parâmetro

A tabela abaixo detalha os métodos de processamento de parâmetros compatíveis com a versão Python.

Como funciona a correspondência da interface ativa

O alvo da correspondência é o nome do Span, no formato Request method Route, como POST /api/order ou GET /api/user/{id}. Tenha em mente o seguinte:

• Equals /api/order não corresponde. Configure como Equals POST /api/order.

• Alternativamente, use Ends with /api/order.

• Ou utilize a expressão regular .*/api/order (expressões regulares também usam semântica de correspondência total).

O que causa falha na extração de parâmetros?

• O tipo ou a source de extração de parâmetro não está no escopo suportado (por exemplo, a fonte Body ou Cookie para o cliente). Consulte Supported scope para verificar se o framework e a source atuais são compatíveis.

• A regra de correspondência da interface ativa está configurada incorretamente. O alvo da correspondência é o nome do Span no formato Request method Route. Uma regra como Equals /api/order não corresponde. Consulte How the active interface matches.

• A sintaxe da etapa de processamento de parâmetro está incorreta ou o tipo de entrada não corresponde aos requisitos do método de processamento:

  • Regex deve conter um grupo nomeado chamado res e usa semântica de correspondência total. Para corresponder a uma substring, adicione .* em ambos os lados.

  • A entrada para JsonPath deve ser um objeto JSON ou texto JSON. Executar JsonPath em uma string simples (como o valor de Header abc) não produz resultado.

• A versão do agente Python é anterior à 3.1.0, que não oferece suporte à extração de parâmetros de negócio.

• A aplicação não foi reiniciada após a criação da primeira regra.

O que causa falha na extração do Body?

Para evitar afetar a leitura do corpo da requisição ou resposta pela própria aplicação, o agente realiza uma verificação de admissão antes de ler o Body. Se qualquer uma das condições a seguir não for atendida, a source Body será totalmente ignorada (não truncada antes da análise):

• Content-Type não é JSON — Apenas application/json ou tipos de mídia terminados com +json são compatíveis. Tipos como text/plain, application/x-www-form-urlencoded, multipart/form-data e tipos binários não são extraídos.

• Content-Length ausente ou excede o limite — Se o cabeçalho da requisição não contiver Content-Length (por exemplo, codificação de transferência chunked), ou se o comprimento do Body exceder o limite superior (64 KB por padrão), todo o Body será ignorado.

• Body não é JSON válido codificado em UTF-8 — Se a decodificação ou a análise JSON falhar, o Body será ignorado.

• Resposta em streaming — Respostas de streaming do Flask ou direct_passthrough, StreamingHttpResponse do Django e StreamingResponse do FastAPI/Starlette (incluindo SSE) não extraem o Body da resposta.

A seguir estão cenários específicos de frameworks:

• FastAPI — O Body da requisição fica visível apenas quando a aplicação realmente o lê — ou seja, o endpoint declara um parâmetro Body (como um modelo Pydantic ou Body()), ou o código chama await request.body() ou await request.json(). Se o endpoint não ler o corpo da requisição, o agente não consome ativamente o fluxo da requisição e o Body não pode ser extraído.

• Django — Se a aplicação consumir primeiro o fluxo da requisição usando request.read() (acionando RawPostDataException), ou se o Body exceder o limite DATA_UPLOAD_MAX_MEMORY_SIZE do Django (acionando RequestDataTooBig), o Body não poderá ser extraído. A leitura normal através de request.body não é afetada (o Django armazena o body em cache, então a aplicação ainda pode lê-lo normalmente).

• Flask — O agente lê e armazena em cache o corpo da requisição usando request.get_data(cache=True). A aplicação ainda pode ler o corpo normalmente depois disso, sem limitações adicionais.

E se o valor extraído não corresponder às expectativas?

• Valor termina com ...: O valor excedeu o limite de comprimento do valor extraído (100 caracteres por padrão) e foi truncado. Aumente o limite de comprimento.

• Valor é ***: A dessensibilização está ativada para esta regra ou globalmente.

• Valor está no formato [a,b]: Existem múltiplos valores para o mesmo Header ou Query Parameter e eles foram mesclados.

• Quando o JsonPath corresponde a múltiplos nós, apenas o primeiro resultado é retornado.

• Quando múltiplas regras gravam no mesmo nome de Attribute, a regra aplicada posteriormente sobrescreve a anterior.

Posso usar a source Query Parameter para extrair campos de formulário de um Body de requisição codificado como formulário?

Não. Quando o Content-Type da requisição é application/x-www-form-urlencoded, a source Query Parameter é totalmente ignorada para evitar que o agente acione a análise de formulário do framework e afete a leitura do corpo da requisição pela própria aplicação. Para tais parâmetros, passe-os através de strings de consulta de URL ou Headers, ou adicione instrumentação personalizada conforme descrito na próxima pergunta.

Como extraio fontes de parâmetros de negócio não compatíveis com a versão Python?

Adicione instrumentação personalizada usando o SDK do OpenTelemetry para aplicações Python para gravar parâmetros de negócio como Attributes em um Span.