Filter span tertentu menggunakan OpenTelemetry - Managed Service for OpenTelemetry

Pemeriksaan kesehatan, pemeriksaan kesiapan, dan permintaan rutin lainnya menghasilkan span yang menambah kebisingan pada jejak Anda serta meningkatkan biaya. Gunakan sampler kustom OpenTelemetry untuk membuang span tersebut sebelum meninggalkan aplikasi Anda.

Managed Service for OpenTelemetry mendukung penyaringan span untuk aplikasi Java dan Node.js.

Cara kerja

OpenTelemetry menggunakan sampler untuk menentukan apakah setiap span akan direkam dan diekspor. Sampler kustom memeriksa properti span—seperti nama span atau path target HTTP—lalu mengembalikan salah satu dari dua keputusan berikut:

DROP (SamplingDecision.DROP) — Span dibuang; tidak direkam maupun diekspor.
RECORD_AND_SAMPLE (SamplingDecision.RECORD_AND_SAMPLE) — Span dipertahankan, direkam, dan diekspor secara normal.

Buatlah sampler yang menargetkan span yang tidak diinginkan dan kembalikan DROP untuk menghilangkan kebisingan sejak sumbernya.

Pilih metode

Pendekatan yang tepat tergantung pada pengaturan instrumentasi dan bahasa pemrograman Anda.

Java

Metode	Kapan digunakan	Perubahan kode yang diperlukan
Agent extension	Instrumentasi otomatis dengan OpenTelemetry Java Agent; tidak perlu mengubah kode aplikasi	Buat JAR terpisah
SDK sampler	Instrumentasi manual dengan OpenTelemetry SDK untuk Java	Tambahkan kelas sampler ke kode aplikasi Anda

Node.js

Metode	Kapan digunakan	Perubahan kode yang diperlukan
Filter saat pembuatan	Cegah pembuatan span untuk permintaan HTTP tertentu	Konfigurasikan `ignoreIncomingRequestHook` dalam `HttpInstrumentation`
Filter saat ekspor	Buang span berdasarkan atribut yang dievaluasi setelah pembuatan span	Implementasikan kelas sampler kustom

Java

Buat agent extension untuk OpenTelemetry Java Agent

Buat sampler kustom sebagai ekstensi Java Agent. Pendekatan ini menjaga logika penyaringan terpisah dari kode aplikasi Anda.

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Aplikasi yang diinstrumentasi secara otomatis dengan OpenTelemetry Java Agent. Untuk petunjuk penyiapan, lihat Use OpenTelemetry to submit the trace data of Java applications
Apache Maven terinstal untuk membangun JAR ekstensi.

Langkah 1: Buat proyek Maven

Buat proyek Maven baru untuk membangun ekstensi agent.

Langkah 2: Tambahkan dependensi

Tambahkan dependensi berikut ke file pom.xml Anda.

Penting

Semua dependensi OpenTelemetry harus sesuai dengan versi OpenTelemetry Java Agent yang Anda gunakan. Contoh berikut menggunakan versi 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>

Langkah 3: Implementasikan sampler

Buat kelas yang mengimplementasikan antarmuka io.opentelemetry.sdk.trace.samplers.Sampler. Definisikan aturan penyaringan Anda dalam metode shouldSample dan kembalikan nama sampler dari getDescription.

shouldSample — Evaluasi setiap span dan kembalikan SamplingResult.create(SamplingDecision.DROP) untuk span yang akan dibuang, atau SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) untuk span yang akan dipertahankan.
getDescription — Kembalikan nama sampler.

Contoh berikut membuang span bernama spanName1 atau spanName2, serta span dengan atribut http.target bernilai /api/checkHealth atau /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 {

    // Nama span yang akan dibuang
    private static List<String> EXCLUDED_SPAN_NAMES = Collections.unmodifiableList(
        Arrays.asList("spanName1", "spanName2")
    );

    // Path target HTTP yang akan dibuang
    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";
    }
}

Langkah 4: Implementasikan penyedia sampler

Buat kelas yang mengimplementasikan io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider. Penyedia ini mendaftarkan sampler Anda ke mekanisme konfigurasi otomatis Java Agent.

createSampler — Kembalikan instance sampler Anda.
getName — Kembalikan nama sampler. Java Agent menggunakan nama ini untuk menemukan 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";
    }
}

Langkah 5: Bangun JAR ekstensi

Kemas proyek menjadi file JAR:

mvn clean package

File JAR dihasilkan di direktori target.

Langkah 6: Muat ekstensi saat startup

Tentukan sampler kustom Anda saat menjalankan aplikasi. Gunakan properti sistem JVM atau variabel lingkungan.

Opsi A: Properti sistem JVM

Tambahkan -Dotel.traces.sampler=<your-sampler-name> ke parameter startup JVM. Ganti <your-sampler-name> dengan nilai yang dikembalikan oleh metode getName.

Perintah startup lengkap:

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

Opsi B: Variabel lingkungan

Atur variabel lingkungan OTEL_TRACES_SAMPLER ke nama sampler Anda:

Klik untuk melihat contoh lengkap perintah startup

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

Ganti placeholder berikut dengan nilai aktual Anda:

Placeholder	Deskripsi
`<your-sampler-name>`	Nama sampler yang dikembalikan oleh `getName`
`<token>`	Token autentikasi untuk endpoint OTLP
`<endpoint>`	URL endpoint eksporter OTLP

Daftarkan sampler kustom dengan OpenTelemetry SDK untuk Java

Untuk aplikasi dengan instrumentasi manual, tambahkan sampler langsung ke kode aplikasi Anda.

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Aplikasi yang diinstrumentasi secara manual dengan OpenTelemetry SDK untuk Java. Untuk petunjuk penyiapan, lihat Use OpenTelemetry to submit the trace data of Java applications

Langkah 1: Buat kelas sampler

Buat kelas SpanFilterSampler yang mengimplementasikan antarmuka Sampler. Implementasinya sama dengan sampler ekstensi agent di Langkah 3: Implementasikan sampler. Sesuaikan daftar EXCLUDED_SPAN_NAMES dan EXCLUDED_HTTP_REQUEST_TARGETS agar sesuai dengan span yang ingin Anda buang.

Langkah 2: Daftarkan sampler ke SdkTracerProvider

Panggil .setSampler(new SpanFilterSampler()) saat membuat instance SdkTracerProvider:

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

Langkah 3: Mulai ulang aplikasi

Mulai ulang aplikasi Anda. Sampler akan mengevaluasi setiap span baru dan membuang span yang sesuai dengan aturan filter.

Node.js

Proyek demo: opentelemetry-nodejs-demo

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Aplikasi yang diinstrumentasi dengan Managed Service for OpenTelemetry API untuk JavaScript. Untuk petunjuk penyiapan, lihat Use OpenTelemetry to submit the trace data of a Node.js application

Filter span saat pembuatan

Cegah permintaan HTTP tertentu menghasilkan span dengan mengonfigurasi ignoreIncomingRequestHook dalam HttpInstrumentation. Hook ini dijalankan sebelum pemrosesan permintaan dan hanya mengontrol apakah span dibuat—permintaan itu sendiri tetap ditangani secara normal.

Contoh berikut melewatkan pembuatan span untuk permintaan ke /api/checkHealth:

const httpInstrumentation = new HttpInstrumentation({
  ignoreIncomingRequestHook: (request) => {
    // Lewati pembuatan span untuk permintaan pemeriksaan kesehatan
    if (request.url === '/api/checkHealth') {
      return true;
    }
    return false;
  },
});

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

Jalankan aplikasi setelah memperbarui konfigurasi instrumentasi.

Filter span saat ekspor

Buang span berdasarkan atributnya setelah pembuatan dengan mengimplementasikan sampler kustom.

Langkah 1: Buat kelas sampler

Buat kelas yang mengimplementasikan antarmuka Sampler. Definisikan logika penyaringan Anda dalam shouldSample:

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

class SpanFilterSampler {
  shouldSample(spanContext, parentContext) {
    // Implementasikan logika sampling kustom Anda di sini.
  }
}

Langkah 2: Daftarkan sampler ke NodeTracerProvider

Berikan instance sampler ke konstruktor NodeTracerProvider:

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

Ganti <your-service-name> dengan nama layanan Anda, misalnya my-node-app.

Jalankan aplikasi setelah memperbarui konfigurasi provider.

Verifikasi bahwa penyaringan berfungsi

Setelah mengonfigurasi dan menerapkan sampler kustom, verifikasi bahwa span disaring dengan benar:

Hasilkan traffic yang sesuai dengan aturan filter Anda. Misalnya, kirim permintaan ke /api/checkHealth atau endpoint yang difilter lainnya.
Buka Konsol Managed Service for OpenTelemetry. Span yang difilter seharusnya tidak lagi muncul dalam jejak Anda.
Bandingkan jumlah span sebelum dan sesudah penyaringan. Penurunan volume span untuk endpoint yang difilter mengonfirmasi bahwa sampler berfungsi.

Jika span yang difilter masih muncul, periksa hal berikut:

Gejala	Kemungkinan penyebab	Penyelesaian
Span tetap diekspor	Sampler tidak terdaftar	Verifikasi bahwa `OTEL_TRACES_SAMPLER` atau `-Dotel.traces.sampler` diatur ke nama sampler Anda
Kesalahan sampler tidak ditemukan saat startup	Ketidaksesuaian nama	Pastikan `getName()` dalam penyedia mengembalikan nama yang sama dengan yang digunakan dalam parameter startup
JAR ekstensi tidak dimuat	Path salah	Verifikasi path dalam `OTEL_JAVAAGENT_EXTENSIONS` atau `-Dotel.javaagent.extensions` mengarah ke file JAR yang benar
Span yang salah difilter	Kesalahan logika aturan filter	Tinjau kondisi dalam `shouldSample` dan pastikan nama span serta nilai atribut sesuai dengan ekspektasi Anda