JavaScript için Azure İzleyici OpenTelemetry

Başlangıç Yapmak

Paketi yükle

npm install @azure/monitor-opentelemetry

Şu anda desteklenen ortamlar

Uyarı: Bu SDK yalnızca Node.js ortamlarda çalışır. Web ve tarayıcı senaryoları için Application Insights JavaScript SDK'sını kullanın.

Daha fazla bilgi için bkz. destek ilkesi.

Önkoşullar

Azure İzleyici OpenTelemetry İstemcisi'ni etkinleştirme

Önemli:useAzureMonitor başka bir şey içe aktarmadan önce çağrılmalıdır. Önce diğer kitaplıklar içeri aktarılırsa telemetri kaybı oluşabilir.

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

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

Bağlantı Dizesi, ortam değişkeni APPLICATIONINSIGHTS_CONNECTION_STRINGkullanılarak ayarlanabilir.

Konfigürasyon

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

Seçenek	Açıklama	Varsayılan
`azureMonitorExporterOptions`	Azure İzleyici OpenTelemetry Dışarı Aktarıcı Yapılandırması. Daha fazla bilgi burada
`samplingRatio`	Örnekleme oranı [0,1] aralığında bir değer almalıdır, 1 yani tüm veriler örneklenecek ve 0 tüm İzleme verileri örneklenecektir.	`1`
`instrumentationOptions`	İzleme kitaplıkları yapılandırması. Daha fazla bilgi burada	`{ http: { enabled: true }, azureSdk: { enabled: true }, mongoDb: { enabled: true }, mySql: { enabled: true }, postgreSql: { enabled: true }, redis: { enabled: true }, redis4: { enabled: true }, bunyan: { enabled: false }, winston: { enabled: false } }`
`browserSdkLoaderOptions`	Web İzlemelerinin yapılandırılmasına izin verin.	`{ enabled: false, connectionString: "" }`
`resource`	Açık telemetri kaynağı. Daha fazla bilgi burada
`enableLiveMetrics`	Canlı ölçümleri etkinleştirin/devre dışı bırakın.	`true`
`enableStandardMetrics`	Standart ölçümleri etkinleştirin/devre dışı bırakın.	`true`
`logRecordProcessors`	Global logger sağlayıcısına kaydolmak için günlük kayıt işlemcileri dizisi.
`spanProcessors`	Genel izleyici sağlayıcısına kaydolmak için yayılma işlemcileri dizisi.
`enableTraceBasedSamplingForLogs`	İzlemeye dayalı günlük örneklemeyi etkinleştirin.	`false`
`enablePerformanceCounters`	Performans sayaçlarını etkinleştirin.	`true`

Seçenekler, paket yükleme klasörünün applicationinsights.json kök klasörü altında bulunan yapılandırma dosyası @azure/monitor-opentelemetry kullanılarak ayarlanabilir, Ex: node_modules/@azure/monitor-opentelemetry. Bu yapılandırma değerleri tüm AzureMonitorOpenTelemetryClient örneklerine uygulanır.

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

Ortam değişkeni kullanılarak APPLICATIONINSIGHTS_CONFIGURATION_FILE özel JSON dosyası sağlanabilir.

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

Enstrümantasyon kütüphaneleri

Aşağıdaki OpenTelemetry İzleme kitaplıkları, Azure İzleyici OpenTelemetry'nin bir parçası olarak dahil edilmiştir.

Not: Azure SDK, MongoDB, MySQL, PostgreSQL, Redis ve Redis-4 araçları dağıtılmış izleme için varsayılan olarak etkindir. HTTP/HTTPS izleme özelliği de varsayılan olarak etkindir. Diğer tüm izlemeler varsayılan olarak devre dışıdır ve izleme seçeneklerinde ayarlanarak enabled: true etkinleştirilebilir.

Uyarı: İzleme kitaplıkları deneysel OpenTelemetry belirtimlerini temel alır. Microsoft'un önizleme desteği taahhüdü, aşağıdaki kitaplıkların Azure İzleyici Application Insights'a veri yaymasını sağlamaktır, ancak hataya neden olan değişikliklerin veya deneysel eşlemenin bazı veri öğelerini engellemesi mümkündür.

Dağıtılmış İzleme

Ölçümler

HTTP/HTTPS (HTTP/HTTPS)

Kayıtlar

Diğer OpenTelemetry İzlemeleri burada bulunabilir ve AzureMonitorOpenTelemetryClient'ta TracerProvider kullanılarak eklenebilir.

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()],
});

Application Insights Tarayıcı SDK Yükleyicisi

Application Insights Tarayıcı SDK'sı Yükleyicisi, aşağıdaki koşullar doğru olduğunda web SDK'sını düğüm sunucusu yanıtlarına eklemenize olanak tanır:

Yanıtın durum kodu 200vardır.
Yanıt yöntemi: GET.
Sunucu yanıtı html başlığına Conent-Type sahiptir.
Sunucu rezonansı her ikisini de ve etiketlerini içerir.
Yanıt geçerli / yedek web Enstrümantasyon CDN uç noktalarını içermiyor. (geçerli ve yedek Web Araçları CDN uç noktaları burada)

Tarayıcı SDK yükleyicisinin kullanımı hakkında daha fazla bilgiyi burada bulabilirsiniz.

Bulut Rolü Adını ve Bulut Rolü Örneğini Ayarlama

Bulut Rolü Adı'nı ve Bulut Rolü Örneğini OpenTelemetry Kaynak öznitelikleri aracılığıyla ayarlayabilirsiniz.

import { emptyResource } from "@opentelemetry/resources";
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 = emptyResource();
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);

Kaynakların standart öznitelikleri hakkında daha fazla bilgi için bkz: Kaynak Anlam Kuralları.

Telemetriyi değiştirme

Bu bölümde telemetrinin nasıl değiştirileceği açıklanmaktadır.

Span öznitelikleri ekleme

Span öznitelikleri eklemek için aşağıdaki iki yoldan birini kullanın:

Araç kütüphaneleri tarafından sağlanan seçenekleri kullanın.
Özel bir span işlemcisi ekleyin.

Bu öznitelikler telemetrinize özel özellik eklemeyi içerebilir.

Bahşiş: Kullanılabilir olduklarında izleme kitaplıkları tarafından sağlanan seçenekleri kullanmanın avantajı, bağlamın tamamının kullanılabilir olmasıdır. Sonuç olarak, kullanıcılar daha fazla öznitelik eklemeyi veya filtrelemeyi seçebilir. Örneğin, HttpClient izleme kitaplığındaki zenginleştirme seçeneği, kullanıcılara httpRequestMessage'ın kendisine erişim verir. Herhangi bir öğeyi seçip bir öznitelik olarak depolayabilirler.

İzlemeye özel özellik ekleme

Span'lara eklediğiniz tüm öznitelikler özel özellikler olarak dışarı aktarılır.

Özel işlemci kullanın:

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

İzlemelere ve günlüklere işlem adı ekleme

İsteklerden bağımlılıklara ve günlüklere işlem adı eklemek ve ilişkilendirmek için özel bir yayılma işlemcisi ve günlük kaydı işlemcisi kullanın.

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, SdkLogRecord } 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: SdkLogRecord, _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);

Filtre telemetrisi

Telemetriyi uygulamanızdan ayrılmadan önce filtrelemek için aşağıdaki yolları kullanabilirsiniz.

Birçok HTTP izleme kitaplığı tarafından sağlanan URL seçeneğini hariç tutun.

Aşağıdaki örnekte , HTTP/HTTPS izleme kitaplığı kullanılarak belirli bir URL'nin izlenmesini nasıl hariç tutulduğu gösterilmektedir:

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

Özel bir işlemci kullanın. Belirli aralıkların dışarı aktarılmasını dışlamak için özel bir span işlemcisi kullanabilirsiniz. Yayılmaları dışarı aktarılmayacak şekilde işaretlemek için olarak TraceFlagayarlayınDEFAULT. Özel özellik ekleme örneğini kullanın, ancak aşağıdaki kod satırlarını değiştirin:

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

Özel telemetri

Bu bölümde, uygulamanızdan özel telemetri verilerinin nasıl toplayacağınız açıklanmaktadır.

Özel metrikler ekleme

Ölçümlü izleme kitaplıkları tarafından toplananların ötesinde ölçümler toplamak isteyebilirsiniz.

OpenTelemetry API'si, çeşitli ölçüm senaryolarını kapsayacak şekilde altı ölçüm "aracı" sunar ve Ölçüm Gezgini'nde ölçümleri görselleştirirken doğru "Toplama Türü"nü seçmeniz gerekir. Bu gereksinim, ölçümleri göndermek için OpenTelemetry Ölçüm API'sini kullanırken ve bir izleme kitaplığı kullanırken geçerlidir.

Aşağıdaki tabloda, OpenTelemetry Ölçüm Araçlarının her biri için önerilen toplama türleri gösterilmektedir.

OpenTelemetry Enstrüman	Azure İzleyici Toplama Türü
Sayaç	Toplam
Zaman Uyumsuz Sayaç	Toplam
Histogram Grafiği	Ortalama, Toplam, Sayı (yalnızca Python ve Node.js için Maks, Min)
Zaman Uyumsuz Ölçer	Ortalama
UpDownCounter (yalnızca Python ve Node.js)	Toplam
Asenkron UpDownCounter (yalnızca Python ve Node.js)	Toplam

Dikkat: Tabloda gösterilenin dışındaki toplama türleri genellikle anlamlı değildir.

OpenTelemetry Belirtimi, araçları açıklar ve her birini ne zaman kullanabileceğinize ilişkin örnekler sağlar.

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

Özel İstisnalar Ekleme

Belirli izleme kitaplıkları Application Insights özel durumlarını otomatik olarak destekler. Ancak, izleme kitaplıklarının raporladığının ötesinde özel durumları el ile raporlamak isteyebilirsiniz. Örneğin, kodunuz tarafından yakalanan özel durumlar normalde bildirilmez ve bunları raporlamak ve böylece hatalar dikey penceresi ve uçtan uca işlem görünümü dahil olmak üzere ilgili deneyimlerde bunlara dikkat çekmek isteyebilirsiniz.

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

Sorun giderme

Kendi kendine tanılama

Azure İzleyici OpenTelemetry, iç günlükler için OpenTelemetry API Günlükçüsü'nü kullanır. Etkinleştirmek için aşağıdaki kodu kullanın:

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_LEVELOrtam değişkeni, aşağıdaki değerleri destekleyerek istenen günlük düzeyini ayarlamak için kullanılabilir: NONE, ERROR, WARNINFODEBUGVERBOSE , , ve .ALL

Günlükler, ortam değişkeni kullanılarak APPLICATIONINSIGHTS_LOG_DESTINATION yerel dosyaya yerleştirilebilir, desteklenen değerler ve filefile+console, *nix ve applicationinsights.log Windows için tüm günlükler /tmp dahil olmak üzere varsayılan olarak tmp klasöründe adlı USERDIR/AppData/Local/Temp bir dosya oluşturulur. Günlük dizini ortam değişkeni kullanılarak APPLICATIONINSIGHTS_LOGDIR yapılandırılabilir.

Örnekler

Birkaç şampiyon senaryosunun tam örnekleri için klasöre bakın samples/ .

Temel kavramlar

OpenTelemetry projesi hakkında daha fazla bilgi için lütfen OpenTelemetry Belirtimleri'ni gözden geçirin.

Eklenti Kayıt Defteri

Kullanmakta olduğunuz bir kitaplık için zaten bir eklenti yapılıp yapılmadığını görmek için lütfen OpenTelemetry Kayıt Defteri'ne bakın.

Kitaplığınızı kayıt defterinde bulamıyorsanız, adresinden opentelemetry-js-contribyeni bir eklenti isteği önermekten çekinmeyin.

Katkıda Bulunmak

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-14