Application Real-Time Monitoring Service:Extrair parâmetros de negócio para sua aplicação Java

Regras de extração de parâmetros

Especifique as origens que contêm os parâmetros a serem extraídos e o método de extração. É possível utilizar múltiplas fontes de parâmetros e etapas de processamento. Quando houver parâmetros disponíveis em várias origens, a extração seguirá a ordem de definição das etapas. Para mais informações, consulte {{XREF_2}}.

• Parameter Source: origem de onde os parâmetros serão extraídos. Ao selecionar Header, Cookie ou Parameter, insira a chave para a extração inicial. Se escolher Body ou Message, os parâmetros serão extraídos de todo o corpo ou mensagem.

• Add parameter processing steps: defina etapas para analisar os valores dos parâmetros a partir de uma ou mais origens. A saída de cada etapa torna-se a entrada da próxima. Sem nenhuma etapa especificada, o texto JSON bruto da origem será utilizado. Para mais detalhes, veja {{XREF_3}}. Os seguintes métodos de extração são suportados:

  Método	Descrição	Exemplo
  OGNL	A entrada deve ser um objeto Java. Suporta expressões OGNL com notação de ponto.	#this.data.getCode()
  JsonPath	Requer uma string JSON na entrada. Aceita expressões JsonPath com notação de ponto.	$.data.code
  Regex	Exige uma string como entrada. Utiliza grupos de captura nomeados. A substring a ser extraída deve corresponder a um grupo de captura chamado res.	.*from:(?<res>[a-z]+).*

Criar uma regra de código de erro personalizado

1. Na seção Customizing Error Settings, ative a chave Custom error code.

2. Clique em Add matching rules.

3. Selecione uma regra de extração e configure a condição de filtro.

   Após ativar a chave Custom error code, adicione regras de correspondência: um span será marcado como erro quando o valor do atributo biz.resp.body for maior que 200 e quando o valor do atributo biz.exception for superior a 0.

4. Clique em Save. A regra entra em vigor dentro de 1 a 2 minutos, sem necessidade de reiniciar a aplicação.

Verificar uma regra de código de erro personalizado

Após configurar uma regra, verifique na página Trace Explorer se há spans falhos que atendam às condições da regra.

1. Confirme o nome do atributo e a condição utilizados pela regra.

2. Na página Trace Explorer, filtre por spans falhos.

   Na página Trace Explorer, utilize a área de filtro rápido à esquerda para filtrar spans cujo status seja de erro. A condição de consulta resultante é serviceName="arms-custom-extraction-demoextracted" AND statusCode IN (2, 3) AND spanName="/api/v1/http_server/body". Neste exemplo, a consulta retorna 3.642 chamadas com erro, cada uma com duração de 0 ms e status de erro.

3. Clique em um trace e verifique se o valor do atributo corresponde à condição da regra. No exemplo a seguir, o valor do atributo biz.resp.body é 670, valor superior a 499 (o limiar especificado pela regra de correspondência de erro).

4. Na página Overview, confirme se a contagem de erros está refletida corretamente no painel de erros.

   

OGNL

A Object-Graph Navigation Language (OGNL) lê e define propriedades de objetos Java. Utilize-a para extrair campos de objetos anotados com @ResponseBody ou @RequestBody. O resultado é convertido em string. Caso o valor extraído seja um objeto Java, ele será serializado para uma string JSON para permitir extrações adicionais.

@RestController
@RequestMapping("/components/api/v1/mall")
public class MallController {
  @RequestMapping("/product")
  @ResponseBody
  public ResponseBody product(@RequestBody RequestBody req) {
    // Business code
  }

  static class RequestBody {
    String requestId;
    Map<String, String> queryParam;

    public String getQueryJsonStr() {
      return JSON.toJsonString(queryParam);
    }
  }

  static class ResponseBody {
    int code;
    boolean success;
    String message;
  }
}

Extrair o campo requestId de RequestBody.

Extrair o campo code de ResponseBody.

Invocar um método getter para extrair o resultado de getQueryJsonStr().

JsonPath

Expressões JsonPath extraem propriedades de uma string JSON.

{
  "code": 200,
  "message": "Query success.",
  "success": true,
  "data": {
    "name": "John",
    "age": 21
  }
}

Extrair data.age dos dados JSON.

Regex

Expressões regulares correspondem a combinações de caracteres em strings. Use um grupo de captura chamado res para especificar o resultado da extração.

https://test.aliyun.com/v2/workitem#requestId=0c978f115b6f7&cityCode=34&env=online

Extrair o valor de cityCode da URL.

Extração em múltiplas etapas

Este exemplo encadeia OGNL, JsonPath e Regex para extrair um valor aninhado do corpo de uma resposta.

A classe a seguir contém o objeto do corpo da resposta:

class DemoResponse {
    int code = 200;
    boolean success = true;
    String message = "text content";
    String extraInfo = "{\"id\": 15, \"cityInfo\": \"from:hangzhou,to:beijing\"}";

    public String getExtraInfo() {
        return this.extraInfo;
    }
}

Objetivo: extrair o nome da cidade indicado por "from" no subcampo cityInfo de extraInfo.

O agente do ARMS processa a extração nestas etapas:

1. Obter o objeto DemoResponse do corpo da resposta.

2. Executar #this.getExtraInfo() (OGNL) para obter o campo extraInfo.

3. Executar $.cityInfo (JsonPath) para analisar extraInfo como JSON e obter o subcampo cityInfo.

4. Executar ^from:(?<res>[a-z]+).* (Regex) para corresponder ao grupo de captura chamado res, que retorna hangzhou.

5. Gravar hangzhou como valor do atributo no span.

Como funcionam as etapas

As etapas de extração recuperam e analisam valores dos dados de origem. Elas formam um pipeline: a saída de cada etapa torna-se a entrada da seguinte.

Cada método exige um tipo de entrada específico. Se a entrada não corresponder, o pipeline é interrompido e o resultado atual é registrado como valor final.

Restrições de sintaxe

O ARMS impõe restrições de sintaxe mais rigorosas do que as versões open-source de OGNL, JsonPath e regex para manter a segurança.

Considerações de desempenho

As etapas de extração envolvem serialização/desserialização, reflexão Java e processamento de regex — as operações mais intensivas em recursos no pipeline de extração. Para interfaces sensíveis a latência, considere estas alternativas:

• Escreva parâmetros nos headers HTTP diretamente no código de negócio (caso a conformidade de segurança permita).

• Utilize o OpenTelemetry SDK for Java para gravar atributos diretamente nos spans. Para mais informações, consulte {{XREF_5}}.

O que fazer se a extração de parâmetros falhar?

A causa depende da origem do parâmetro:

• Body: verifique se o Spring MVC está em uso, se a classe possui a anotação @Controller e se o método tem a anotação @RequestBody ou @ResponseBody.

• Response Cookie: confirme que está executando Tomcat v7.0.4-9.x ou Undertow v1.4.0.Final+. Caso contrário, utilize request Cookie.

Qual é o escopo da extração de exceções?

O agente do ARMS para Java captura apenas exceções personalizadas lançadas fora dos spans. Para extrair exceções de métodos de chamada essenciais dentro dos spans e marcá-las como erros, instrumente o método de chamada. Para mais informações, consulte {{XREF_6}}.

Como mapear anotações do Spring MVC para regras de extração?

Como extrair tipos de parâmetros não suportados?

Utilize os SDKs do OpenTelemetry para instrumentar sua aplicação e gravar os parâmetros diretamente como atributos do span. Para mais detalhes, consulte {{XREF_7}}.

A extração suporta objetos Body com RequestBodyAdvice e ResponseBodyAdvice?

Sim. O agente do ARMS extrai parâmetros após a execução do BodyAdvice definido pelo usuário, mas antes do BodyAdvice nativo do Spring.