Genera seguimientos y métricas con Node.js

En este documento, se describe cómo modificar una app de JavaScript de Node.js para recopilar datos de seguimiento y métricas con el framework de código abierto de OpenTelemetry y cómo escribir registros JSON estructurados en salida estándar. En este documento, también se proporciona información sobre una app de Node.js de muestra que puedes instalar y ejecutar. La app usa el framework web Fastify y está configurada para generar métricas, seguimientos y registros.

Información sobre la instrumentación manual y automática

Para este lenguaje, OpenTelemetry define la instrumentación automática como la práctica de recopilar telemetría de bibliotecas y frameworks sin realizar cambios en el código. Sin embargo, tienes módulos de instalación y estableces variables de entorno.

Este documento no describe información automática. Para obtener más información sobre ese tema, consulta Instrumentación automática para Node.

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

Antes de comenzar

Habilita las API de Cloud Logging, Cloud Monitoring, and Cloud Trace.

Habilita las API

Instrumenta tu app para recopilar seguimientos, métricas y registros

Si deseas instrumentar tu app para recopilar datos de seguimiento y métricas, y escribir JSON estructurado en la salida estándar, realiza los pasos que se describen en las siguientes secciones de este documento:

Configura OpenTelemetry
Configura tu app para precargar la configuración de OpenTelemetry
Configura el registro estructurado
Escribe registros estructurados

Configura OpenTelemetry

La configuración predeterminada del SDK de Node.js de OpenTelemetry exporta seguimientos mediante el protocolo OTLP. También configura OpenTelemetry para usar el formato de contexto de seguimiento W3C a fin de propagar el contexto de seguimiento. Esta configuración garantiza que los intervalos tengan la relación superior-secundaria correcta dentro de un seguimiento.

En la siguiente muestra de código, se ilustra un módulo JavaScript para configurar OpenTelemetry:


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 la muestra de código anterior, se configura OpenTelemetry para exportar métricas con el protocolo OTLP y se usa el paquete @opentelemetry/auto-instrumentations-node a fin de configurar todas las instrumentaciones de Node.js disponibles.

Para garantizar que se limpie toda la telemetría pendiente y que las conexiones se cierren de forma correcta antes de que la aplicación se cierre, el controlador SIGTERM llama a shutdown.

Para obtener más información y opciones de configuración, consulta Instrumentación automática de Node.js de OpenTelemetry.

Configura tu app para precargar la configuración de OpenTelemetry

Si deseas configurar la app para que escriba registros estructurados y recopile métricas y realice un seguimiento de los datos mediante OpenTelemetry, actualiza la invocación de la app a fin de precargar el módulo de instrumentación con la marca --require de Node.js. El uso de la marca --require garantiza que OpenTelemetry se inicialice antes de que se inicie la app. Si deseas obtener más información, consulta Primeros pasos con OpenTelemetry de Node.js.

En la siguiente muestra de código, se ilustra un Dockerfile que pasa la marca --require:

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

Configura el registro estructurado

Para incluir la información de seguimiento como parte de los registros con formato JSON escritos en el resultado estándar, configura tu aplicación para que genere registros estructurados en formato JSON. Fastify usa el framework de registro de Pino y proporciona un registrador en cada controlador de solicitudes. En la siguiente muestra de código, se ilustra un objeto LoggerOptions de Pino que configura la app para que genere registros estructurados 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, luego, agrega esa información como atributos al registro estructurado JSON. Estos atributos se pueden usar para correlacionar un registro con un seguimiento:

logging.googleapis.com/trace: el nombre del recurso del seguimiento asociado a la entrada de registro.
logging.googleapis.com/spanId: el ID de intervalo con el seguimiento asociado 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 estructura LogEntry.

Para usar la configuración Pino con Fastify, pasa el objeto de configuración del registrador cuando crees la app de Fastify:

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

Escribe registros estructurados

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

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

OpenTelemetry propaga de forma automática las entradas de registro de Pino con el contexto de intervalo del intervalo activo actual en el contexto de OpenTelemetry. Este contexto de intervalo se incluye en los registros JSON, como se describe en Configura el registro estructurado.

Ejecuta una app de ejemplo configurada para recopilar telemetría

La app de ejemplo usa formatos que no dependen de los proveedores, incluido JSON para los registros y OTLP para las métricas y los seguimientos, y el framework de Fastify. Para enrutar la telemetría a Google Cloud, esta muestra usa el Collector de OpenTelemetry configurado con los exportadores de Google. La app tiene dos extremos:

La función handleMulti controla el extremo /multi. El generador de cargas de la app envía solicitudes al extremo /multi. Cuando este extremo recibe una solicitud, envía entre tres y siete solicitudes al extremo /single en el 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';
});

La función handleSingle controla el extremo /single. Cuando este extremo recibe una solicitud, se suspende durante un retraso breve y, luego, 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`;
});

Descarga e implementa la app

Para ejecutar la muestra, haz lo siguiente:

En la consola de Google Cloud, activa Cloud Shell.

Activar Cloud Shell

En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

Clona el repositorio:

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

Ve al directorio de muestra:

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

Compila y ejecuta la muestra:

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

Si no ejecutas en Cloud Shell, ejecuta la aplicación con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS que apunta a un archivo de credenciales. Las credenciales predeterminadas de la aplicación 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

Consulta tus métricas

La instrumentación de OpenTelemetry en la app de ejemplo genera métricas de Prometheus que puedes ver mediante 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 del cliente y almacena los resultados en un histograma.

Para ver las métricas que genera la app de muestra, haz lo siguiente:

En la consola de Google Cloud, ve a la página Explorador de métricas:
Dirígete al Explorador de métricas

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.
En el elemento Métrica, expande el menú Seleccionar una métrica, ingresa http_server en la barra de filtros y, luego, usa los submenús para seleccionar un métrica y tipo de recurso específicos:
1. En el menú Recursos activos, elige Destino de Prometheus.
2. En el menú Categorías de métricas activas, elige Http.
3. En el menú Métricas activas, selecciona una métrica.
4. Haz clic en Aplicar.
Configura cómo se ven los datos.
Cuando las mediciones de una métrica son acumulativas, el Explorador de métricas normaliza automáticamente los datos medidos por el período de alineación, lo que hace que el gráfico muestre una frecuencia. Para obtener más información, consulta Categorías, tipos y conversiones.

Cuando se miden valores de números 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, establece el primer menú de la entrada Agregación como Ninguna.

Para obtener más información sobre la configuración de un gráfico, consulta elige métricas cuando uses el Explorador de métricas.

Ve tus seguimientos

Para ver tus datos de seguimiento, haz lo siguiente:

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

También puedes usar la barra de búsqueda para encontrar esta página.
En el gráfico de dispersión, selecciona un seguimiento con el URI de /multi.
En el diagrama de Gantt del panel Detalles de seguimiento, selecciona el intervalo etiquetado como /multi.

Se abre un panel que muestra información sobre la solicitud HTTP. Estos detalles incluyen el método, el código de estado, la cantidad de bytes y el usuario-agente del emisor.
Para ver los registros asociados con este seguimiento, selecciona la pestaña Registros y eventos.

La pestaña muestra registros individuales. Para ver los detalles de la entrada de registro, expande la entrada de registro. También puedes hacer clic en Ver registros y ver el registro con el Explorador de registros.

Si deseas obtener más información para usar el explorador de Cloud Trace, consulta Busca y explora seguimientos.

Mira los registros

En el Explorador de registros, puedes inspeccionar tus registros y, también, puedes ver los seguimientos asociados, cuando existen.

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

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
Ubica un registro con la descripción de handle /multi request.

Para ver los detalles del registro, expande la entrada de registro.
Haz clic en Seguimientos en una entrada de registro con el mensaje "Controla solicitudes múltiples" y, luego, selecciona Ver detalles de seguimiento.

Se abrirá el panel Detalles de seguimiento y se mostrará el seguimiento seleccionado.

Para obtener más información sobre el uso del Explorador de registros, consulta Visualiza registros con el Explorador de registros.