全部产品
Search

搜索本产品

    Managed Service for OpenTelemetry：Gunakan Managed Service for OpenTelemetry untuk memfilter rentang tertentu

    文档中心

    Managed Service for OpenTelemetry：Gunakan Managed Service for OpenTelemetry untuk memfilter rentang tertentu

    更新时间：Jul 02, 2025

    Topik ini menjelaskan cara menggunakan Managed Service for OpenTelemetry untuk memfilter rentang tertentu pada aplikasi Java dan Node.js.

    Aplikasi Java

    Anda dapat menggunakan pengambil sampel Managed Service for OpenTelemetry untuk memfilter rentang. Jika Anda tidak ingin memodifikasi kode aplikasi atau menggunakan Agen Java Managed Service for OpenTelemetry untuk melaporkan data aplikasi secara otomatis, Anda dapat membuat ekstensi untuk agen tersebut. Dengan menulis pengambil sampel OpenTelemetry kustom dan mendefinisikan aturan filter, Anda dapat memfilter rentang tertentu tanpa perlu memodifikasi kode aplikasi. Untuk informasi lebih lanjut, lihat Metode 1. Jika Anda menggunakan SDK Java Managed Service for OpenTelemetry untuk melaporkan data aplikasi secara manual, Anda dapat menulis pengambil sampel kustom dalam kode aplikasi. Untuk informasi lebih lanjut, lihat Metode 2.

    Metode 1: Buat ekstensi untuk Agen Java Managed Service for OpenTelemetry

    Prasyarat

    Aplikasi diinstrumen secara otomatis menggunakan OpenTelemetry Java Agent. Untuk informasi lebih lanjut, lihat Gunakan OpenTelemetry untuk Melaporkan Data Jejak Aplikasi Java.

    1. Buat sebuah proyek.

      Buat sebuah proyek Maven. Proyek ini digunakan untuk membuat dan membangun ekstensi.

    2. Tambahkan dependensi ke file pom.xml.

      Penting

      Untuk memastikan bahwa dependensi kompatibel, pastikan semua dependensi terkait Managed Service for OpenTelemetry memiliki versi yang sama dengan versi OpenTelemetry Java Agent yang Anda gunakan.

       <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 nilai field scope menjadi 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. Buat kelas SpanFilterSampler. Anda juga dapat menggunakan nama kelas kustom.

      Kelas ini harus mengimplementasikan antarmuka io.opentelemetry.sdk.trace.samplers.Sampler dan metode shouldSample serta getDescription.

      • shouldSample

        Anda dapat mendefinisikan aturan filter kustom dalam metode ini. Untuk rentang yang ingin Anda filter, SamplingResult.create(SamplingDecision.DROP) dikembalikan. Untuk rentang yang ingin Anda pertahankan dan laporkan, SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) dikembalikan.

      • getDescription

        Metode ini mengembalikan nama pengambil sampel kustom.

      Dalam contoh berikut, pengambil sampel SpanFilterSampler memfilter rentang dengan nama spanName1 atau spanName2 dan rentang dengan attributes.http.target adalah /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 {
 /*
 * Filter rentang dengan nama dalam EXCLUDED_SPAN_NAMES.
 */
 private static List<String> EXCLUDED_SPAN_NAMES = Collections.unmodifiableList(
 Arrays.asList("spanName1", "spanName2")
 );
 
 /*
 * Filter rentang dengan attributes.http.target dalam EXCLUDED_HTTP_REQUEST_TARGETS.
 */
 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)) { // Filter rentang berdasarkan aturan.
 return SamplingResult.create(SamplingDecision.DROP);
 } else {
 return SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE);
 }
 }
 
 @Override
 public String getDescription() {
 return "SpanFilterSampler"; // Anda dapat mengganti SpanFilterSampler dengan nama kustom.
 }
 }

    4. Buat kelas SpanFilterSamplerProvider. Anda juga dapat menggunakan nama kelas kustom.

      Kelas ini harus mengimplementasikan antarmuka io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider dan metode createSampler serta getName.

      • createSampler

        Metode ini membuat dan mengembalikan instance pengambil sampel kustom.

      • getName

        Metode ini mengembalikan nama pengambil sampel kustom. OpenTelemetry Java Agent menemukan pengambil sampel ini berdasarkan nama.

       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"; // Anda dapat mengganti SpanFilterSampler dengan nama kustom.
 }
 }

    5. Bangun pengambil sampel.

      Kemas proyek menjadi file Java archive (JAR) dan simpan file JAR di direktori target.

      mvn clean package

    6. Muat ekstensi OpenTelemetry Java Agent saat aplikasi dimulai.

      • Metode 1: Tambahkan parameter otel.traces.sampler ke parameter VM asli.

        -Dotel.traces.sampler=<your-sampler-name> // Ganti <your-sampler-name> dengan nama pengambil sampel kustom, yaitu nilai balik dari metode getName.

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

      • Metode 2: Konfigurasikan variabel lingkungan OTEL_TRACES_SAMPLER.

        export OTEL_TRACES_SAMPLER="<your-sampler-name>" // Ganti <your-sampler-name> dengan nama pengambil sampel kustom, yaitu nilai balik dari metode getName.

        Tampilkan Contoh Perintah Startup Lengkap

         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

    Metode 2: Gunakan SDK Java Managed Service for OpenTelemetry

    Prasyarat

    Aplikasi diinstrumen secara manual menggunakan SDK Java Managed Service for OpenTelemetry. Untuk informasi lebih lanjut, lihat Gunakan OpenTelemetry untuk Melaporkan Data Jejak Aplikasi Java.

    1. Buat kelas pengambil sampel kustom dalam kode aplikasi Anda.

      Kelas ini harus mengimplementasikan antarmuka io.opentelemetry.sdk.trace.samplers.Sampler dan metode shouldSample serta getDescription.

      • shouldSample

        Anda dapat mendefinisikan aturan filter kustom dalam metode ini. Untuk rentang yang ingin Anda filter, SamplingResult.create(SamplingDecision.DROP) dikembalikan. Untuk rentang yang ingin Anda pertahankan dan laporkan, SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) dikembalikan.

      • getDescription

        Metode ini mengembalikan nama pengambil sampel kustom.

      Dalam contoh berikut, pengambil sampel SpanFilterSampler memfilter rentang dengan nama spanName1 atau spanName2 dan rentang dengan attributes.http.target adalah /api/checkHealth atau /health/check.

       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 {
 /*
 * Filter rentang dengan nama dalam EXCLUDED_SPAN_NAMES.
 */
 private static List<String> EXCLUDED_SPAN_NAMES = Collections.unmodifiableList(
 Arrays.asList("spanName1", "spanName2")
 );
 
 /*
 * Filter rentang dengan attributes.http.target dalam EXCLUDED_HTTP_REQUEST_TARGETS.
 */
 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)) { // Filter rentang berdasarkan aturan.
 return SamplingResult.create(SamplingDecision.DROP);
 } else {
 return SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE);
 }
 }
 
 @Override
 public String getDescription() {
 return "SpanFilterSampler"; // Anda dapat mengganti SpanFilterSampler dengan nama kustom.
 }
 }

    2. Atur pengambil sampel kustom saat Anda membuat instance SdkTracerProvider.

      Saat Anda membuat instance SdkTracerProvider, panggil metode setSampler(new SpanFilterSampler()) untuk mengatur pengambil sampel kustom.

       ...
 
 
 SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
 . setSampler(new MySampler()) // Tambahkan baris ini.
 .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
 .setEndpoint("<endpoint>")
 .addHeader("Authentication", "<token>")
 .build()).build())
 .setResource(resource)
 .build();
 
 
 ...

    3. Mulai aplikasi.

    Aplikasi Node.js

    Demo: opentelemetry-nodejs-demo.

    Prasyarat

    Aplikasi diinstrumen menggunakan API Managed Service for OpenTelemetry untuk JavaScript. Untuk informasi lebih lanjut, lihat Gunakan Managed Service for OpenTelemetry untuk Mengirimkan Data Jejak Aplikasi Node.js.

    Metode 1: Filter rentang saat rentang dibuat

    1. Konfigurasikan parameter ignoreIncomingRequestHook saat Anda membuat HttpInstrumentation.

      Saat Anda membuat HttpInstrumentation, Anda dapat mengonfigurasi parameter HttpInstrumentationConfig, yang mencakup parameter ignoreIncomingRequestHook. Parameter ignoreIncomingRequestHook memungkinkan Anda menentukan metode kustom untuk menentukan apakah akan menginstrumen aplikasi sebelum permintaan diproses. Metode kustom hanya menentukan bahwa rentang tidak dibuat. Permintaan diproses seperti yang diharapkan.

      Dalam contoh berikut, permintaan dengan request.url /api/checkHealth diabaikan untuk instrumen.

       ...
 
 // Konten yang akan diganti.
 // registerInstrumentations({
 // tracerProvider: provider,
 // instrumentations: [new HttpInstrumentation(), ExpressInstrumentation],
 // });
 
 const httpInstrumentation = new HttpInstrumentation({
 
 // Tentukan metode kustom dalam parameter ignoreIncomingRequestHook.
 ignoreIncomingRequestHook: (request) => {
 // Abaikan permintaan dengan request.url /api/checkHealth.
 if (request.url === '/api/checkHealth') {
 return true;
 }
 return false;
 },
 
 });
 
 registerInstrumentations({
 tracerProvider: provider,
 instrumentations: [httpInstrumentation, ExpressInstrumentation],
 });
 
 ...

    2. Mulai aplikasi.

    Metode 2: Filter rentang saat rentang dilaporkan

    1. Buat kelas pengambil sampel kustom.

      Buat kelas pengambil sampel kustom yang mengimplementasikan antarmuka Sampler. Antarmuka ini mendefinisikan aturan sampling. Contoh:

       const opentelemetry = require('@opentelemetry/api');
 
 class SpanFilterSampler {
 shouldSample(spanContext, parentContext) {
 // Implementasikan logika sampling kustom Anda di sini.
 }
 }

    2. Atur pengambil sampel kustom saat Anda membuat instance NodeTracerProvider.

       ...
 const provider = new NodeTracerProvider({
 sampler: new SpanFilterSampler(), // Tambahkan baris kode ini untuk mengatur pengambil sampel kustom.
 resource: new Resource({
 [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(), // nama host Anda
 [SemanticResourceAttributes.SERVICE_NAME]: "<your-service-name>",
 }),
 });
 ...