Azure Monitor OpenTelemetry for JavaScript

Cómo empezar

Instalación del paquete

npm install @azure/monitor-opentelemetry

Entornos admitidos actualmente

• Versiones de LTS de Node.js

• Entornos de ejecución compatibles con OpenTelemetry

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

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

Prerrequisitos

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

Habilitación del cliente OpenTelemetry de Azure Monitor

Importante:useAzureMonitor se debe llamar antes de importar cualquier otra cosa. Es posible que se produzca una pérdida de telemetría si primero se importan otras bibliotecas.

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } 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 APPLICATIONINSIGHTS_CONNECTION_STRINGde entorno .

Configuración

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

{
  http: { enabled: true },
  azureSdk: { enabled: false },
  mongoDb: { enabled: false },
  mySql: { enabled: false },
  postgreSql: { enabled: false },
  redis: { enabled: false },
  bunyan: { enabled: false }, 
  winston: { enabled: false } 
}
      

        
{ 
  enabled: false, 
  connectionString: "" 
}
        
      

Las opciones se pueden establecer usando el archivo applicationinsights.json de configuración ubicado en la carpeta raíz de la carpeta de instalación del @azure/monitor-opentelemetry paquete, Ej: 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
        }
    },
    ...
}

El archivo JSON personalizado se puede proporcionar mediante una APPLICATIONINSIGHTS_CONFIGURATION_FILE variable de entorno.

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

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 se basan en especificaciones experimentales de OpenTelemetry. El compromiso de soporte técnico de Microsoft en versión preliminar es garantizar que las siguientes bibliotecas emitan 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
• MongoDB
• MySQL
• Postgres
• Redis
• Redis-4
• SDK de Azure

Métricas

• HTTP/HTTPS

Registros

• Bunyan

• Winston

Otras instrumentaciones de OpenTelemetry están disponibles aquí y se podrían agregar mediante TracerProvider en 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()],
});

Cargador del SDK del explorador de Application Insights

El cargador del SDK del explorador de Application Insights permite insertar el SDK web en las respuestas del servidor de nodo cuando se cumplen las siguientes condiciones:

• La respuesta tiene el código de estado 200.
• El método de respuesta es GET.
• La respuesta del servidor tiene el Conent-Type encabezado html.
• La resonancia del servidor contiene ambas etiquetas y .
• La respuesta no contiene puntos de conexión de CDN actuales de instrumentación web/copia de seguridad. (encontrará 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 navegador aquí.

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

Puede establecer el nombre del rol en la nube y la instancia del rol en la nube a través de los atributos del recurso de OpenTelemetry .

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

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

Modificación de la telemetría

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

Agregar atributos de span

Puede agregar atributos de span mediante cualquiera de los dos métodos siguientes.

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

Estos atributos pueden incluir agregar una propiedad personalizada a sus datos de telemetría.

Propina: La ventaja de usar las opciones proporcionadas por las bibliotecas de instrumentación, cuando están disponibles, es que todo el contexto está disponible. En consecuencia, los usuarios pueden optar por agregar o filtrar más atributos. Por ejemplo, la opción de enriquecimiento de la biblioteca de instrumentación HttpClient proporciona a los usuarios acceso al propio httpRequestMessage. Pueden seleccionar lo que deseen de él y almacenarlo como atributo.

Adición de una propiedad personalizada a un objeto Trace

Los atributos que agregues a los elementos se exportan como propiedades personalizadas.

Use un procesador personalizado:

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

Agregar el nombre de la operación a los seguimientos y registros

Utilice un procesador de intervalo personalizado y un procesador de entradas de registro para adjuntar y correlacionar el nombre de la operación de las solicitudes a las dependencias y los registros.

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

Telemetría de filtro

Puede usar las siguientes formas para filtrar la telemetría antes de que salga de la aplicación.

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

   A continuación se muestra un ejemplo de cómo excluir una dirección URL determinada del seguimiento mediante la biblioteca de instrumentación 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);
   

2. Utilice un procesador personalizado. Puede usar un procesador de intervalos personalizado para excluir determinados intervalos de la exportación. Para marcar los intervalos que no se van a exportar, establezca TraceFlag en DEFAULT. Use el ejemplo de agregar propiedad personalizada, pero reemplace las siguientes líneas de código:

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

Telemetría personalizada

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

Agregar métricas personalizadas

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

La API de OpenTelemetry ofrece seis "instrumentos" de métricas para cubrir una variedad de escenarios de métricas, y deberá elegir el "Tipo de agregación" correcto al visualizar métricas en el Explorador de métricas. Este requisito es cierto cuando se usa la API de métricas de OpenTelemetry 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 métricos de OpenTelemetry.

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

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

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

Agregar excepciones personalizadas

Las bibliotecas de instrumentación seleccionadas admiten automáticamente excepciones a Application Insights. Sin embargo, es posible que desee informar manualmente de las excepciones más allá de lo que informan las bibliotecas de instrumentos. Por ejemplo, las excepciones detectadas por el código normalmente no se notifican, y es posible que desee notificarlas y, por lo tanto, llamar la atención sobre ellas en experiencias relevantes, incluida la hoja de 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");

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

Solución de problemas

Diagnóstico automático

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

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_LEVELLa variable de entorno se puede utilizar para establecer el nivel de registro deseado, admitiendo los siguientes valores: NONE, ERROR, WARN, VERBOSEINFODEBUG, , y .ALL

Los registros se pueden colocar en un archivo local usando APPLICATIONINSIGHTS_LOG_DESTINATION la variable de entorno, los valores admitidos son file y file+console, se generará un archivo llamado 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 una variable de entorno.

Ejemplos

Para ver ejemplos completos de algunas situaciones de campeones, consulte la samples/ carpeta.

Conceptos clave

Para obtener más información sobre el proyecto OpenTelemetry, consulte las especificaciones de OpenTelemetry.

Registro de plugins

Para ver si ya se ha creado un complemento para una biblioteca que está utilizando, consulte el Registro de OpenTelemetry.

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

Contribución

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.