Application Real-Time Monitoring Service:カスタムサンプラーによる特定スパンのフィルタリング

前提条件

開始する前に、以下を確認してください：

• OpenTelemetry Java エージェントで自動的にインストルメンテーションされたアプリケーション。セットアップ手順については、「Java アプリケーションのトレースデータを OpenTelemetry を使用して送信する」をご参照ください。

• 拡張 JAR をビルドするための Apache Maven のインストール

ステップ 1： Maven プロジェクトの作成

エージェント拡張をビルドするための新しい Maven プロジェクトを作成します。

ステップ 2： 依存関係の追加

次の依存関係を pom.xml ファイルに追加します。

<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>
  <!--スコープを 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： サンプラーの実装

io.opentelemetry.sdk.trace.samplers.Sampler インターフェイスを実装するクラスを作成します。shouldSample メソッドでフィルタリングルールを定義し、getDescription からサンプラー名を返します。

• shouldSample -- 各スパンを評価し、破棄するスパンには SamplingResult.create(SamplingDecision.DROP) を、保持するスパンには SamplingResult.create(SamplingDecision.RECORD_AND_SAMPLE) を返します。

• getDescription -- サンプラー名を返します。

次の例では、spanName1 または spanName2 という名前のスパン、および http.target 属性が /api/checkHealth または /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 {

    // ドロップするスパン名
    private static List<String> EXCLUDED_SPAN_NAMES = Collections.unmodifiableList(
        Arrays.asList("spanName1", "spanName2")
    );

    // ドロップする HTTP ターゲットパス
    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： サンプラープロバイダーの実装

io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSamplerProvider を実装するクラスを作成します。このプロバイダーは、Java エージェントの自動構成メカニズムにサンプラーを登録します。

• createSampler -- サンプラーのインスタンスを返します。

• getName -- サンプラー名を返します。Java エージェントはこの名前を使用してサンプラーを特定します。

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： 拡張 JAR のビルド

プロジェクトを JAR ファイルにパッケージ化します：

mvn clean package

JAR ファイルは target ディレクトリに生成されます。

ステップ 6： 起動時に拡張をロード

アプリケーションの起動時にカスタムサンプラーを指定します。JVM システムプロパティまたは環境変数のいずれかを使用します。

オプション A： JVM システムプロパティ

-Dotel.traces.sampler=<your-sampler-name> を JVM 起動パラメーターに追加します。<your-sampler-name> を getName メソッドから返される値に置き換えます。

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

オプション B： 環境変数

OTEL_TRACES_SAMPLER 環境変数をサンプラー名に設定します：

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

次のプレースホルダーを実際の値に置き換えてください：

前提条件

開始する前に、以下を確認してください：

• OpenTelemetry SDK for Java で手動でインストルメンテーションされたアプリケーション。セットアップ手順については、「Java アプリケーションのトレースデータを OpenTelemetry を使用して送信する」をご参照ください。

ステップ 1： サンプラークラスの作成

SpanFilterSampler クラスを作成し、Sampler インターフェイスを実装します。実装は、「ステップ 3： サンプラーの実装」のエージェント拡張サンプラーと同じです。ドロップしたいスパンに合わせて EXCLUDED_SPAN_NAMES および EXCLUDED_HTTP_REQUEST_TARGETS リストを調整します。

ステップ 2： SdkTracerProvider へのサンプラーの登録

SdkTracerProvider インスタンスをビルドする際に .setSampler(new SpanFilterSampler()) を呼び出します：

SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
    .setSampler(new SpanFilterSampler())  // カスタムサンプラーの登録
    .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
        .setEndpoint("<endpoint>")
        .addHeader("Authentication", "<token>")
        .build()).build())
    .setResource(resource)
    .build();

ステップ 3： アプリケーションの再起動

アプリケーションを再起動します。サンプラーはすべての新しいスパンを評価し、フィルターのルールに一致するものをドロップします。

ステップ 1： サンプラークラスの作成

Sampler インターフェイスを実装するクラスを作成します。shouldSample でフィルタリングロジックを定義します：

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

class SpanFilterSampler {
  shouldSample(spanContext, parentContext) {
    // ここにカスタムサンプリングロジックを実装します。
  }
}

ステップ 2： NodeTracerProvider へのサンプラーの登録

サンプラーインスタンスを NodeTracerProvider コンストラクターに渡します：

const provider = new NodeTracerProvider({
  sampler: new SpanFilterSampler(),  // カスタムサンプラーの登録
  resource: new Resource({
    [SemanticResourceAttributes.HOST_NAME]: require("os").hostname(),
    [SemanticResourceAttributes.SERVICE_NAME]: "<your-service-name>",
  }),
});

<your-service-name> を、my-node-app のように、ご利用のサービス名に置き換えます。

プロバイダーの構成を更新した後、アプリケーションを起動します。