OpenTelemetry de Azure Monitor para JavaScript

Empezar

Instalación del paquete

npm install @azure/monitor-opentelemetry

Entornos admitidos actualmente

• versiones ltS de Node.js

• entornos de ejecución compatibles con OpenTelemetry

Advertencia: Este SDK solo funciona para entornos de Node.js. Use la del SDK de JavaScript de Application Insights para escenarios de explorador y web.

Consulte nuestra de directiva de soporte técnico de para obtener más información.

Prerrequisitos

• Un de suscripción de Azure de
• Un área de trabajo de Application Insights

Habilitación del cliente OpenTelemetry de Azure Monitor

Importante: se debe llamar auseAzureMonitorantes de importar cualquier otra cosa. Puede haber una pérdida de telemetría resultante si se importan primero otras bibliotecas.

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

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

• La cadena de conexión se puede establecer mediante la variable de entorno APPLICATIONINSIGHTS_CONNECTION_STRING

Configuración

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

Propiedad	Descripción	Predeterminado
azureMonitorExporterOptions	Configuración del exportador de OpenTelemetry de Azure Monitor. Más información aquí
samplingRatio	La relación de muestreo debe tomar un valor en el intervalo [0,1], 1 lo que significa que todos los datos se muestrearán y se muestrearán todos los datos de seguimiento.	1
instrumentationOptions	Permitir la configuración de Las instrumentaciones de OpenTelemetry.	{"http": { enabled: true },"azureSdk": { enabled: false },"mongoDb": { enabled: false },"mySql": { enabled: false },"postgreSql": { enabled: false },"redis": { enabled: false },"bunyan": { enabled: false }, "winston": { enabled: { enabled: false } }
browserSdkLoaderOptions	Permitir la configuración de instrumentaciones web.	{ enabled: false, connectionString: "" }
recurso	Recurso Opentelemetry. Más información aquí
samplingRatio	La relación de muestreo debe tomar un valor en el intervalo [0,1], 1 lo que significa que todos los datos se muestrearán y se muestrearán todos los datos de seguimiento.	1
enableLiveMetrics	Habilite o deshabilite Las métricas dinámicas.	verdadero
enableStandardMetrics	Habilite o deshabilite las métricas estándar.	verdadero
logRecordProcessors	Matriz de procesadores de registros de registro que se van a registrar en el proveedor global del registrador.
spanProcessors	Matriz de procesadores de intervalo para registrarse en el proveedor global de seguimiento.
enableTraceBasedSamplingForLogs	Habilite el muestreo de registros en función del seguimiento.	falso

Las opciones se pueden establecer mediante el archivo de configuración applicationinsights.json ubicado en la carpeta raíz de la carpeta de instalación del paquete de @azure/monitor-opentelemetry, por ejemplo: node_modules/@azure/monitor-opentelemetry. Estos valores de configuración se aplicarán a todas las instancias de AzureMonitorOpenTelemetryClient.

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

Se puede proporcionar un archivo JSON personalizado mediante APPLICATIONINSIGHTS_CONFIGURATION_FILE variable de entorno.

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

// Application Insights SDK setup....

Bibliotecas de instrumentación

Las siguientes bibliotecas de Instrumentación de OpenTelemetry se incluyen como parte de OpenTelemetry de Azure Monitor.

Advertencia: las bibliotecas de instrumentación de se basan en especificaciones experimentales de OpenTelemetry. La versión preliminar de Microsoft compromiso de soporte técnico es asegurarse de que las siguientes bibliotecas emiten datos a Application Insights de Azure Monitor, pero es posible que los cambios importantes o la asignación experimental bloqueen algunos elementos de datos.

Seguimiento distribuido

• HTTP/HTTPS
• de mongoDB de
• mySQL
• Postgres
• redis
• redis-4
• del SDK de Azure

Métricas

• HTTP/HTTPS

Trozas

• Bunyan

• de Winston

Hay otras instrumentaciones de OpenTelemetry disponibles aquí y se podrían agregar mediante TracerProvider en AzureMonitorOpenTelemetryClient.

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

Cargador del SDK del explorador de Application Insights

Application Insights Browser SDK Loader permite insertar el SDK web en las respuestas del servidor de nodos cuando se cumplen las condiciones siguientes:

• La respuesta tiene código de estado 200.
• El método response es GET.
• La respuesta del servidor tiene el encabezado html Conent-Type.
• Server resonse contiene etiquetas y .
• La respuesta no contiene puntos de conexión de CDN de instrumentación web /backup actuales. (los puntos de conexión de CDN de instrumentación web actuales y de copia de seguridad aquí)

Puede encontrar más información sobre el uso del cargador del SDK del explorador aquí.

Establecer el nombre del rol en la nube y la instancia de rol en la nube

Puede establecer el nombre del rol en la nube y la instancia de rol en la nube a través de atributos de de recursos de 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);

Para obtener información sobre los atributos estándar de los recursos, consulte Convenciones semántica de recursos.

Modificación de la telemetría

En esta sección se explica cómo modificar la telemetría.

Adición de atributos span

Para agregar atributos span, use cualquiera de las dos maneras siguientes:

• Use las opciones proporcionadas por las bibliotecas de instrumentación de .
• Agregue un procesador de intervalos personalizado.

Estos atributos pueden incluir agregar una propiedad personalizada a la telemetría.

sugerencia: La ventaja de usar las opciones proporcionadas por las bibliotecas de instrumentación, cuando están disponibles, es que todo el contexto está disponible. Como resultado, los usuarios pueden seleccionar para agregar o filtrar más atributos. Por ejemplo, la opción enrich de la biblioteca de instrumentación HttpClient proporciona a los usuarios acceso al propio httpRequestMessage. Pueden seleccionar cualquier cosa de ella y almacenarla como un atributo.

Agregar una propiedad personalizada a un seguimiento

Los atributos agregar a intervalos se exportan como propiedades personalizadas.

Usar un procesador personalizado:

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

Filtrado de telemetría

Puede usar las siguientes maneras de filtrar la telemetría antes de abandonar la aplicación.

1. Excluya la opción de dirección URL proporcionada por muchas bibliotecas de instrumentación HTTP.

   En el ejemplo siguiente se muestra cómo excluir una determinada dirección URL del seguimiento mediante el uso de la biblioteca de instrumentación HTTP/HTTPS de :

   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. Use un procesador personalizado. Puede usar un procesador de intervalos personalizado para excluir determinados intervalos de exportación. Para marcar intervalos que no se van a exportar, establezca TraceFlag en DEFAULT. Use el ejemplo agregar propiedad personalizada, pero reemplace las siguientes líneas de código:

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

Telemetría personalizada

En esta sección se explica cómo recopilar telemetría personalizada de la aplicación.

Adición de métricas personalizadas

Es posible que quiera recopilar métricas más allá de lo que recopilan las bibliotecas de instrumentación de .

La API de OpenTelemetry ofrece seis "instrumentos" de métricas para cubrir una variedad de escenarios de métricas y tendrá que elegir el "Tipo de agregación" correcto al visualizar las métricas en el Explorador de métricas. Este requisito es cierto cuando se usa openTelemetry Metric API para enviar métricas y cuando se usa una biblioteca de instrumentación.

En la tabla siguiente se muestran los tipos de agregación recomendados] para cada uno de los Instrumentos de métricas de OpenTelemetry.

OpenTelemetry Instrument	Tipo de agregación de Azure Monitor
Mostrador	Suma
Contador asincrónico	Suma
Histograma	Promedio, Suma, Recuento (máximo, mínimo para Python y solo Node.js)
Medidor asincrónico	Promedio
UpDownCounter (solo Python y Node.js)	Suma
UpDownCounter asincrónico (solo Python y Node.js)	Suma

precaución: tipos de agregación más allá de lo que se muestra en la tabla normalmente no son significativos.

El especificación OpenTelemetry describe los instrumentos y proporciona ejemplos de cuándo puede usar cada uno.

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

Agregar excepciones personalizadas

Seleccione bibliotecas de instrumentación que admiten automáticamente excepciones en Application Insights. Sin embargo, es posible que desee notificar manualmente las excepciones más allá del informe de bibliotecas de instrumentación. Por ejemplo, las excepciones detectadas por el código no se no normalmente no se notifican, y es posible que desee notificarlas y, por tanto, llamar la atención sobre ellas en experiencias relevantes, incluida la hoja errores y la vista de transacciones de un extremo a otro.

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

Solución de problemas

Autodiagnóstico

OpenTelemetry de Azure Monitor usa el registrador de API de OpenTelemetry para los registros internos. Para habilitarlo, use el código siguiente:

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 variable de entorno se podría usar para establecer el nivel de registro deseado, admitiendo los siguientes valores: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE y ALL.

Los registros se pueden colocar en un archivo local mediante APPLICATIONINSIGHTS_LOG_DESTINATION variable de entorno, los valores admitidos se file y file+console, se generará un archivo denominado applicationinsights.log en la carpeta tmp de forma predeterminada, incluidos todos los registros, /tmp para *nix y USERDIR/AppData/Local/Temp para Windows. El directorio de registro se puede configurar mediante APPLICATIONINSIGHTS_LOGDIR variable de entorno.

Ejemplos

Para obtener ejemplos completos de algunos escenarios de campeón, consulte la carpeta samples/.

Conceptos clave

Para obtener más información sobre el proyecto OpenTelemetry, revise la Especificaciones de OpenTelemetry.

Registro de complementos

Para ver si ya se ha realizado un complemento para una biblioteca que está usando, consulte la OpenTelemetry Registry.

Si no puede usar la biblioteca en el registro, no dude en sugerir una nueva solicitud de complemento en opentelemetry-js-contrib.

Contribuyendo

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.