Azure Monitor OpenTelemetry untuk JavaScript

2025-06-13

Memulai Langkah Pertama

Pasang paketnya

npm install @azure/monitor-opentelemetry

Lingkungan yang didukung saat ini

Peringatan: SDK ini hanya berfungsi untuk lingkungan Node.js. Gunakan Application Insights JavaScript SDK untuk skenario web dan browser.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Mengaktifkan Klien OpenTelemetry Azure Monitor

Penting:useAzureMonitor harus dipanggil sebelum Anda mengimpor hal lain. Mungkin ada kehilangan telemetri yang dihasilkan jika pustaka lain diimpor terlebih dahulu.

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

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

String Koneksi dapat diatur menggunakan variabel APPLICATIONINSIGHTS_CONNECTION_STRINGlingkungan .

Konfigurasi

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

const resource = resourceFromAttributes({ 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);

Opsi	Deskripsi	Bawaan
`azureMonitorExporterOptions`	Konfigurasi Pengekspor OpenTelemetri Azure Monitor. Info lebih lanjut di sini
`samplingRatio`	Rasio pengambilan sampel harus mengambil nilai dalam rentang [0,1], 1 yang berarti semua data akan diambil sampelnya dan 0 semua data Pelacakan akan diambil sampelnya.	`1`
`instrumentationOptions`	Konfigurasi pustaka instrumentasi. Info lebih lanjut di sini	`{ 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`	Izinkan konfigurasi Web Instrumentations.	`{ enabled: false, connectionString: "" }`
`resource`	Sumber daya Opentelemetry. Info lebih lanjut di sini
`enableLiveMetrics`	Aktifkan/nonaktifkan metrik langsung.	`true`
`enableStandardMetrics`	Aktifkan/nonaktifkan metrik standar.	`true`
`logRecordProcessors`	Array prosesor catatan log untuk mendaftar ke penyedia logger global.
`spanProcessors`	Array prosesor rentang untuk mendaftar ke penyedia pelacak global.
`enableTraceBasedSamplingForLogs`	Aktifkan pengambilan sampel log berdasarkan pelacakan.	`false`
`enablePerformanceCounters`	Aktifkan penghitung performa.	`true`

Opsi dapat diatur menggunakan file applicationinsights.json konfigurasi yang terletak di bawah folder root folder instalasi @azure/monitor-opentelemetry paket, Mis: node_modules/@azure/monitor-opentelemetry. Nilai konfigurasi ini akan diterapkan ke semua instans AzureMonitorOpenTelemetryClient.

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

File JSON kustom dapat disediakan menggunakan APPLICATIONINSIGHTS_CONFIGURATION_FILE variabel lingkungan.

process.env["APPLICATIONINSIGHTS_CONFIGURATION_FILE"] = "path/to/customConfig.json";

Perpustakaan Instrumentasi

Pustaka Instrumentasi OpenTelemetry berikut disertakan sebagai bagian dari Azure Monitor OpenTelemetry.

Peringatan: Perpustakaan instrumentasi didasarkan pada spesifikasi OpenTelemetry eksperimental. Komitmen dukungan pratinjau Microsoft adalah untuk memastikan bahwa pustaka berikut memancarkan data ke Azure Monitor Application Insights, tetapi ada kemungkinan bahwa perubahan yang melanggar atau pemetaan eksperimental akan memblokir beberapa elemen data.

Pelacakan Terdistribusi

Metode pengukuran

HTTP/HTTPS

Catatan

Instrumentasi OpenTelemetry lainnya tersedia di sini dan dapat ditambahkan menggunakan TracerProvider di AzureMonitorOpenTelemetryClient.

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

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

Pemuat SDK Browser Application Insights

Application Insights Browser SDK Loader memungkinkan Anda menyuntikkan web SDK ke respons server simpul ketika kondisi berikut benar:

Respons memiliki kode 200status .
Metode respons adalah GET.
Respons server memiliki Conent-Type header html.
Resonse server berisi keduanya dan tag.
Respon tidak berisi titik akhir CDN terkini atau cadangan untuk Instrumentasi web. (endpoint CDN Instrumentasi Web saat ini dan cadangan di sini)

Informasi lebih lanjut tentang penggunaan browser SDK loader dapat ditemukan di sini.

Tetapkan Nama Peran Cloud dan Instans Peran Cloud

Anda dapat mengatur atribut Cloud Role Name dan Cloud Role Instance melalui OpenTelemetry Resource .

import {
  ATTR_SERVICE_NAME,
  SEMRESATTRS_SERVICE_NAMESPACE,
  SEMRESATTRS_SERVICE_INSTANCE_ID,
} from "@opentelemetry/semantic-conventions";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[ATTR_SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SEMRESATTRS_SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SEMRESATTRS_SERVICE_INSTANCE_ID] = "my-instance";

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

Untuk informasi tentang atribut standar untuk sumber daya, lihat Konvensi Semantik Sumber Daya.

Mengubah telemetri

Bagian ini menjelaskan cara memodifikasi telemetri.

Menambahkan atribut rentang

Untuk menambahkan atribut rentang, gunakan salah satu dari dua cara berikut ini:

Gunakan opsi yang disediakan oleh pustaka instrumentasi.
Tambahkan prosesor rentang kustom.

Atribut ini mungkin menambahkan properti kustom ke telemetri Anda.

Ujung: Keuntungan menggunakan opsi yang disediakan oleh pustaka instrumentasi, ketika tersedia, adalah bahwa seluruh konteks tersedia. Sebagai hasilnya, pengguna dapat memilih untuk menambahkan atau memfilter lebih banyak atribut. Sebagai contoh, opsi memperkaya di pustaka instrumentasi HttpClient memberikan pengguna akses ke httpRequestMessage itu sendiri. Mereka dapat memilih apa pun darinya dan menyimpannya sebagai atribut.

Menambahkan properti kustom ke Pelacakan

Atribut apa pun yang Anda tambahkan ke rentang diekspor sebagai properti kustom.

Gunakan prosesor kustom:

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

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span): void {}
  onEnd(span: ReadableSpan): void {
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SEMATTRS_HTTP_CLIENT_IP] = "<IP Address>";
  }
}

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

useAzureMonitor(options);

Tambahkan nama operasi ke pelacakan dan log

Gunakan prosesor rentang kustom dan prosesor catatan log untuk melampirkan dan menghubungkan nama operasi dari permintaan ke dependensi dan log.

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, trace } from "@opentelemetry/api";
import { AI_OPERATION_NAME } from "@azure/monitor-opentelemetry-exporter";
import { LogRecordProcessor, LogRecord } from "@opentelemetry/sdk-logs";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onStart(_span: Span, _context: Context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _span.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
  onEnd(_span: ReadableSpan): void {}
}

class LogRecordEnrichingProcessor implements LogRecordProcessor {
  async forceFlush(): Promise<void> {
    // Flush code here
  }
  async shutdown(): Promise<void> {
    // shutdown code here
  }
  onEmit(_logRecord: LogRecord, _context: Context): void {
    const parentSpan = trace.getSpan(_context);
    if (parentSpan && "name" in parentSpan) {
      // If the parent span has a name we can assume it is a ReadableSpan and cast it.
      _logRecord.setAttribute(AI_OPERATION_NAME, (parentSpan as unknown as ReadableSpan).name);
    }
  }
}

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

useAzureMonitor(options);

Memfilter telemetri

Anda dapat menggunakan cara berikut untuk memfilter telemetri sebelum keluar dari aplikasi Anda.

Kecualikan opsi URL yang disediakan oleh banyak pustaka instrumentasi HTTP.

Contoh berikut menunjukkan cara mengecualikan URL tertentu agar tidak dilacak dengan menggunakan pustaka instrumentasi HTTP/HTTPS:

import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
import { IncomingMessage, RequestOptions } from "node:http";
import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

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

Gunakan prosesor khusus. Anda dapat menggunakan prosesor rentang kustom untuk mengecualikan rentang tertentu agar tidak diekspor. Untuk menandai rentang agar tidak diekspor, atur TraceFlag ke DEFAULT. Gunakan contoh add custom property, tetapi ganti baris kode berikut:

import { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
import { Span, Context, SpanKind, TraceFlags } from "@opentelemetry/api";

class SpanEnrichingProcessor implements SpanProcessor {
  async forceFlush(): Promise<void> {
    // Force flush code here
  }
  onStart(_span: Span, _parentContext: Context): void {
    // Normal code here
  }
  async shutdown(): Promise<void> {
    // Shutdown code here
  }
  onEnd(span: ReadableSpan): void {
    if (span.kind === SpanKind.INTERNAL) {
      span.spanContext().traceFlags = TraceFlags.NONE;
    }
  }
}

Telemetri kustom

Bagian ini menjelaskan cara mengumpulkan telemetri kustom dari aplikasi Anda.

Menambahkan Metrik Kustom

Anda mungkin ingin mengumpulkan metrik di luar apa yang dikumpulkan oleh pustaka instrumentasi.

OpenTelemetry API menawarkan enam "instrumen" metrik untuk mencakup berbagai skenario metrik dan Anda harus memilih "Jenis Agregasi" yang benar saat memvisualisasikan metrik di Metrics Explorer. Persyaratan ini berlaku saat menggunakan API Metrik OpenTelemetry untuk mengirim metrik dan saat menggunakan pustaka instrumentasi.

Tabel berikut menunjukkan jenis agregasi yang direkomendasikan] untuk masing-masing Instrumen Metrik OpenTelemetry.

Instrumen OpenTelemetry	Jenis Agregasi Azure Monitor
Penghitung	Jumlah total
Penghitung Asinkron	Jumlah total
Histogram	Rata-rata, Jumlah, Jumlah (Maks, Min untuk Python dan Node.js saja)
Pengukur Asinkron	Tengah
UpDownCounter (khusus Python dan Node.js)	Jumlah total
UpDownCounter Asinkron (hanya Python dan Node.js)	Jumlah total

Hati: Jenis agregasi di luar apa yang ditampilkan dalam tabel biasanya tidak bermakna.

Spesifikasi OpenTelemetry menjelaskan instrumen dan memberikan contoh kapan Anda dapat menggunakan masing-masing instrumen.

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

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

const histogram = meter.createHistogram("histogram");
const counter = meter.createCounter("counter");
const gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
  const 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" });

Tambahkan Pengecualian Kustom

Pustaka instrumentasi tertentu secara otomatis mendukung pengecualian ke Application Insights. Namun, Anda mungkin ingin melaporkan pengecualian secara manual di luar apa yang dilaporkan pustaka instrumention. Misalnya, pengecualian yang ditangkap oleh kode Anda biasanya tidak dilaporkan, dan Anda mungkin ingin melaporkannya dan dengan demikian menarik perhatian padanya dalam pengalaman yang relevan termasuk bilah kegagalan dan tampilan transaksi end-to-end.

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

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

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

Penyelesaian Masalah

Diagnostik mandiri

Azure Monitor OpenTelemetry menggunakan OpenTelemetry API Logger untuk log internal. Untuk mengaktifkannya, gunakan kode berikut:

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

process.env["APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL"] = "VERBOSE";
process.env["APPLICATIONINSIGHTS_LOG_DESTINATION"] = "file";
process.env["APPLICATIONINSIGHTS_LOGDIR"] = "path/to/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVELVariabel lingkungan dapat digunakan untuk mengatur tingkat log yang diinginkan, mendukung nilai-nilai berikut: NONE, , WARNERROR, DEBUGINFOVERBOSE , dan .ALL

Log dapat dimasukkan ke dalam file lokal menggunakan APPLICATIONINSIGHTS_LOG_DESTINATION variabel lingkungan, nilai yang didukung adalah file dan file+console, file bernama applicationinsights.log akan dibuat di folder tmp secara default, termasuk semua log, /tmp untuk *nix dan USERDIR/AppData/Local/Temp untuk Windows. Direktori log dapat dikonfigurasi menggunakan APPLICATIONINSIGHTS_LOGDIR variabel lingkungan.

Contoh

Untuk sampel lengkap dari beberapa skenario juara, lihat samples/ folder.

Konsep utama

Untuk informasi lebih lanjut tentang proyek OpenTelemetry, silakan tinjau Spesifikasi OpenTelemetry.

Registri Plugin

Untuk melihat apakah plugin telah dibuat untuk perpustakaan yang Anda gunakan, silakan lihat OpenTelemetry Registry.

Jika Anda tidak dapat membuka perpustakaan Anda di registri, jangan ragu untuk menyarankan permintaan plugin baru di opentelemetry-js-contrib.

Berpartisipasi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.