JavaScript 用 Azure Monitor OpenTelemetry

[アーティクル]
05/15/2024

作業の開始

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

npm install @azure/monitor-opentelemetry

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

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

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

前提条件

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);

プロパティ	説明	Default
azureMonitorExporterOptions	Azure Monitor OpenTelemetry Exporter の構成。詳細情報はこちら
samplingRatio	サンプリング率は [0,1] の範囲内の値を取る必要があります。1 は、すべてのデータがサンプリングされ、0 個のすべてのトレースデータがサンプリングされることを意味します。	1
instrumentationOptions	OpenTelemetry Instrumentations の構成を許可します。	{"http": { enabled: true },"azureSdk": { enabled: false },"mongoDb": { enabled: false },"mySql": { enabled: false },"postgreSql": { enabled: false },"redis": { enabled: false },"bunyan": { enabled: false }, "winston": { enabled: false }, "winston": { enabled: false: false } }
browserSdkLoaderOptions	Web インストルメンテーションの構成を許可します。	{ enabled: false, connectionString: "" }
resource	Opentelemetry リソース。詳細情報はこちら
samplingRatio	サンプリング率は [0,1] の範囲内の値を取る必要があります。1 は、すべてのデータがサンプリングされ、0 個のすべてのトレースデータがサンプリングされることを意味します。	1
enableLiveMetrics	ライブメトリックを有効または無効にします。	false
enableStandardMetrics	標準メトリックを有効または無効にします。	TRUE
logRecordProcessors	グローバルロガープロバイダーに登録するログレコードプロセッサの配列。
spanProcessors	グローバルトレーサープロバイダーに登録するスパンプロセッサの配列。

オプションは、パッケージインストールフォルダーのルートフォルダー (例: 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

ログ

その他の 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);

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

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

多くの 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);

カスタムプロセッサを使用します。カスタムスパンプロセッサを使用して、特定のスパンをエクスポートから除外できます。スパンをエクスポートされないようにマークするには、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 インストルメント	Azure Monitor の集計の種類
カウンタ	SUM
非同期カウンター	SUM
ヒストグラム	Average、Sum、Count (Python と Node.js のみ Max、Min)
非同期ゲージ	Average
UpDownCounter (Python と Node.js のみ)	SUM
非同期 UpDownCounter (Python と Node.js のみ)	SUM

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

「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新しいプラグイン要求を提案してください。

共同作成

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

インプレッション数

次の方法で共有

JavaScript 用 Azure Monitor OpenTelemetry

作業の開始

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

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

前提条件

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

構成

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

分散トレース

メトリック

ログ

Application Insights Browser SDK ローダー

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

テレメトリの変更

スパン属性を追加する

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

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

カスタムのテレメトリ

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

カスタム例外の追加

トラブルシューティング

自己診断

例

主要な概念

プラグインレジストリ

共同作成

フィードバック

その他のリソース

次の方法で共有

JavaScript 用 Azure Monitor OpenTelemetry

作業の開始

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

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

前提条件

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

構成

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

分散トレース

メトリック

ログ

Application Insights Browser SDK ローダー

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

テレメトリの変更

スパン属性を追加する

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

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

カスタムのテレメトリ

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

カスタム例外の追加

トラブルシューティング

自己診断

例

主要な概念

プラグイン レジストリ

共同作成

フィードバック

その他のリソース

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

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

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

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

プラグインレジストリ