Filtrar spans específicos usando OpenTelemetry - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Verificações de integridade, probes de prontidão e outras requisições rotineiras geram spans que adicionam ruído aos traces e aumentam os custos. Use um sampler personalizado do OpenTelemetry para descartar esses spans antes que saiam da aplicação.

O Managed Service for OpenTelemetry oferece suporte à filtragem de spans para aplicações Java e Node.js.

Como funciona

O OpenTelemetry usa samplers para decidir se deve registrar e exportar cada span. Um sampler personalizado inspeciona as propriedades do span — como o nome ou o caminho de destino HTTP — e retorna uma de duas decisões:

DROP (SamplingDecision.DROP) — O sistema descarta o span. Ele não é registrado nem exportado.
RECORD_AND_SAMPLE (SamplingDecision.RECORD_AND_SAMPLE) — O sistema mantém, registra e exporta o span normalmente.

Escreva um sampler que identifique os spans indesejados e retorne DROP para eliminar o ruído na origem.

Escolha um método

A abordagem ideal depende da configuração de instrumentação e da linguagem de programação.

Java

Método	Quando usar	Alterações de código necessárias
Extensão de agente	Instrumentação automática com OpenTelemetry Java Agent; sem necessidade de alterar o código da aplicação	Crie um JAR separado
Sampler do SDK	Instrumentação manual com OpenTelemetry SDK for Java	Adicionar a classe do sampler ao código da aplicação

Node.js

Método	Quando usar	Alterações de código necessárias
Filtrar na criação	Impedir a criação de spans para requisições HTTP específicas	Configure `ignoreIncomingRequestHook` em `HttpInstrumentation`
Filtrar na exportação	Descartar spans com base em atributos avaliados após a criação	Implementar uma classe de sampler personalizada

Java

Crie uma extensão de agente para OpenTelemetry Java Agent

Crie um sampler personalizado como uma extensão do Java Agent. Essa abordagem mantém a lógica de filtragem separada do código da aplicação.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma aplicação instrumentada automaticamente com OpenTelemetry Java Agent. Para instruções de configuração, consulte Usar o OpenTelemetry para enviar dados de trace de aplicações Java
Apache Maven instalado para compilar o JAR da extensão

Etapa 1: Crie um projeto Maven

Crie um novo projeto Maven para compilar a extensão do agente.

Etapa 2: Adicionar dependências

Adicione as seguintes dependências ao arquivo pom.xml.

Importante

Todas as dependências do OpenTelemetry devem corresponder à versão do OpenTelemetry Java Agent em uso. O exemplo a seguir usa a versão 1.28.0.

<dependency>
  <groupId>com.google.auto.service</groupId>
  <artifactId>auto-service</artifactId>
  <version>1.1.1</version>
</dependency>

<dependency>
  <groupId>io.opentelemetry.javaagent</groupId>
  <artifactId>opentelemetry-javaagent</artifactId>
  <version>1.28.0</version>
  <!--Set the scope to compile.-->
  <scope>compile</scope>
</dependency>

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-trace</artifactId>
  <version>1.28.0</version>
</dependency>

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
  <version>1.28.0</version>
</dependency>

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-semconv</artifactId>
  <version>1.28.0-alpha</version>
</dependency>

Etapa 3: Implementar o sampler

Crie uma classe que implemente a interface io.opentelemetry.sdk.trace.samplers.Sampler. Defina as regras de filtragem no método shouldSample e retorne um nome para o sampler a partir de getDescription.

shouldSample — Avalie cada span e retorne SamplingResult.create(SamplingDecision.DROP) para descartá-lo ou SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) para mantê-lo.
getDescription — Retorne o nome do sampler.

O exemplo a seguir descarta spans chamados spanName1 ou spanName2, além de spans com um atributo http.target igual a /api/checkHealth ou /health/checks:

package org.example;

import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Context;
import io.opentelemetry.sdk.trace.data.LinkData;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import io.opentelemetry.sdk.trace.samplers.SamplingDecision;
import io.opentelemetry.sdk.trace.samplers.SamplingResult;
import io.opentelemetry.semconv.trace.attributes.SemanticAttributes;

import java.util.*;

public class SpanFilterSampler implements Sampler {

    // Span names to drop
    private static List<String> EXCLUDED_SPAN_NAMES = Collections.unmodifiableList(
        Arrays.asList("spanName1", "spanName2")
    );

    // HTTP target paths to drop
    private static List<String> EXCLUDED_HTTP_REQUEST_TARGETS = Collections.unmodifiableList(
        Arrays.asList("/api/checkHealth", "/health/checks")
    );

    @Override
    public SamplingResult shouldSample(Context parentContext, String traceId, String name,
            SpanKind spanKind, Attributes attributes, List<LinkData> parentLinks) {

        String httpTarget = attributes.get(SemanticAttributes.HTTP_TARGET) != null
            ? attributes.get(SemanticAttributes.HTTP_TARGET) : "";

        if (EXCLUDED_SPAN_NAMES.contains(name)
                || EXCLUDED_HTTP_REQUEST_TARGETS.contains(httpTarget)) {
            return SamplingResult.create(SamplingDecision.DROP);
        }
        return SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE);
    }

    @Override
    public String getDescription() {
        return "SpanFilterSampler";
    }
}

Etapa 4: Implementar o provedor do sampler

Crie uma classe que implemente io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider. Esse provedor registra o sampler no mecanismo de autoconfiguração do Java Agent.

createSampler — Retorne uma instância do sampler.
getName — Retorne o nome do sampler. O Java Agent usa esse nome para localizar o sampler.

package org.example;

import com.google.auto.service.AutoService;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider;
import io.opentelemetry.sdk.trace.samplers.Sampler;

@AutoService(ConfigurableSamplerProvider.class)
public class SpanFilterSamplerProvider implements ConfigurableSamplerProvider {

    @Override
    public Sampler createSampler(ConfigProperties configProperties) {
        return new SpanFilterSampler();
    }

    @Override
    public String getName() {
        return "SpanFilterSampler";
    }
}

Etapa 5: Compilar o JAR da extensão

Empacote o projeto em um arquivo JAR:

mvn clean package

O sistema gera o arquivo JAR no diretório target.

Etapa 6: Carregar a extensão na inicialização

Especifique o sampler personalizado ao iniciar a aplicação. Use uma propriedade de sistema da JVM ou uma variável de ambiente.

Opção A: Propriedade de sistema da JVM

Adicione -Dotel.traces.sampler=<your-sampler-name> aos parâmetros de inicialização da JVM. Substitua <your-sampler-name> pelo valor retornado pelo método getName.

Comando completo de inicialização:

java -javaagent:path/to/opentelemetry-javaagent.jar \
  -Dotel.javaagent.extensions=path/to/opentelemetry-java-agent-extension.jar \
  -Dotel.traces.sampler=<your-sampler-name> \
  -Dotel.exporter.otlp.headers=Authentication=<token> \
  -Dotel.exporter.otlp.endpoint=<endpoint> \
  -Dotel.metrics.exporter=none \
  -jar yourapp.jar

Opção B: Variável de ambiente

Defina a variável de ambiente OTEL_TRACES_SAMPLER com o nome do sampler:

Clique em para visualizar um exemplo completo do comando de início

export OTEL_JAVAAGENT_EXTENSIONS="path/to/opentelemetry-java-agent-extension.jar"
export OTEL_TRACES_SAMPLER="<your-sampler-name>"
export OTEL_EXPORTER_OTLP_HEADERS="Authentication=<token>"
export OTEL_EXPORTER_OTLP_ENDPOINT="<endpoint>"
export OTEL_METRICS_EXPORTER="none"

java -javaagent:path/to/opentelemetry-javaagent.jar \
  -jar yourapp.jar

Substitua os seguintes espaços reservados pelos valores reais:

Espaço reservado	Descrição
`<your-sampler-name>`	Nome do sampler retornado por `getName`
`<token>`	Token de autenticação para o endpoint OTLP
`<endpoint>`	URL do endpoint do exportador OTLP

Registrar um sampler personalizado com OpenTelemetry SDK for Java

Para aplicações com instrumentação manual, adicione o sampler diretamente ao código da aplicação.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma aplicação instrumentada manualmente com OpenTelemetry SDK for Java. Para instruções de configuração, consulte Usar o OpenTelemetry para enviar dados de trace de aplicações Java

Etapa 1: Crie a classe do sampler

Crie uma classe SpanFilterSampler que implemente a interface Sampler. A implementação é idêntica à do sampler de extensão de agente na Etapa 3: Implementar o sampler. Adapte as listas EXCLUDED_SPAN_NAMES e EXCLUDED_HTTP_REQUEST_TARGETS para corresponder aos spans que deseja descartar.

Etapa 2: Registrar o sampler no SdkTracerProvider

Chame .setSampler(new SpanFilterSampler()) ao construir a instância de SdkTracerProvider:

SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
    .setSampler(new SpanFilterSampler())  // Register the custom sampler
    .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
        .setEndpoint("<endpoint>")
        .addHeader("Authentication", "<token>")
        .build()).build())
    .setResource(resource)
    .build();

Etapa 3: Reiniciar a aplicação

Reinicie a aplicação. O sampler avalia cada novo span e descarta aqueles que correspondem às regras de filtragem.

Node.js

Projeto de demonstração: opentelemetry-nodejs-demo

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma aplicação instrumentada com a API do Managed Service for OpenTelemetry para JavaScript. Para instruções de configuração, consulte Usar o OpenTelemetry para enviar dados de trace de uma aplicação Node.js

Filtrar spans no momento da criação

Impeça que requisições HTTP específicas gerem spans configurando ignoreIncomingRequestHook em HttpInstrumentation. O hook executa antes do processamento da requisição e controla apenas a criação do span — o sistema trata a requisição normalmente.

O exemplo a seguir ignora a criação de spans para requisições destinadas a /api/checkHealth:

const httpInstrumentation = new HttpInstrumentation({
  ignoreIncomingRequestHook: (request) => {
    // Skip span creation for health check requests
    if (request.url === '/api/checkHealth') {
      return true;
    }
    return false;
  },
});

registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [httpInstrumentation, ExpressInstrumentation],
});

Inicie a aplicação após atualizar a configuração de instrumentação.

Filtrar spans no momento da exportação

Descarte spans com base nos atributos após a criação implementando um sampler personalizado.

Etapa 1: Crie uma classe de sampler

Crie uma classe que implemente a interface Sampler. Defina a lógica de filtragem em shouldSample:

const opentelemetry = require('@opentelemetry/api');

class SpanFilterSampler {
  shouldSample(spanContext, parentContext) {
    // Implement your custom sampling logic here.
  }
}

Etapa 2: Registrar o sampler no NodeTracerProvider

Passe a instância do sampler para o construtor de NodeTracerProvider:

const provider = new NodeTracerProvider({
  sampler: new SpanFilterSampler(),  // Register the custom sampler
  resource: new Resource({
    [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
    [SemanticResourceAttributes.SERVICE_NAME]: "<your-service-name>",
  }),
});

Substitua <your-service-name> pelo nome do serviço, por exemplo, my-node-app.

Inicie a aplicação após atualizar a configuração do provedor.

Verifique se a filtragem funciona

Após configurar e implantar um sampler personalizado, verifique se a filtragem de spans ocorre corretamente:

Gere tráfego correspondente às regras de filtragem. Por exemplo, envie requisições para /api/checkHealth ou outros endpoints filtrados.
Abra o console do Managed Service for OpenTelemetry. Os spans filtrados não devem mais aparecer nos traces.
Compare a contagem de spans antes e depois da filtragem. A redução no volume de spans para os endpoints filtrados confirma o funcionamento do sampler.

Se os spans filtrados ainda aparecerem, verifique os itens a seguir:

Sintoma	Causa possível	Resolução
Spans ainda são exportados	Sampler não registrado	Verifique se `OTEL_TRACES_SAMPLER` ou `-Dotel.traces.sampler` está definido com o nome do sampler
Erro de sampler não encontrado na inicialização	Incompatibilidade de nome	Certifique-se de que `getName()` no provedor retorna o mesmo nome usado no parâmetro de inicialização
JAR da extensão não carregado	Caminho incorreto	Verifique se o caminho em `OTEL_JAVAAGENT_EXTENSIONS` ou `-Dotel.javaagent.extensions` aponta para o arquivo JAR correto
Spans errados filtrados	Erro na lógica da regra de filtragem	Revise as condições em `shouldSample` e confirme se os nomes dos spans e os valores dos atributos correspondem ao esperado