適用於 JavaScript 的 Azure 監視器 OpenTelemetry

發行項
06/19/2024

開始

安裝套件

npm install @azure/monitor-opentelemetry

目前支持的環境

警告： 此 SDK 僅適用於 Node.js 環境。針對網頁和瀏覽器案例，請使用 Application Insights JavaScript SDK。

如需詳細資訊，請參閱我們的支持原則。

先決條件

啟用 Azure 監視器 OpenTelemetry 用戶端

重要事項：在您匯入任何其他專案之前，必須先呼叫。如果先匯入其他連結庫，可能會導致遙測遺失。

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

財產	描述	違約
azureMonitorExporterOptions	Azure 監視器 OpenTelemetry 匯出工具組態。在這裡詳細資訊
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 } }
browserSdkLoaderOptions	允許 Web 檢測的設定。	{ enabled： false， connectionString： “” }
資源	Opentelemetry 資源。在這裡詳細資訊
samplingRatio	取樣比例必須接受範圍 [0,1] 中的值，1 表示所有數據都會取樣，並將取樣 0 個追蹤數據。	1
enableLiveMetrics	啟用/停用即時計量。	真
enableStandardMetrics	啟用/停用標準計量。	真
logRecordProcessors	要向全域記錄提供者註冊的記錄記錄處理器陣列。
spanProcessors	要向全域追蹤提供者註冊之範圍處理器的陣列。

您可以使用元件設定選項，applicationinsights.json 位於 @azure/monitor-opentelemetry 套件安裝資料夾的根資料夾下，例如：node_modules/@azure/monitor-opentelemetry。這些組態值會套用至所有 AzureMonitorOpenTelemetryClient 實例。

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

您可以使用 APPLICATIONINSIGHTS_CONFIGURATION_FILE 環境變數來提供自訂 JSON 檔案。

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

// Application Insights SDK setup....

檢測連結庫

下列 OpenTelemetry Instrumentation 連結庫包含在 Azure 監視器 OpenTelemetry 中。

警告： 檢測連結庫是以實驗性的 OpenTelemetry 規格為基礎。 Microsoft的預覽支持承諾是確保下列連結庫將數據發出至 Azure 監視器 Application Insights，但可能會封鎖某些數據元素的重大變更或實驗對應。

分散式追蹤

指標

HTTP/HTTPS

原木

這裡提供其他 OpenTelemetry Instrumentations ，而且可以使用 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 載入器可讓您在下列條件成立時，將 Web SDK 插入節點伺服器回應中：

回應具有狀態代碼 200。
回應方法 GET。
伺服器回應具有 html 標頭 Conent-Type。
伺服器共鳴同時包含和標籤。
回應不包含目前的 /backup 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);

如需資源標準屬性的資訊，請參閱資源語意慣例。

修改遙測

本節說明如何修改遙測。

新增範圍屬性

若要新增span屬性，請使用下列兩種方式之一：

使用偵測連結庫所提供的選項，。
新增自訂範圍處理器。

這些屬性可能包括將自定義屬性新增至遙測。

秘訣： 使用檢測連結庫所提供的選項的優點是，可以使用整個內容。因此，用戶可以選取以新增或篩選更多屬性。例如，HttpClient 檢測連結庫中的擴充選項可讓使用者存取 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 提供六個計量「工具」來涵蓋各種計量案例，而且在計量總管中可視化計量時，您必須挑選正確的「匯總類型」。使用 OpenTelemetry 計量 API 來傳送計量，以及使用檢測連結庫時，這項需求是正確的。

下表顯示每個 OpenTelemetry Metric Instruments 的建議匯總類型]。

OpenTelemetry 檢測	Azure 監視器匯總類型
計數器	和
異步計數器	和
直方圖	平均、總和、計數（僅限 Python 和 Node.js 的最大值、最小值）
異步量測計	平均
UpDownCounter （僅限 Python 和 Node.js）	和
異步 UpDownCounter （僅限 Python 和 Node.js）	和

注意： 數據表中顯示的匯總類型通常沒有意義。

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, Exception } 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 as Exception);
}

故障排除

自我診斷

Azure 監視器 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 環境 varialbe 可用來設定所需的記錄層級，支援下列值：NONE、ERROR、WARN、INFO、DEBUG、VERBOSE 和 ALL。

記錄可以使用 APPLICATIONINSIGHTS_LOG_DESTINATION 環境變數放入本機檔案中，支援的值為 file 和 file+console，預設會在 tmp 資料夾中產生名為 applicationinsights.log 的檔案，包括所有記錄、/tmp *nix 和 Windows USERDIR/AppData/Local/Temp。您可以使用 APPLICATIONINSIGHTS_LOGDIR 環境變數來設定記錄目錄。

例子

如需幾個冠軍案例的完整範例，請參閱 samples/ 資料夾。

重要概念

如需 OpenTelemetry 專案的詳細資訊，請檢閱 OpenTelemetry 規格。

外掛程式登錄

若要查看您正在使用的連結庫是否已建立外掛程式，請參閱 OpenTelemetry Registry。

如果您無法在登錄中連結庫，請放心地在 opentelemetry-js-contrib建議新的外掛程式要求。

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

共用方式為