JavaScript 用 Azure Monitor OpenTelemetry

作業の開始

パッケージをインストールする

npm install @azure/monitor-opentelemetry

現在サポートされている環境

• Node.js の LTS バージョン

• OpenTelemetry でサポートされているランタイム

警告： この SDK は、Node.js 環境でのみ機能します。 Web およびブラウザーのシナリオには、Application Insights JavaScript SDK を使用してください。

詳細については、Microsoft のサポート ポリシーを参照してください。

前提条件

• Azure サブスクリプション
• Application Insights ワークスペース

Azure Monitor OpenTelemetry クライアントを有効にする

大事な：useAzureMonitor は、他のものをインポートする 前に 呼び出す必要があります。 他のライブラリが最初にインポートされると、テレメトリが失われる可能性があります。

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
}
useAzureMonitor(options);

• 接続文字列は、環境変数 APPLICATIONINSIGHTS_CONNECTION_STRINGを使用して設定できます

構成

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";

const resource = new Resource({ "testAttribute": "testValue" });
const options: AzureMonitorOpenTelemetryOptions = {
    azureMonitorExporterOptions: {
        // Offline storage
        storageDirectory: "c://azureMonitor",
        // Automatic retries
        disableOfflineStorage: false,
        // Application Insights Connection String
        connectionString:
              process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
    },
    samplingRatio: 1,
    instrumentationOptions: {
        // Instrumentations generating traces
        azureSdk: { enabled: true },
        http: { enabled: true },
        mongoDb: { enabled: true },
        mySql: { enabled: true },
        postgreSql: { enabled: true },
        redis: { enabled: true },
        redis4: { enabled: true },
        // Instrumentations generating logs
        bunyan: { enabled: true },
        winston: { enabled: true },
    },
    enableLiveMetrics: true,
    enableStandardMetrics: true,
    browserSdkLoaderOptions: {
        enabled: false,
        connectionString: "",
    },
    resource: resource,
    logRecordProcessors: [],
    spanProcessors: []
};

useAzureMonitor(options);

オプションは、パッケージ インストール フォルダーのルート フォルダー (例: node_modules/@azure/monitor-opentelemetry) の@azure/monitor-opentelemetry下にある構成ファイルapplicationinsights.jsonを使用して設定できます。 これらの構成値は、すべての AzureMonitorOpenTelemetryClient インスタンスに適用されます。

{
    "samplingRatio": 0.8,
    "enableStandardMetrics": true,
    "enableLiveMetrics": true,
    "instrumentationOptions":{
        "azureSdk": {
            "enabled": false
        }
    },
    ...
}

カスタム JSON ファイルは、環境変数を使用して APPLICATIONINSIGHTS_CONFIGURATION_FILE 指定できます。

process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE = "C:/applicationinsights/config/customConfig.json"

// Application Insights SDK setup....

インストルメンテーション ライブラリ

Azure Monitor OpenTelemetry の一部として、次の OpenTelemetry インストルメンテーション ライブラリが含まれています。

警告： インストルメンテーション ライブラリは、試験的な OpenTelemetry 仕様に基づいています。 Microsoft のプレビュー サポートのコミットメントは、次のライブラリが Azure Monitor Application Insights にデータを出力することを保証することですが、互換性を破る変更や試験的なマッピングによって一部のデータ要素がブロックされる可能性があります。

分散トレース

• HTTP/HTTPS
• MongoDB
• MySQL
• Postgres
• Redis
• Redis-4
• Azure SDK

メトリック

• HTTP/HTTPS

ログ

• Bunyan

• Winston

その他の OpenTelemetry インストルメンテーションについては、 こちらを 参照してください。また、AzureMonitorOpenTelemetryClient の TracerProvider を使用して追加できます。

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, trace } from "@opentelemetry/api";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
const instrumentations = [
   new ExpressInstrumentation(),
];
registerInstrumentations({
   tracerProvider:  trace.getTracerProvider(),
   meterProvider: metrics.getMeterProvider(),
   instrumentations: instrumentations,
});  

Application Insights Browser SDK ローダー

Application Insights Browser SDK Loader を使用すると、次の条件に該当する場合に、ノード サーバーの応答に Web SDK を挿入できます。

• 応答に状態コード 200 が含まれている。
• 応答メソッドが GET である。
• サーバー応答には html ヘッダーがあります Conent-Type 。
• サーバーの resonse には 、 タグと タグの両方が含まれています。
• 応答に現在およびバックアップの Web インストルメンテーション CDN エンドポイントが含まれていない。 (現在およびバックアップの Web インストルメンテーション CDN エンドポイントはここにあります)

クラウド ロール名とクラウド ロール インスタンスを設定する

OpenTelemetry リソース属性を使用して、クラウド ロール名とクラウド ロール インスタンスを設定できます。

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SemanticResourceAttributes.SERVICE_INSTANCE_ID] = "my-instance";

const options: AzureMonitorOpenTelemetryOptions = { resource : customResource }
useAzureMonitor(options);

リソースの標準属性については、「リソース セマンティック規則」を参照してください。

テレメトリの変更

このセクションでは、テレメトリを変更する方法について説明します。

スパン属性を追加する

スパン属性を追加するには、次の 2 つの方法のいずれかを使用します。

• インストルメンテーション ライブラリで提供されるオプションを使用する。
• カスタム スパン プロセッサを追加する。

これらの属性には、テレメトリへのカスタム プロパティの追加が含まれる可能性があります。

ヒント： インストルメンテーション ライブラリによって提供されるオプションを使用できる場合、コンテキスト全体を使用できるという利点があります。 その結果、ユーザーは、追加する属性を選択したり、フィルター処理したりできます。 たとえば、HttpClient インストルメンテーション ライブラリの enrich オプションを使用すると、ユーザーは httpRequestMessage 自体にアクセスできます。 そこからは何でも選択して、属性として保存できます。

トレースにカスタム プロパティを追加する

スパンに追加した属性は、カスタム プロパティとしてエクスポートされます。

カスタム プロセッサの使用:

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";


class SpanEnrichingProcessor implements SpanProcessor{
  forceFlush(): Promise<void>{
    return Promise.resolve();
  }
  shutdown(): Promise<void>{
    return Promise.resolve();
  }
  onStart(_span: Span): void{}
  onEnd(span: ReadableSpan){
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
    // Add the SpanEnrichingProcessor
    spanProcessors: [new SpanEnrichingProcessor()] 
}
useAzureMonitor(options);

テレメトリのフィルター処理

テレメトリがアプリケーションから離れる前に、次の方法を使用してテレメトリをフィルター処理できます。

1. 多くの HTTP インストルメンテーション ライブラリによって提供される URL オプションを除外します。

   次の例では、HTTP/HTTPS インストルメンテーション ライブラリを使用して、特定の URL を追跡から除外する方法を示しています。

   import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
   import { IncomingMessage } from "http";
   import { RequestOptions } from "https";
   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   
   const httpInstrumentationConfig: HttpInstrumentationConfig = {
       enabled: true,
       ignoreIncomingRequestHook: (request: IncomingMessage) => {
           // Ignore OPTIONS incoming requests
           if (request.method === 'OPTIONS') {
               return true;
           }
           return false;
       },
       ignoreOutgoingRequestHook: (options: RequestOptions) => {
           // Ignore outgoing requests with /test path
           if (options.path === '/test') {
               return true;
           }
           return false;
       }
   };
   const options : AzureMonitorOpenTelemetryOptions = {
       instrumentationOptions: {
       http:  httpInstrumentationConfig,
       }
   };
   useAzureMonitor(options);
   

2. カスタム プロセッサを使用します。 カスタム スパン プロセッサを使用して、特定のスパンをエクスポートから除外できます。 スパンをエクスポートされないようにマークするには、TraceFlag を DEFAULT に設定します。 カスタム プロパティの追加の例を使用しますが、次のコード行を置き換えます。

   ...
   import { SpanKind, TraceFlags } from "@opentelemetry/api";
   import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
   
   class SpanEnrichingProcessor implements SpanProcessor {
       ...
   
       onEnd(span: ReadableSpan) {
           if(span.kind == SpanKind.INTERNAL){
               span.spanContext().traceFlags = TraceFlags.NONE;
           }
       }
   }
   

カスタムのテレメトリ

このセクションでは、アプリケーションからカスタム テレメトリを収集する方法について説明します。

カスタム メトリックを追加する

インストルメンテーション ライブラリによって収集されるメトリック以外のメトリックを収集することもできます。

OpenTelemetry API には、さまざまなメトリック シナリオに対応する 6 つのメトリック "インストルメント" が用意されており、メトリック エクスプローラーでメトリックを視覚化する場合は、適切な "集計の種類" を選択する必要があります。 この要件は、OpenTelemetry Metric API を使用してメトリックを送信する場合と、インストルメンテーション ライブラリを使用する場合に当てはまります。

次の表は、OpenTelemetry メトリック インストルメントごとに推奨される集計の種類を示しています。

注意： 通常、テーブルに表示される集計型を超える集計の種類は意味がありません。

「OpenTelemetry の仕様」では、インストルメントについて説明し、それぞれを使用する場合の例を示します。

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { ObservableResult, metrics } from "@opentelemetry/api";

useAzureMonitor();
const meter =  metrics.getMeter("testMeter");

let histogram = meter.createHistogram("histogram");
let counter = meter.createCounter("counter");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
    let randomNumber = Math.floor(Math.random() * 100);
    observableResult.observe(randomNumber, {"testKey": "testValue"});
});

histogram.record(1, { "testKey": "testValue" });
histogram.record(30, { "testKey": "testValue2" });
histogram.record(100, { "testKey2": "testValue" });

counter.add(1, { "testKey": "testValue" });
counter.add(5, { "testKey2": "testValue" });
counter.add(3, { "testKey": "testValue2" });

カスタム例外の追加

インストルメンテーション ライブラリを選択すると、Application Insights の例外が自動的にサポートされます。 ただし、インストルメント化ライブラリで報告される例外以外の例外を手動で報告することもできます。 たとえば、コードによってキャッチされた例外は通常報告 されないため 、それらを報告して、エラー ブレードやエンドツーエンドのトランザクション ビューなどの関連エクスペリエンスで注意を引くことができます。

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace } from "@opentelemetry/api";

useAzureMonitor();
const tracer =  trace.getTracer("testMeter");

let span = tracer.startSpan("hello");
try{
    throw new Error("Test Error");
}
catch(error){
    span.recordException(error);
}

トラブルシューティング

自己診断

Azure Monitor OpenTelemetry では、内部ログに OpenTelemetry API ロガーが使用されます。 これを有効にするには、次のコードを使用します。

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { DiagLogLevel } from "@opentelemetry/api";

process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL 環境の変動を使用して目的のログ レベルを設定し、次の値をサポートできます: NONE、 ERROR、 WARN、 INFO、 DEBUG、 VERBOSE および ALL。

ログは環境変数を使用してAPPLICATIONINSIGHTS_LOG_DESTINATIONローカル ファイルに格納できます。サポートされている値 は file と file+consoleです。という名前applicationinsights.logのファイルは、*nix と USERDIR/AppData/Local/Temp Windows のすべてのログを含め、/tmp既定で tmp フォルダーに生成されます。 ログ ディレクトリは、環境変数を使用して APPLICATIONINSIGHTS_LOGDIR 構成できます。

例

いくつかのチャンピオン シナリオの完全なサンプルについては、 フォルダーを samples/ 参照してください。

主要な概念

OpenTelemetry プロジェクトの詳細については、 OpenTelemetry の仕様を参照してください。

プラグイン レジストリ

使用しているライブラリに対してプラグインが既に作成されているかどうかを確認するには、OpenTelemetry レジストリをチェックしてください。

レジストリ内のライブラリができない場合は、 で opentelemetry-js-contrib新しいプラグイン要求を提案してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。