Partilhar via

Substituições de amostragem - Azure Monitor Application Insights for Java

  • Artigo

Nota

O recurso de substituições de amostragem está em GA, a partir da versão 3.5.0.

As substituições de amostragem permitem substituir a porcentagem de amostragem padrão, por exemplo:

  • Defina a percentagem de amostragem como 0 (ou algum valor pequeno) para verificações de saúde ruidosas.
  • Defina a porcentagem de amostragem como 0 (ou algum valor pequeno) para chamadas de dependência barulhentas.
  • Defina a porcentagem de amostragem como 100 para um tipo de solicitação importante (por exemplo, /login) mesmo que você tenha a amostragem padrão configurada para algo menor.

Terminologia

Antes de aprender sobre substituições de amostragem, você deve entender o termo span. Um span é um termo geral para:

  • Uma solicitação de entrada.
  • Uma dependência de saída (por exemplo, uma chamada remota para outro serviço).
  • Uma dependência em processo (por exemplo, trabalho sendo feito por subcomponentes do serviço).

Para substituições de amostragem, estes componentes de span são importantes:

  • Atributos

Os atributos span representam propriedades padrão e personalizadas de uma determinada solicitação ou dependência.

Introdução

Para começar, crie um arquivo de configuração chamado applicationinsights.json. Salve-o no mesmo diretório que applicationinsights-agent-*.jar. Utilize o modelo seguinte.

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

Como funciona

telemetryTypetelemetryKind( no Application Insights 3.4.0) deve ser um dos request, dependency, trace (log) ou exception.

Quando uma extensão é iniciada, o tipo de extensão e os atributos presentes nela naquele momento são usados para verificar se alguma das substituições de amostragem corresponde.

As partidas podem ser qualquer uma strict ou regexp. As correspondências de expressão regular são realizadas em relação ao valor do atributo inteiro, portanto, se você quiser corresponder a um valor que contenha abc qualquer lugar nele, precisará usar .*abc.*o . Uma substituição de amostragem pode especificar vários critérios de atributo, caso em que todos eles devem corresponder para que a substituição de amostragem corresponda.

Se uma das substituições da amostragem corresponder, a sua percentagem de amostragem é utilizada para decidir se a amostragem deve ou não ser amostrada.

Apenas a primeira substituição de amostragem que corresponde é usada.

Se nenhuma substituição de amostragem corresponder:

  • Se for a primeira extensão no rastreamento, a configuração de amostragem de nível superior será usada.
  • Se não for o primeiro período no rastreamento, a decisão de amostragem pai será usada.

Atributos de span disponíveis para amostragem

Os atributos de extensão OpenTelemetry são coletados automaticamente e baseados nas convenções semânticas OpenTelemetry .

Você também pode adicionar atributos span de forma programática e usá-los para amostragem.

Nota

Para ver o conjunto exato de atributos capturados pelo Application Insights Java para seu aplicativo, defina o nível de autodiagnóstico para depurar e procure mensagens de depuração começando com o texto "export span".

Nota

Somente os atributos definidos no início da extensão estão disponíveis para amostragem, portanto, atributos como http.response.status_code ou duração da solicitação que são capturados posteriormente podem ser filtrados por meio das extensões OpenTelemetry Java. Aqui está uma extensão de exemplo que filtra extensões com base na duração da solicitação.

Nota

Os atributos adicionados com um processador de telemetria não estão disponíveis para amostragem.

Casos de utilização

Suprimir telemetria de coleta para verificações de integridade

Este exemplo suprime a coleta de telemetria para todas as solicitações para /health-checks.

Este exemplo também suprime a coleta de quaisquer extensões a jusante (dependências) que normalmente seriam coletadas em /health-checks.

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

Suprimir a telemetria de coleta para uma chamada de dependência barulhenta

Este exemplo suprime a coleta de telemetria para todas as GET my-noisy-key chamadas redis.

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

Coletar 100% da telemetria para um tipo de solicitação importante

Este exemplo coleta 100% da telemetria para /login.

Como as extensões a jusante (dependências) respeitam a decisão de amostragem do pai (na ausência de qualquer substituição de amostragem para essa extensão a jusante), elas também são coletadas para todas as solicitações '/login'.

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

Expor atributos span para suprimir chamadas de dependência SQL

Este exemplo mostra a experiência de localizar atributos disponíveis para suprimir chamadas SQL barulhentas. A consulta abaixo descreve as diferentes chamadas SQL e contagens de registros associadas nos últimos 30 dias:

dependencies
| where timestamp > ago(30d)
| where name == 'SQL: DB Query'
| summarize count() by name, operation_Name, data
| sort by count_ desc

SQL: DB Query    POST /Order             DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    36712549    
SQL: DB Query    POST /Receipt           DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    2220248    
SQL: DB Query    POST /CheckOutForm      DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    554074    
SQL: DB Query    GET /ClientInfo         DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    37064

A partir dos resultados acima, pode-se observar que todas as operações compartilham o mesmo valor no data campo: DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;. A semelhança entre todos esses registros o torna um bom candidato para uma substituição de amostragem.

Ao definir o autodiagnóstico como depuração, as seguintes entradas de log ficarão visíveis na saída:

2023-10-26 15:48:25.407-04:00 DEBUG c.m.a.a.i.exporter.AgentSpanExporter - exporting span: SpanData{spanContext=ImmutableSpanContext...

A área de interesse desses logs é a seção "atributos":

{
  "attributes": {
    "data": {
      "thread.name": "DefaultDatabaseBroadcastTransport: MessageReader thread",
      "thread.id": 96,
      "db.connection_string": "apache:",
      "db.statement": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
      "db.system": "other_sql",
      "applicationinsights.internal.item_count": 1
    }
  }
}

Usando essa saída, você pode configurar uma substituição de amostragem semelhante à abaixo que filtrará nossas chamadas SQL barulhentas:

{
  "connectionString": "...",
  "preview": {
    "sampling": {
      "overrides": [
        {
          "telemetryType": "dependency",
          "attributes": [
            {
              "key": "db.statement",
              "value": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
              "matchType": "strict"
            }
          ],
          "percentage": 0
        }
      ]
    }
  }
}

Depois que as alterações são aplicadas, a consulta a seguir nos permite determinar a última vez que essas dependências foram ingeridas no Application Insights:

dependencies
| where timestamp > ago(30d)
| where data contains 'DECLARE @MyVar'
| summarize max(timestamp) by data
| sort by max_timestamp desc

DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    11/13/2023 8:52:41 PM

Suprimir telemetria de coleta para log

Com SL4J você pode adicionar atributos de log:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MdcClass {

  private static final Logger logger = LoggerFactory.getLogger(MdcClass.class);

  void method {
	
    MDC.put("key", "value");
    try {
       logger.info(...); // Application log to remove
    finally {
       MDC.remove("key"); // In a finally block in case an exception happens with logger.info
    }
	
  }
  
}

Em seguida, você pode remover o log com o atributo adicionado:

{
  "sampling": {
    "overrides": [
      {
        "telemetryType": "trace",
        "percentage": 0,
        "attributes": [
          {
            "key": "key",
            "value": "value",
            "matchType": "strict"
          }
        ]
      }
    ]
  }
}

Suprimir telemetria de coleta para um método Java

Vamos adicionar um span a um método Java e remover esse span com a substituição de amostragem.

Vamos primeiro adicionar a opentelemetry-instrumentation-annotations dependência:

    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    </dependency>

Agora podemos adicionar a WithSpan anotação a um método Java que executa solicitações SQL:

package org.springframework.samples.petclinic.vet;

@Controller
class VetController {

	private final VetRepository vetRepository;

	public VetController(VetRepository vetRepository) {
		this.vetRepository = vetRepository;
	}

	@GetMapping("/vets.html")
	public String showVetList(@RequestParam(defaultValue = "1") int page, Model model) {
		Vets vets = new Vets();
		Page<Vet> paginated = findPaginated(page);
		vets.getVetList().addAll(paginated.toList());
		return addPaginationModel(page, paginated, model);
	}

	@WithSpan
	private Page<Vet> findPaginated(int page) {
		int pageSize = 5;
		Pageable pageable = PageRequest.of(page - 1, pageSize);
		return vetRepository.findAll(pageable);  // Execution of SQL requests
	}

A seguinte configuração de substituição de amostra permite remover a extensão adicionada WithSpan pela anotação:

  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.function",
            "value": "findPaginated",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

O valor do atributo é o nome do método Java.

Essa configuração removerá todos os dados de telemetria criados a partir do findPaginated método. As dependências SQL não serão criadas para as execuções SQL provenientes do findPaginated método.

A configuração a seguir removerá todos os dados de telemetria VetController emitidos dos métodos da classe que tem a WithSpan anotação:

 "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.namespace",
            "value": "org.springframework.samples.petclinic.vet.VetController",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

Resolução de Problemas

Se você usar regexp e a substituição de amostragem não funcionar, tente com o .* regex. Se a amostragem agora funcionar, isso significa que você tem um problema com o primeiro regex e leia esta documentação do regex.

Se não funcionar com .*o , poderá ter um problema de sintaxe no .application-insights.json file Observe os logs do Application Insights e veja se você percebe mensagens de aviso.