Esta página se ha traducido con Cloud Translation API.

Ejemplo de instrumentación de Node.js

En este documento se describe cómo modificar una aplicación JavaScript de Node.js para recoger datos de trazas y métricas mediante el framework de código abierto OpenTelemetry, así como escribir registros JSON estructurados en la salida estándar. En este documento también se proporciona información sobre una aplicación de ejemplo de Node.js que puedes instalar y ejecutar. La aplicación usa el framework web Fastify y está configurada para generar métricas, trazas y registros.

Para obtener más información sobre la instrumentación, consulta los siguientes documentos:

Información sobre la instrumentación manual y sin código

En este lenguaje, OpenTelemetry define la instrumentación sin código como la práctica de recoger datos telemétricos de bibliotecas y frameworks sin tener que modificar el código. Sin embargo, sí puedes instalar módulos y definir variables de entorno.

En este documento no se describe la instrumentación sin código. Para obtener información sobre este tema, consulta Instrumentación con cero código de JavaScript.

Para obtener información general, consulta Instrumentación de OpenTelemetry para Node.

Antes de empezar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Instrumentar tu aplicación para recoger trazas, métricas y registros

Para instrumentar tu aplicación de forma que recoja datos de trazas y métricas, y para escribir JSON estructurado en la salida estándar, sigue los pasos que se describen en las secciones posteriores de este documento:

Configurar OpenTelemetry
Configurar la aplicación para precargar la configuración de OpenTelemetry
Configurar el almacenamiento de registros estructurado
Escribir registros estructurados

Configurar OpenTelemetry

La configuración predeterminada del SDK de OpenTelemetry Node.js exporta las trazas mediante el protocolo OTLP. También configura OpenTelemetry para que use el formato W3C Trace Context para propagar el contexto de seguimiento. Esta configuración asegura que los intervalos tengan la relación correcta entre elementos principales y secundarios en una traza.

El siguiente código de ejemplo muestra un módulo de JavaScript para configurar OpenTelemetry.

Para ver el ejemplo completo, haz clic en Más y, a continuación, selecciona Ver en GitHub.


diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

En el ejemplo de código anterior se configura OpenTelemetry para exportar métricas mediante el protocolo OTLP y se usa el paquete @opentelemetry/auto-instrumentations-node para configurar todas las instrumentaciones de Node.js disponibles.

Para asegurarse de que se vacía toda la telemetría pendiente y de que las conexiones se cierran correctamente antes de que se cierre la aplicación, el controlador SIGTERM llama a shutdown.

Para obtener más información y opciones de configuración, consulta Configuración de la instrumentación sin código.

Configurar la aplicación para precargar la configuración de OpenTelemetry

Para configurar la aplicación de forma que escriba registros estructurados y recoja métricas y datos de trazas mediante OpenTelemetry, actualiza la invocación de la aplicación para precargar el módulo de instrumentación con la marca --require de Node.js. Al usar la marca --require, te aseguras de que OpenTelemetry se inicialice antes de que se inicie tu aplicación. Para obtener más información, consulta el artículo Empezar a usar OpenTelemetry Node.js.

En el siguiente código de ejemplo se muestra un archivo Dockerfile que pasa la marca --require:

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

Configurar el almacenamiento de registros estructurado

Para incluir la información de la traza en los registros con formato JSON que se escriben en la salida estándar, configura tu aplicación para que genere registros estructurados en formato JSON. Fastify usa el framework de registro Pino y proporciona un registrador en cada controlador de solicitudes. El siguiente ejemplo de código muestra un objeto LoggerOptions de Pino que configura la aplicación para que genere registros estructurados en formato JSON:


// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

La configuración anterior extrae información sobre el intervalo activo del mensaje de registro y, a continuación, añade esa información como atributos al registro estructurado JSON. Estos atributos se pueden usar para correlacionar un registro con un rastreo:

logging.googleapis.com/trace: nombre de recurso de la traza asociada a la entrada de registro.
logging.googleapis.com/spanId: el ID del intervalo de la traza asociada a la entrada de registro.
logging.googleapis.com/trace_sampled: el valor de este campo debe ser true o false.

Para obtener más información sobre estos campos, consulta la LogEntry estructura.

Para usar la configuración de Pino con Fastify, pasa el objeto de configuración del registrador al crear la aplicación Fastify:

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

Escribir registros estructurados

Para escribir registros estructurados que enlacen a un rastreo, usa el Pino logger proporcionado por Fastify. Por ejemplo, en la siguiente instrucción se muestra cómo llamar al método Logger.info():

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry rellena automáticamente las entradas de registro de Pino con el contexto de span del span activo actual en el contexto de OpenTelemetry. Este contexto de intervalo se incluye en los registros JSON, tal como se describe en Configurar el registro estructurado.

Ejecutar una aplicación de ejemplo configurada para recoger telemetría

La aplicación de ejemplo usa formatos independientes del proveedor, como JSON para los registros y OTLP para las métricas y los rastreos, así como el framework Fastify. Para enrutar la telemetría a Google Cloud, en este ejemplo se usa OpenTelemetry Collector configurado con exportadores de Google. La aplicación tiene dos endpoints:

El endpoint /multi se gestiona con la función handleMulti. El generador de carga de la aplicación envía solicitudes al endpoint /multi. Cuando este endpoint recibe una solicitud, envía entre tres y siete solicitudes al endpoint /single del servidor local.

/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the handler body.
 */
fastify.get('/multi', async request => {
  const subRequests = randInt(3, 8);
  request.log.info({subRequests}, 'handle /multi request');

  for (let i = 0; i < subRequests; i++) {
    await axios.get(`http://localhost:${port}/single`);
  }
  return 'ok';
});

El endpoint /single se gestiona con la función handleSingle. Cuando este endpoint recibe una solicitud, espera un breve periodo y, a continuación, responde con una cadena.

/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 */
fastify.get('/single', async request => {
  // Sleep between 100-200 milliseconds
  const sleepMillis = randInt(100, 200);
  request.log.info({sleepMillis}, 'Going to sleep');
  await sleep(sleepMillis);
  return `slept ${sleepMillis}\n`;
});

Descargar y desplegar la aplicación

Para ejecutar la muestra, haz lo siguiente:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Clona el repositorio:

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js

Ve al directorio de ejemplo:

cd opentelemetry-operations-js/samples/instrumentation-quickstart

Compila y ejecuta el ejemplo:

docker compose up --abort-on-container-exit

Si no estás ejecutando la aplicación en Cloud Shell, hazlo con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS que apunte a un archivo de credenciales. Las credenciales de aplicación predeterminadas proporcionan un archivo de credenciales en $HOME/.config/gcloud/application_default_credentials.json.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Ver tus métricas

La instrumentación de OpenTelemetry en la aplicación de ejemplo genera métricas de Prometheus que puedes ver con el explorador de métricas:

Prometheus/http_server_duration_milliseconds/histogram Registra la duración de las solicitudes del servidor y almacena los resultados en un histograma.
Prometheus/http_client_duration_milliseconds/histogram Registra la duración de las solicitudes de cliente y almacena los resultados en un histograma.

En la Google Cloud consola, ve a la página Explorador de métricas:
Ve al explorador de métricas.

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.
En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
En el elemento Métrica, despliega el menú Seleccionar una métrica, introduce http_server en la barra de filtros y, a continuación, usa los submenús para seleccionar un tipo de recurso y una métrica específicos:
1. En el menú Recursos activos, selecciona Destino de Prometheus.
2. En el menú Categorías de métricas activas, selecciona Http.
3. En el menú Métricas activas, seleccione una métrica.
4. Haz clic en Aplicar.
Configure cómo se ven los datos.
Cuando las mediciones de una métrica son acumulativas, Explorador de métricas normaliza automáticamente los datos medidos por el periodo de alineación, lo que hace que el gráfico muestre una tasa. Para obtener más información, consulta Tipos, clases y conversiones.

Cuando se miden valores enteros o dobles, como con las dos métricas counter, el explorador de métricas suma automáticamente todas las series temporales. Para ver los datos de las rutas HTTP /multi y /single, defina el primer menú de la entrada Agregación como Ninguna.

Para obtener más información sobre cómo configurar un gráfico, consulta el artículo Seleccionar métricas al utilizar el explorador de métricas.

Ver tus trazas

Los datos de la traza pueden tardar varios minutos en estar disponibles. Por ejemplo, cuando tu proyecto recibe datos de traza, es posible que Google Cloud Observability tenga que crear una base de datos para almacenar esos datos. La creación de la base de datos puede tardar unos minutos. Durante ese periodo, no se podrá ver ningún dato de seguimiento.

Para ver los datos de la traza, haz lo siguiente:

En la Google Cloud consola, ve a la página Explorador de trazas:
Ir a Explorador de trazas

También puedes encontrar esta página mediante la barra de búsqueda.
En la sección de la tabla de la página, seleccione una fila con el nombre del intervalo /multi.
En el gráfico de Gantt del panel Detalles del rastreo, selecciona el intervalo etiquetado como /multi.

Se abrirá un panel con información sobre la solicitud HTTP. Estos detalles incluyen el método, el código de estado, el número de bytes y el agente de usuario de la persona que llama.
Para ver los registros asociados a este rastreo, selecciona la pestaña Registros y eventos.

En la pestaña se muestran los registros individuales. Para ver los detalles de la entrada de registro, despliégala. También puede hacer clic en Ver registros y consultar el registro con el Explorador de registros.

Para obtener más información sobre cómo usar el explorador de Cloud Trace, consulta Buscar y explorar trazas.

Consultar los registros

En Explorador de registros, puedes inspeccionar tus registros y ver las trazas asociadas, si las hay.

En la Google Cloud consola, ve a la página Explorador de registros:
Ve al Explorador de registros.

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.
Busca un registro con la descripción handle /multi request.

Para ver los detalles del registro, despliega la entrada.
En una entrada de registro con el mensaje "handle /multi request", haz clic en Trazas y, a continuación, selecciona Ver detalles de la traza.

Se abre el panel Detalles de la traza, donde se muestra la traza seleccionada.

Los datos de registro pueden estar disponibles varios minutos antes que los datos de la traza. Si se produce un error al ver los datos de seguimiento, ya sea buscando un seguimiento por ID o siguiendo los pasos de esta tarea, espera uno o dos minutos y vuelve a intentarlo.

Para obtener más información sobre cómo usar el Explorador de registros, consulta el artículo Ver registros con el Explorador de registros.