OpenTelemetry de Azure Monitor para JavaScript

Artículo
05/10/2024

Introducción

Instalar el paquete

npm install @azure/monitor-opentelemetry

Entornos admitidos actualmente

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

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Habilitación del cliente OpenTelemetry de Azure Monitor

Importante:useAzureMonitor debe llamarse antes 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);

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	Default
azureMonitorExporterOptions	Configuración del exportador de OpenTelemetry de Azure Monitor. Más información aquí
samplingRatio	La proporción de muestreo debe tomar un valor en el intervalo [0,1], 1, lo que significa que se muestrearán todos los datos de seguimiento y se muestrearán todos los datos de seguimiento.	1
instrumentationOptions	Permitir la configuración de 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: "" }
resource	Recurso Opentelemetry. Más información aquí
samplingRatio	La proporción de muestreo debe tomar un valor en el intervalo [0,1], 1, lo que significa que se muestrearán todos los datos de seguimiento y se muestrearán todos los datos de seguimiento.	1
enableLiveMetrics	Habilite o deshabilite Live Metrics.	false
enableStandardMetrics	Habilite o deshabilite las métricas estándar.	true
logRecordProcessors	Matriz de procesadores de registros de registro que se van a registrar en el proveedor global de registradores.
spanProcessors	Matriz de procesadores de intervalo para registrarse en el proveedor de seguimiento global.

Las opciones se pueden establecer mediante el archivo applicationinsights.json de configuración ubicado en la carpeta raíz de la carpeta de instalación del @azure/monitor-opentelemetry paquete, 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 la 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 se basan en especificaciones de OpenTelemetry experimentales. El compromiso de soporte técnico de la versión preliminar de Microsoft es garantizar que las siguientes bibliotecas emitan datos a Azure Monitor Application Insights, aunque es posible que los cambios importantes o la asignación experimental bloqueen algunos elementos de datos.

Seguimiento distribuido

Métricas

HTTP/HTTPS

Registros

Hay disponibles otras instrumentaciones de OpenTelemetry aquí y se pueden 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

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

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 resonse del servidor contiene las 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í)

Establecimiento del nombre 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 los atributos de recurso 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 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.

Incorporación de atributos de intervalo

Puede agregar atributos de intervalo 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.

Agregar una propiedad personalizada al seguimiento

Los atributos que se agregan a intervalos se exportan como propiedades personalizadas.

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

Telemetría de filtro

Use los siguientes métodos para filtrar los datos de telemetría antes de que salgan de la aplicación.

Excluya la opción de dirección URL que proporcionan 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 { 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);

Use 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 incorporación de 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 datos de telemetría personalizados de la aplicación.

Agregar Métricas personalizadas

Es posible que quiera 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 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 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 de métricas de OpenTelemetry.

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

Precaución: 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 { 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 admitan 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 notifican normalmente, y es posible que desee notificarlas y, por tanto, llamar su atención 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 } 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);
}

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";
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_LEVELenvironment varialbe se puede usar para establecer el nivel de registro deseado, admitiendo los valores siguientes: NONE, ERRORWARN, , INFO, DEBUGy VERBOSEALL.

Los registros se pueden colocar en un archivo local mediante APPLICATIONINSIGHTS_LOG_DESTINATION la variable de entorno, los valores admitidos son file y file+console, un archivo denominado applicationinsights.log se generará 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 obtener ejemplos completos de algunos escenarios de campeón, consulte la samples/ carpeta .

Conceptos clave

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

Registro de complementos

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

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

Contribuciones

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

Impresiones

Share via