サンプリングオーバーライド - Azure Monitor Application Insights for Java

2025-04-23

注

サンプリングオーバーライド機能の一般提供は 3.5.0 以降です。

サンプリングオーバーライドを使用すると、既定のサンプリング率をオーバーライドできます。次に例を示します。

ノイズの多い正常性チェックでは、サンプリング率を 0 (または何らかの小さい値) に設定します。
ノイズの多い依存関係呼び出しでは、サンプリング率を 0 (または何らかの小さい値) に設定します。
重要な要求の種類 (/login など) では、既定のサンプリングが低く構成されている場合でも、サンプリング率を 100 に設定します。

用語

サンプリングオーバーライドについて学習する前に、"スパン" という用語を理解しておく必要があります。スパンは、次を表す一般的な用語です。

リクエストが着信しています。
送信依存関係 (別のサービスへのリモート呼び出しなど)。
プロセス内の依存関係 (サービスのサブコンポーネントによって実行される操作など)。

サンプリングオーバーライドに関しては、これらのスパンコンポーネントが重要です。

属性

スパン属性は、指定された要求または依存関係の標準とカスタムの両方のプロパティを表します。

作業の開始

開始するには、applicationinsights.json という名前の構成ファイルを作成します。これを、applicationinsights-agent-*.jar と同じディレクトリに保存します。次に示すテンプレートを使用します。

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10,
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 0
      },
      {
        "telemetryType": "request",
        "attributes": [
          ...
        ],
        "percentage": 100
      }
    ]
  }
}

しくみ

telemetryType (Application Insights 3.4.0 では telemetryKind) は、request、dependency、trace (ログ)、または exception のいずれかである必要があります。

スパンが開始されると、そのスパンの種類とその時点で存在する属性が使用されて、サンプリングオーバーライドが一致するかどうかがチェックされます。

マッチは strict か regexp です。正規表現の一致は、属性値全体に対して実行されます。そのため、その中のどこかに abc が含まれる値に一致することが望まれる場合、.*abc.* を使用する必要があります。 1 つのサンプリングオーバーライドに複数の属性条件を指定できます。その場合、そのすべてが一致対象のサンプリングオーバーライドに一致している必要があります。

いずれかのサンプリングオーバーライドが一致する場合は、そのサンプリング率を使用してスパンをサンプリングするかどうかを決定します。

一致する最初のサンプリングオーバーライドのみが使用されます。

サンプリングオーバーライドが一致しない場合:

そのスパンがトレースの最初のスパンである場合は、最上位のサンプリング構成が使用されます。
そのスパンがトレースの最初のスパンでない場合は、親のサンプリングの決定が使用されます。

サンプリングに使用できるスパン属性

OpenTelemetry スパン属性は、 OpenTelemetry セマンティック規則に基づいて自動収集されます。

プログラムでスパン属性を追加し、サンプリングに使用することもできます。

注

アプリケーションの Application Insights Java によってキャプチャされた属性の正確なセットを確認するには、自己診断レベルを debug に設定し、テキスト "exporting span" で始まるデバッグメッセージを探します。

注

サンプリングに使用できるのはスパンの開始時に設定された属性のみであり、後でキャプチャされる http.response.status_code や要求期間などの属性は、OpenTelemetry Java 拡張機能を使用してフィルター処理できます。要求の期間に基づいてスパンをフィルター処理する拡張機能のサンプルを次に示します。

注

テレメトリプロセッサで追加された属性は、サンプリングには使用できません。

使用例

正常性チェックのテレメトリ収集を抑制する

この例では、/health-checks へのすべての要求に対するテレメトリの収集が抑制されています。

この例では、通常は /health-checks で収集されるダウンストリームのスパン (依存関係) の収集も抑制されています。

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/health-check",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

ノイズの多い依存関係呼び出しのテレメトリ収集を抑制する

この例では、すべての GET my-noisy-key redis 呼び出しに対するテレメトリの収集が抑制されています。

{
  "connectionString": "...",
  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "db.system",
            "value": "redis",
            "matchType": "strict"
          },
          {
            "key": "db.statement",
            "value": "GET my-noisy-key",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }
}

重要な要求の種類のテレメトリを 100% 収集する

この例では、/login のテレメトリが 100% 収集されます。

ダウンストリームのスパン（依存関係）は、親のサンプリング決定を尊重するため（そのダウンストリームスパンに対するサンプリングオーバーライドがない限り）、すべての '/login' リクエストについても収集されます。

{
  "connectionString": "...",
  "sampling": {
    "percentage": 10
  },
  "sampling": {
    "overrides": [
      {
        "telemetryType": "request",
        "attributes": [
          {
            "key": "url.path",
            "value": "/login",
            "matchType": "strict"
          }
        ],
        "percentage": 100
      }
    ]
  }
}

SQL 依存関係呼び出しを抑制するためにスパン属性を公開する

この例では、ノイズの多い SQL 呼び出しを抑制する使用可能な属性の検索について段階的に説明します。次のクエリは、過去 30 日間のさまざまな SQL 呼び出しと関連するレコード数を示しています。

dependencies
| where timestamp > ago(30d)
| where name == 'SQL: DB Query'
| summarize count() by name, operation_Name, data
| sort by count_ desc

SQL: DB Query    POST /Order             DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    36712549    
SQL: DB Query    POST /Receipt           DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    2220248    
SQL: DB Query    POST /CheckOutForm      DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    554074    
SQL: DB Query    GET /ClientInfo         DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    37064

結果から、すべての操作が data フィールド ( DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;) で同じ値を共有していることを確認できます。これらのすべてのレコードに共通点があるため、サンプリングオーバーライドの候補に適しています。

自己診断をデバッグに設定すると、次のログエントリが出力に表示されるようになります。

2023-10-26 15:48:25.407-04:00 DEBUG c.m.a.a.i.exporter.AgentSpanExporter - exporting span: SpanData{spanContext=ImmutableSpanContext...

これらのログの関心領域は "attributes" セクションです。

{
  "attributes": {
    "data": {
      "thread.name": "DefaultDatabaseBroadcastTransport: MessageReader thread",
      "thread.id": 96,
      "db.connection_string": "apache:",
      "db.statement": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
      "db.system": "other_sql",
      "applicationinsights.internal.item_count": 1
    }
  }
}

その出力を使用して、ノイズの多い SQL 呼び出しをフィルター処理する次の例のようなサンプリングオーバーライドを構成できます。

{
  "connectionString": "...",
  "preview": {
    "sampling": {
      "overrides": [
        {
          "telemetryType": "dependency",
          "attributes": [
            {
              "key": "db.statement",
              "value": "DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;",
              "matchType": "strict"
            }
          ],
          "percentage": 0
        }
      ]
    }
  }
}

変更が適用されると、次のクエリを使用して、これらの依存関係が Application Insights に最後に取り込まれた時刻を確認できます。

dependencies
| where timestamp > ago(30d)
| where data contains 'DECLARE @MyVar'
| summarize max(timestamp) by data
| sort by max_timestamp desc

DECLARE @MyVar varbinary(20); SET @MyVar = CONVERT(VARBINARY(20), 'Hello World');SET CONTEXT_INFO @MyVar;    11/13/2023 8:52:41 PM

ログのテレメトリ収集を抑制する

SL4J では、ログ属性を追加できます。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

public class MdcClass {

  private static final Logger logger = LoggerFactory.getLogger(MdcClass.class);

  void method {
	
    MDC.put("key", "value");
    try {
       logger.info(...); // Application log to remove
    finally {
       MDC.remove("key"); // In a finally block in case an exception happens with logger.info
    }
	
  }
  
}

その後、追加された属性を持つログを削除できます。

{
  "sampling": {
    "overrides": [
      {
        "telemetryType": "trace",
        "percentage": 0,
        "attributes": [
          {
            "key": "key",
            "value": "value",
            "matchType": "strict"
          }
        ]
      }
    ]
  }
}

Java メソッドのテレメトリ収集を抑制する

ここでは、Java メソッドにスパンを追加し、サンプリングオーバーライドを使用してこのスパンを削除します。

まず opentelemetry-instrumentation-annotations 依存関係を追加します。

    <dependency>
      <groupId>io.opentelemetry.instrumentation</groupId>
      <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    </dependency>

これで、SQL 要求を実行する Java メソッドに WithSpan 注釈を追加できるようになりました。

package org.springframework.samples.petclinic.vet;

@Controller
class VetController {

	private final VetRepository vetRepository;

	public VetController(VetRepository vetRepository) {
		this.vetRepository = vetRepository;
	}

	@GetMapping("/vets.html")
	public String showVetList(@RequestParam(defaultValue = "1") int page, Model model) {
		Vets vets = new Vets();
		Page<Vet> paginated = findPaginated(page);
		vets.getVetList().addAll(paginated.toList());
		return addPaginationModel(page, paginated, model);
	}

	@WithSpan
	private Page<Vet> findPaginated(int page) {
		int pageSize = 5;
		Pageable pageable = PageRequest.of(page - 1, pageSize);
		return vetRepository.findAll(pageable);  // Execution of SQL requests
	}

次のサンプリングオーバーライド構成を使用すると、WithSpan 注釈によって追加されたスパンを削除できます。

  "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.function",
            "value": "findPaginated",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

属性値は Java メソッドの名前です。

この構成では、 findPaginated メソッドから作成されたすべてのテレメトリデータが削除されます。 sql 依存関係は、 findPaginated メソッドからの SQL 実行には作成されません。

次の構成では、VetController注釈を持つWithSpan クラスのメソッドから出力されたすべてのテレメトリデータが削除されます。

 "sampling": {
    "overrides": [
      {
        "telemetryType": "dependency",
        "attributes": [
          {
            "key": "code.namespace",
            "value": "org.springframework.samples.petclinic.vet.VetController",
            "matchType": "strict"
          }
        ],
        "percentage": 0
      }
    ]
  }

トラブルシューティング

regexp を使用していて、サンプリングオーバーライドが機能しない場合は、.* 正規表現を試してください。サンプリングが機能するようになった場合は、最初の正規表現に問題があることを意味します。こちらの正規表現のドキュメントを確認してください。

.* で機能しない場合は、application-insights.json file に構文の問題が存在している可能性があります。 Application Insights のログを確認し、警告メッセージが表示されているかどうかを確認してください。

よく寄せられる質問

サンプリングオーバーライドを有効にするには、手動インストルメンテーションを使用する必要がありますか?

いいえ、サンプリングオーバーライドは一般提供 (GA) となり、自動計装と手動インストルメンテーションの両方で使用できます。

Azure App Service で自動インスツルメンテーションを使用する場合、サンプリングオーバーライドをどのように構成すればよいですか？

自動計装を使用する場合は、Azure ポータルで applicationinsights.json ファイルを更新します。

サンプリングオーバーライド用に Application Insights エージェントファイルを手動でアップロードする必要がありますか?

自動計装の場合、エージェントの手動アップロードは必要ありません。ただし、手動インストルメンテーションの場合でも、Application Insights エージェント JAR ファイルと構成ファイルをデプロイパッケージに含める必要があります。

手動インストルメンテーションのコンテキストにおける "ローカル開発" と "アプリケーションサーバー" の違いは何ですか?

ローカル開発とは、開発者のマシンや Azure Cloud Shell インスタンスなど、アプリがビルドまたはテストされている環境を指します。アプリケーションサーバーとは、Azure App Service 環境の Tomcat 11 など、アプリケーションを実行している Web サーバーを指します。手動インストルメンテーションを使用する場合は、エージェント JAR ファイルがアプリケーションサーバーに正しく配置されていることを確認する必要があります。

Java ランタイム (Tomcat 11 など) で Azure App Service を使用している場合、サンプリングオーバーライドを構成するにはどうすればよいですか?

自動インストルメンテーションの場合は、Azure portal を使用してサンプリングオーバーライドを構成できます。手動インストルメンテーションを使用する場合は、Application Insights エージェント JAR を適切なディレクトリに配置し、目的のサンプリング設定に applicationinsights.json ファイルを含める必要があります。

次の方法で共有

サンプリング オーバーライド - Azure Monitor Application Insights for Java

用語