Compartir vía

Migración desde el SDK 2.X de Node.js Application Insights a Azure Monitor OpenTelemetry

  • Artículo

Esta guía proporciona dos opciones para actualizar desde el SDK 2.X de Azure Monitor Application Insights Node.js a OpenTelemetry.

  • Realice una Instalación limpia de la Distribución de OpenTelemetry de Azure Monitor de Node.js.
    • Quite las dependencias de la API clásica de Application Insights.
    • Familiarícese con las API y los términos de OpenTelemetry.
    • Prepárese para usar todo lo que OpenTelemetry le ofrece ahora y en el futuro.
  • Actualice al SDK 3.X de Node.js.
    • Posponga los cambios de código preservando la compatibilidad con los eventos y métricas personalizados existentes.
    • Acceda a bibliotecas de instrumentación de OpenTelemetry más completas.
    • Mantener la elegibilidad para las últimas correcciones de errores y seguridad.

  1. Adquiera conocimientos previos sobre la Interfaz de programación de aplicaciones (API) de OpenTelemetry JavaScript y el Kit de desarrollo de software (SDK).

  2. Desinstale la dependencia applicationinsights de su proyecto.

    npm uninstall applicationinsights

  3. Quite la implementación del SDK 2.X del código.

    Quite toda la instrumentación de Application Insights del código. Elimine las secciones en las que se inicialice, modifique o llame al cliente de Application Insights.

  4. Habilite Application Insights con la Distribución de OpenTelemetry de Azure Monitor.

    Importante

    Antes de importar cualquier otra cosa, se debe llamar a useAzureMonitor. Es posible que haya pérdida de telemetría si primero se importan otras bibliotecas. Siga la introducción para incorporarse a la Distribución de OpenTelemetry de Azure Monitor.

Cambios y limitaciones de la Distribución de OpenTelemetry de Azure Monitor

  • Las API del SDK 2.X de Application Insights no están disponibles en la Distribución de OpenTelemetry de Azure Monitor. Puede acceder a estas API a través de una ruta de actualización sin interrupciones en el SDK 3.X de Application Insights.
  • Todavía no se admite el filtrado de dependencias, registros y excepciones por nombre de la operación.

Notas y limitaciones

Los siguientes cambios y limitaciones se aplican a ambas rutas de actualización.

Compatibilidad con versiones de Node.js

Para que una versión de Node.js sea compatible con el SDK de ApplicationInsights 3.X, debe tener compatibilidad superpuesta tanto del SDK de Azure como de OpenTelemetry. Compruebe los entornos de ejecución compatibles con OpenTelemetry para ver las actualizaciones más recientes. Los usuarios de versiones anteriores como Node 8, anteriormente compatibles con el SDK de ApplicationInsights, pueden seguir usando las soluciones de OpenTelemetry, pero pueden experimentar un comportamiento inesperado o interrupciones. El SDK de ApplicationInsights también depende del SDK de Azure para JS, que no garantiza la compatibilidad con ninguna versión de Node.js que haya alcanzado el final del ciclo de vida. Vea la directiva de compatibilidad del SDK de Azure para JS. Para que una versión de Node.js sea compatible con el SDK de ApplicationInsights 3.X, debe tener compatibilidad superpuesta tanto del SDK de Azure como de OpenTelemetry.

Opciones de configuración

La versión 2.X del SDK de Application Insights ofrece opciones de configuración que no están disponibles en la Distribución de OpenTelemetry de Azure Monitor ni en la actualización de la versión principal al SDK 3.X de Application Insights. Para encontrar estos cambios, junto con las opciones que seguimos admitiendo, consulte Documentación de configuración del SDK.

Métricas extendidas

Las métricas extendidas son compatibles con el SDK 2.X de Application Insights; sin embargo, la compatibilidad con estas métricas finaliza tanto en la versión 3.X del SDK de ApplicationInsights como en la Distribución de OpenTelemetry de Azure Monitor.

Procesadores de telemetría

Si bien la Distribución de OpenTelemetry de Azure Monitor y el SDK 3.X de Application Insights no son compatibles con TelemetryProcessors, sí permiten pasar procesadores de intervalos y registros. Para más información sobre cómo hacerlo, consulte Proyecto de Distribución de OpenTelemetry de Azure Monitor.

Este ejemplo muestra el equivalente de crear y aplicar un procesador de telemetría que adjunta una propiedad personalizada en el SDK 2.X de Application Insights.

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

Este ejemplo muestra cómo modificar una implementación de Distribución de OpenTelemetry de Azure Monitor para pasar un SpanProcessor a la configuración de la distribución.

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);