Node.js y OpenTelemetry

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Esta página está diseñada para desarrolladores de aplicaciones que deseen recopilar datos de Cloud Trace para aplicaciones de Node.js mediante OpenTelemetry. OpenTelemetry es un conjunto de bibliotecas de instrumentación para recopilar datos de seguimiento y de métricas; estas bibliotecas funcionan con varios backends. Para recopilar seguimientos con OpenTelemetry y Node.js, haz lo siguiente, como se describe en esta página:

  • Instala los paquetes de OpenTelemetry.
  • Configura la aplicación para exportar intervalos a Cloud Trace.
  • Configura tu plataforma.

Para obtener información sobre la versión, consulta los siguientes vínculos:

Para ver el contenido de referencia de OpenTelemetry, consulta lo siguiente:

Si quieres obtener más información sobre OpenTelemetry para Node.js, junto con documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de comenzar

Verifica que la API de Cloud Trace esté habilitada para tu proyecto de Google Cloud:

  1. Haz clic en el siguiente botón o, en Google Cloud Console, selecciona API y servicios y, luego, selecciona API de Cloud Trace:

    Ir a la API de Trace

  2. En la página API de Cloud Trace, si se muestra un botón etiquetado como Habilitar, haz clic en él. Si no se muestra este botón, la API de Cloud Trace está habilitada para el proyecto seleccionado.

Instala, inicializa y usa el cliente

OpenTelemetry ofrece tres maneras de instrumentar tu aplicación:

  • Instrumentación automática para aplicaciones de Node.js

    Cuando usas este enfoque, configuras la aplicación para incluir el SDK @opentelemetry/sdk-trace-node. Sin embargo, no es necesario que realices cambios en el código de ninguna de las bibliotecas que usas.

  • Seguimiento manual

    Cuando usas este enfoque, modificas las bibliotecas que usas para recopilar información de seguimiento.

  • Instrumentación automática para aplicaciones web

    Cuando usas este enfoque, configuras la aplicación para incluir el SDK @opentelemetry/sdk-trace-web. El SDK recopila datos de rendimiento del usuario, como la latencia y los seguimientos distribuidos, lo que te brinda información para diagnosticar problemas de frontend y supervisar el estado general de la aplicación.

En las siguientes secciones, se muestra el caso de uso de cada instrumentación.

Instrumentación automática

El módulo @opentelemetry/sdk-trace-node proporciona instrumentación automática para aplicaciones de Node.js.

La instrumentación automática identifica lo siguiente dentro de tu aplicación:

  • Frameworks, como Express
  • Protocolos comunes, como HTTP, HTTPS y gRPC
  • Bases de datos, como MySQL, MongoDB, Redis y PostgreSQL
  • Otras bibliotecas dentro de tu aplicación

La instrumentación automática proporciona seguimiento listo para usar, por lo que no necesitas realizar cambios en el código de ninguna de las bibliotecas que usas. El código de instrumentación realiza automáticamente las siguientes acciones:

  • Extrae un identificador de contexto de seguimiento de las solicitudes entrantes para permitir el seguimiento distribuido, si corresponde.
  • Garantiza que el contexto de seguimiento actual se propague mientras la transacción atraviesa una aplicación.
  • Agrega el identificador de seguimiento de contexto a las solicitudes salientes, lo que permite que el seguimiento distribuido continúe al siguiente salto, si corresponde.
  • Crea y finaliza los intervalos.

El módulo usa complementos para instrumentar automáticamente la aplicación a fin de producir intervalos y proporcionar un seguimiento de extremo a extremo con solo unas pocas líneas de código.

Instrumentación manual

El módulo de seguimiento manual, @opentelemetry/sdk-trace-base, proporciona control total sobre la instrumentación y creación de intervalos. No carga async_hooks. De forma predeterminada, no usa el almacenamiento local de continuación ni ningún complemento de instrumentación. El seguimiento manual tiene menos implicaciones de sobrecarga de rendimiento en comparación con el módulo de instrumentación automática.

Instrumentación automática para aplicaciones web

El módulo @opentelemetry/sdk-trace-web proporciona instrumentación automatizada y seguimiento para aplicaciones web. Recopila datos de rendimiento del usuario, como la latencia y los seguimientos distribuidos, lo que te brinda la información necesaria para diagnosticar problemas de frontend y supervisar el estado general de la aplicación.

Ejemplo

En las siguientes instrucciones, se muestra cómo usar el módulo de instrumentación automática para Compute Engine y Google Kubernetes Engine.

Compute Engine

Instala los siguientes paquetes:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Agrega el siguiente código a tu app para inicializar y registrar el exportador:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

GKE

Agrega lo siguiente a la sección Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Agrega el siguiente código a tu app para inicializar y registrar el exportador:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

Aplicación de ejemplo mediante el uso del framework de Express

La instrumentación de OpenTelemetry Express te permite recopilar automáticamente datos de seguimiento y exportarlos al backend que elijas, lo que te permite observar los sistemas distribuidos.

Para usar OpenTelemetry en aplicaciones que usan el framework Express, completa los siguientes pasos:

  1. Instala los siguientes paquetes:

    npm install --save @opentelemetry/instrumentation-http
npm install --save @opentelemetry/instrumentation-express

  2. Agrega el siguiente código a tu app, que carga todos los complementos compatibles:

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const provider = new NodeTracerProvider();

Para ver un ejemplo básico, consulta el ejemplo de OpenTelemetry Express.

Crea un intervalo personalizado

Puedes agregar información adicional al seguimiento creado por el sistema mediante la creación de un intervalo personalizado.

Para crear un intervalo personalizado, agrega lo siguiente al código fuente:


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
opentelemetry.trace.setGlobalTracerProvider(provider);
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();

  • getTracer muestra una instancia del rastreador, en la que basic es el nombre del rastreador o la biblioteca de instrumentación. Esto indica a OpenTelemetry quién está creando intervalos.

  • foo es el nombre del intervalo personalizado.

  • invoking work es el nombre del evento de muestra. Aquí se muestra cómo usar la API de addEvent.

Para ver un ejemplo básico de cómo crear un intervalo personalizado, consulta el ejemplo de OpenTelemetry.

Configura tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Ejecuta en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace.

Para obtener una lista de los entornos de Google Cloud compatibles, consulta Compatibilidad de entornos.

Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado:

  • Para obtener información sobre cómo configurar los niveles de acceso de tu entorno mediante Google Cloud Console, consulta Configura tu proyecto de Google Cloud.

  • Para los usuarios de gcloud, especifica los niveles de acceso con la marca --scopes y, también, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Ejecuta de forma local y en otros lugares

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe contener la función de agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.

Las bibliotecas cliente de Google Cloud usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación.

Puedes proporcionar estas credenciales de tres maneras:

  • Ejecución gcloud auth application-default login

  • Coloca la cuenta de servicio en una ruta predeterminada para tu sistema operativo. A continuación, se enumeran las rutas de acceso predeterminadas para Windows y Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta a tu cuenta de servicio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Cómo ver los seguimientos

Después de la implementación, puedes ver los seguimientos en el lector de seguimiento de Google Cloud Console.

Ir a la página del Lector de seguimiento

Soluciona problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a la página de solución de problemas.