Filter specific spans using OpenTelemetry - Managed Service for OpenTelemetry

Durum denetimleri, hazırlık yoklamaları ve diğer rutin istekler, izlerinize gürültü katan ve maliyetleri artıran yayılımlar oluşturur. Bu yayılımların uygulamanızdan çıkmasını engellemek için özel bir OpenTelemetry örnekleyici kullanın.

Managed Service for OpenTelemetry, Java ve Node.js uygulamaları için yayılım filtrelemeyi destekler.

Çalışma mantığı

OpenTelemetry, her yayılımın kaydedilip kaydedilmeyeceğine ve dışa aktarılıp aktarılmayacağına karar vermek için örnekleyicileri kullanır. Özel bir örnekleyici; yayılım adı veya HTTP hedef yolu gibi yayılım özelliklerini inceler ve aşağıdaki iki karardan birini verir:

DROP (SamplingDecision.DROP) -- Yayılım atılır. Kaydedilmez veya dışa aktarılmaz.
RECORD_AND_SAMPLE (SamplingDecision.RECORD_AND_SAMPLE) -- Yayılım korunur, normal şekilde kaydedilir ve dışa aktarılır.

İstenmeyen yayılımlarla eşleşen ve gürültüyü kaynağında ortadan kaldırmak için DROP değeri döndüren bir örnekleyici yazın.

Yöntem seçimi

Doğru yaklaşım, enstrümantasyon kurulumunuza ve programlama dilinize bağlıdır.

Java

Yöntem	Kullanım durumu	Gerekli kod değişiklikleri
Aracı uzantısı	OpenTelemetry Java Agent ile otomatik enstrümantasyon; uygulama kodunda değişiklik gerekmez	Ayrı bir JAR dosyası oluşturun
SDK örnekleyicisi	OpenTelemetry SDK for Java ile manuel enstrümantasyon	Örnekleyici sınıfını uygulama kodunuza ekleyin

Node.js

Yöntem	Kullanım durumu	Gerekli kod değişiklikleri
Oluşturma sırasında filtreleme	Belirli HTTP istekleri için yayılım oluşturulmasını önleme	`HttpInstrumentation` içindeki `ignoreIncomingRequestHook` öğesini yapılandırın
Dışa aktarma sırasında filtreleme	Yayılım oluşturulduktan sonra değerlendirilen niteliklere göre yayılımları atma	Özel bir örnekleyici sınıfı uygulayın

Java

OpenTelemetry Java Agent için aracı uzantısı oluşturma

Özel bir örnekleyiciyi Java Agent uzantısı olarak derleyin. Bu yaklaşım, filtreleme mantığını uygulama kodunuzdan ayrı tutar.

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

OpenTelemetry Java Agent ile otomatik olarak enstrümante edilmiş bir uygulama. Kurulum talimatları için bkz. Java uygulamalarının iz verilerini göndermek için OpenTelemetry kullanma
Uzantı JAR dosyasını derlemek için Apache Maven yüklü

1. Adım: Maven projesi oluşturma

Aracı uzantısını derlemek için yeni bir Maven projesi oluşturun.

2. Adım: Bağımlılıkları ekleme

Aşağıdaki bağımlılıkları pom.xml dosyanıza ekleyin.

Önemli

Tüm OpenTelemetry bağımlılıkları, kullandığınız OpenTelemetry Java Agent sürümüyle eşleşmelidir. Aşağıdaki örnekte 1.28.0 sürümü kullanılmaktadır.

<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>

3. Adım: Örnekleyiciyi uygulama

io.opentelemetry.sdk.trace.samplers.Sampler arayüzünü uygulayan bir sınıf oluşturun. Filtreleme kurallarınızı shouldSample yönteminde tanımlayın ve getDescription yönteminden bir örnekleyici adı döndürün.

shouldSample -- Her yayılımı değerlendirin; atılacak yayılımlar için SamplingResult.create(SamplingDecision.DROP) değerini, korunacak yayılımlar için ise SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) değerini döndürün.
getDescription -- Örnekleyici adını döndürün.

Aşağıdaki örnek, spanName1 veya spanName2 adlı yayılımları ve http.target niteliği /api/checkHealth ya da /health/checks olan yayılımları atar:

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";
    }
}

4. Adım: Örnekleyici sağlayıcısını uygulama

io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider arayüzünü uygulayan bir sınıf oluşturun. Bu sağlayıcı, örnekleyicinizi Java Agent'ın otomatik yapılandırma mekanizmasına kaydeder.

createSampler -- Örnekleyicinizin bir örneğini döndürün.
getName -- Örnekleyici adını döndürün. Java Agent, örnekleyiciyi bulmak için bu adı kullanır.

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";
    }
}

5. Adım: Uzantı JAR dosyasını derleme

Projeyi bir JAR dosyasına paketleyin:

mvn clean package

JAR dosyası target dizininde oluşturulur.

6. Adım: Başlangıçta uzantıyı yükleme

Uygulamayı başlatırken özel örnekleyicinizi belirtin. Bir JVM sistem özelliği veya ortam değişkeni kullanabilirsiniz.

Seçenek A: JVM sistem özelliği

JVM başlatma parametrelerine -Dotel.traces.sampler=<your-sampler-name> ekleyin. <your-sampler-name> yerine getName yöntemi tarafından döndürülen değeri yazın.

Tam başlatma komutu:

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

Seçenek B: Ortam değişkeni

OTEL_TRACES_SAMPLER ortam değişkenini örnekleyici adınıza ayarlayın:

Başlatma komutunun tam örneğini görüntülemek için tıklayın

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

Aşağıdaki yer tutucuları gerçek değerlerinizle değiştirin:

Yer tutucu	Açıklama
`<your-sampler-name>`	`getName` tarafından döndürülen örnekleyici adı
`<token>`	OTLP uç noktası için kimlik doğrulama belirteci
`<endpoint>`	OTLP dışa aktarıcı uç noktası URL'si

OpenTelemetry SDK for Java ile özel örnekleyiciyi kaydetme

Manuel enstrümantasyona sahip uygulamalar için örnekleyiciyi doğrudan uygulama kodunuza ekleyin.

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

OpenTelemetry SDK for Java ile manuel olarak enstrümante edilmiş bir uygulama. Kurulum talimatları için bkz. Java uygulamalarının iz verilerini göndermek için OpenTelemetry kullanma

1. Adım: Örnekleyici sınıfını oluşturma

Sampler arayüzünü uygulayan bir SpanFilterSampler sınıfı oluşturun. Uygulama, 3. Adım: Örnekleyiciyi uygulama bölümündeki aracı uzantısı örnekleyicisiyle aynıdır. Atmak istediğiniz yayılımlarla eşleşmesi için EXCLUDED_SPAN_NAMES ve EXCLUDED_HTTP_REQUEST_TARGETS listelerini uyarlayın.

2. Adım: Örnekleyiciyi SdkTracerProvider ile kaydetme

SdkTracerProvider örneğini oluştururken .setSampler(new SpanFilterSampler()) çağrısı yapın:

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();

3. Adım: Uygulamayı yeniden başlatma

Uygulamanızı yeniden başlatın. Örnekleyici, her yeni yayılımı değerlendirir ve filtre kurallarıyla eşleşenleri atar.

Node.js

Demo projesi: opentelemetry-nodejs-demo

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

Managed Service for OpenTelemetry API for JavaScript ile enstrümante edilmiş bir uygulama. Kurulum talimatları için bkz. Node.js uygulamasının iz verilerini göndermek için OpenTelemetry kullanma

Oluşturma sırasında yayılımları filtreleme

HttpInstrumentation içinde ignoreIncomingRequestHook yapılandırarak belirli HTTP isteklerinin yayılım oluşturmasını önleyin. Kanca, istek işlemeden önce çalışır ve yalnızca bir yayılımın oluşturulup oluşturulmayacağını kontrol eder; istek kendisi normal şekilde işlenir.

Aşağıdaki örnek, /api/checkHealth adresine yapılan istekler için yayılım oluşturmayı atlar:

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],
});

Enstrümantasyon yapılandırmasını güncelledikten sonra uygulamayı başlatın.

Dışa aktarma sırasında yayılımları filtreleme

Özel bir örnekleyici uygulayarak, oluşturulduktan sonra yayılımları niteliklerine göre atın.

1. Adım: Örnekleyici sınıfı oluşturma

Sampler arayüzünü uygulayan bir sınıf oluşturun. Filtreleme mantığınızı shouldSample içinde tanımlayın:

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

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

2. Adım: Örnekleyiciyi NodeTracerProvider ile kaydetme

Örnekleyici örneğini NodeTracerProvider oluşturucusuna iletin:

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>",
  }),
});

<your-service-name> yerine hizmetinizin adını yazın; örneğin my-node-app.

Sağlayıcı yapılandırmasını güncelledikten sonra uygulamayı başlatın.

Filtrelemenin çalıştığını doğrulama

Özel bir örnekleyiciyi yapılandırdıktan ve dağıttıktan sonra yayılımların doğru şekilde filtrelendiğini doğrulayın:

Filtre kurallarınızla eşleşen trafik oluşturun. Örneğin, /api/checkHealth veya diğer filtrelenen uç noktalara istek gönderin.
Managed Service for OpenTelemetry konsolunu açın. Filtrelenen yayılımlar artık izlerinizde görünmemelidir.
Filtrelemeden önceki ve sonraki yayılım sayısını karşılaştırın. Filtrelenen uç noktalar için yayılım hacmindeki azalma, örnekleyicinin çalıştığını gösterir.

Filtrelenen yayılımlar hala görünüyorsa aşağıdakileri kontrol edin:

Belirti	Olası neden	Çözüm
Yayılımlar hala dışa aktarılıyor	Örnekleyici kaydedilmemiş	`OTEL_TRACES_SAMPLER` veya `-Dotel.traces.sampler` değerinin örnekleyici adınıza ayarlandığını doğrulayın
Başlangıçta örnekleyici bulunamadı hatası	Ad uyuşmazlığı	Sağlayıcıdaki `getName()` yönteminin, başlatma parametresinde kullanılan adla aynı adı döndürdüğünden emin olun
Uzantı JAR dosyası yüklenmedi	Yol hatalı	`OTEL_JAVAAGENT_EXTENSIONS` veya `-Dotel.javaagent.extensions` içindeki yolun doğru JAR dosyasını işaret ettiğini doğrulayın
Yanlış yayılımlar filtrelendi	Filtre kuralı mantık hatası	`shouldSample` içindeki koşulları gözden geçirin ve yayılım adları ile nitelik değerlerinin beklentilerinizle eşleştiğini onaylayın