Node.js

SDK de Node.js para ClickStack - El stack de observabilidad de ClickHouse

ClickStack utiliza el estándar OpenTelemetry para recopilar datos de telemetría (logs, métricas, trazas y excepciones). Las trazas se generan automáticamente mediante instrumentación automática, por lo que no es necesario instrumentar manualmente para obtener valor de las trazas.

Esta guía integra:

• Logs
• Métricas
• Trazas
• Excepciones

​

Primeros pasos

​

Instalar el paquete de instrumentación de OpenTelemetry de HyperDX

Utiliza el siguiente comando para instalar el paquete de OpenTelemetry de ClickStack.

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

Inicialización del SDK

Para inicializar el SDK, debes llamar a la función init al inicio del punto de entrada de tu aplicación.

require

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omítelo en Managed ClickStack
    service: 'my-service'
});

import

import * as HyperDX from '@hyperdx/node-opentelemetry';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omítelo en Managed ClickStack
    service: 'my-service'
});

Esto capturará automáticamente trazas, métricas y logs de tu aplicación Node.js.

​

Configurar la recopilación de logs

De forma predeterminada, se recopilan los logs de console.*. Si usas un logger como winston o pino, tendrás que añadir un transporte a tu logger para enviar logs a ClickStack. Si usas otro tipo de logger, contacta con nosotros o explora una de nuestras integraciones de plataforma, si corresponde (como Kubernetes).

Winston

Si usas winston como logger, tendrás que añadir el siguiente transporte a tu logger.

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // Enviar logs de nivel info y superiores
          detectResources: true,
        }),
      ],
    });

    export default logger;

Pino

Si usas pino como logger, tendrás que añadir el siguiente transporte a tu logger y especificar un mixin para correlacionar los logs con las trazas.

import pino from 'pino';
import * as HyperDX from '@hyperdx/node-opentelemetry';

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // Enviar logs de nivel info y superiores
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

console.log

De forma predeterminada, los métodos console.* se admiten de forma nativa. No se requiere ninguna configuración adicional.

Puedes desactivar esto estableciendo la variable de entorno HDX_NODE_CONSOLE_CAPTURE en 0 o pasando consoleCapture: false a la función init.

​

Configurar la recopilación de errores

El SDK de ClickStack puede capturar automáticamente excepciones no capturadas y errores en su aplicación, con la traza de pila completa y el contexto del código.

Para habilitarlo, deberá añadir el siguiente código al final del middleware de gestión de errores de su aplicación o capturar manualmente las excepciones mediante la función recordException.

Express

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omitir para Managed ClickStack
    service: 'my-service'
});
const app = express();

// Añada sus rutas, etc.

// Añada esto después de todas las rutas,
// pero antes de definir cualquier otro middleware de gestión de errores
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

Koa

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omitir para Managed ClickStack
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

// Añada sus rutas, etc.

app.listen(3030);

Manual

const HyperDX = require('@hyperdx/node-opentelemetry');

function myErrorHandler(error, req, res, next) {
    // Esto puede usarse en cualquier parte de su aplicación
    HyperDX.recordException(error);
}

​

Solución de problemas

Si tienes problemas con el SDK, puedes habilitar el registro detallado configurando la variable de entorno OTEL_LOG_LEVEL en debug.

export OTEL_LOG_LEVEL=debug

​

Configuración avanzada de la instrumentación

​

Capturar logs de la consola

De forma predeterminada, el SDK de ClickStack capturará los logs de la consola. Puede desactivarlo estableciendo la variable de entorno HDX_NODE_CONSOLE_CAPTURE en 0.

copy

export HDX_NODE_CONSOLE_CAPTURE=0

​

Añadir información de usuario o metadatos

Para etiquetar fácilmente todos los eventos relacionados con un atributo o identificador determinado (p. ej., id. de usuario o correo electrónico), puede llamar a la función setTraceAttributes, que etiquetará cada log/span asociado a la traza actual tras la llamada con los atributos indicados. Se recomienda llamar a esta función lo antes posible dentro de una solicitud o traza determinadas (p. ej., lo antes posible en la pila de middleware de Express).

Esta es una forma práctica de garantizar que todos los logs/spans queden etiquetados automáticamente con los identificadores correctos para poder buscarlos más adelante, en lugar de tener que etiquetar y propagar los identificadores manualmente.

userId, userEmail, userName y teamName rellenarán la UI de sesiones con los valores correspondientes, pero pueden omitirse. Cualquier otro valor adicional puede especificarse y usarse para buscar eventos.

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // Obtener información del usuario de la solicitud...

  // Adjuntar información del usuario a la traza actual
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

Asegúrese de habilitar el modo Beta configurando la variable de entorno HDX_NODE_BETA_MODE en 1 o pasando betaMode: true a la función init para habilitar los atributos de trazas.

export HDX_NODE_BETA_MODE=1

​

Google Cloud Run

Si ejecutas tu aplicación en Google Cloud Run, Cloud Trace inyecta automáticamente encabezados de muestreo en las solicitudes entrantes, lo que actualmente limita el muestreo de trazas a 0,1 solicitudes por segundo por instancia.

El paquete @hyperdx/node-opentelemetry establece la frecuencia de muestreo en 1.0 de forma predeterminada.

Para cambiar este comportamiento o configurar otras instalaciones de OpenTelemetry, puedes configurar manualmente las variables de entorno OTEL_TRACES_SAMPLER=parentbased_always_on y OTEL_TRACES_SAMPLER_ARG=1 para lograr el mismo resultado.

Para obtener más información y forzar el trazado de solicitudes específicas, consulta la documentación de Google Cloud Run.

​

Bibliotecas instrumentadas automáticamente

El SDK instrumentará automáticamente (generará trazas de) las siguientes bibliotecas:

• dns
• express
• graphql
• hapi
• http
• ioredis
• knex
• koa
• mongodb
• mongoose
• mysql
• mysql2
• net
• pg
• pino
• redis
• winston

​

Instalación alternativa

​

Ejecutar la aplicación con la CLI de OpenTelemetry de ClickStack

Como alternativa, puedes instrumentar automáticamente tu aplicación sin necesidad de hacer cambios en el código usando la CLI opentelemetry-instrument o la opción --require de Node.js. La instalación de la CLI ofrece una gama más amplia de bibliotecas y frameworks con instrumentación automática.

Con NPX

Managed ClickStack

Puedes omitir HYPERDX_API_KEY en Managed ClickStack.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

Punto de entrada personalizado (p. ej., Nodemon, ts-node, etc.)

Managed ClickStack

Puedes omitir HYPERDX_API_KEY en Managed ClickStack.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

Importación de código

// Importa esto al principio del primer archivo que se carga en tu aplicación
// Seguirás especificando tu clave de API mediante la variable de entorno `HYPERDX_API_KEY`
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // opcional, valor predeterminado: true
    additionalInstrumentations: [], // opcional, valor predeterminado: []
});

La variable de entorno OTEL_SERVICE_NAME se usa para identificar tu servicio en la aplicación de HyperDX; puede ser cualquier nombre que quieras.

​

Activar la captura de excepciones

Para activar la captura de excepciones no controladas, deberás establecer la variable de entorno HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE en 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

Después, para capturar automáticamente las excepciones de Express o Koa, o para capturarlas manualmente, sigue las instrucciones de la sección Configurar la recopilación de errores anterior.

​

Bibliotecas instrumentadas automáticamente

Las siguientes bibliotecas se instrumentarán automáticamente (con trazas) mediante los métodos de instalación anteriores:

• amqplib
• Funciones de AWS Lambda
• aws-sdk
• bunyan
• cassandra-driver
• connect
• cucumber
• dataloader
• dns
• express
• fastify
• generic-pool
• graphql
• grpc
• hapi
• http
• ioredis
• knex
• koa
• lru-memoizer
• memcached
• mongodb
• mongoose
• mysql
• mysql2
• nestjs-core
• net
• pg
• pino
• redis
• restify
• socket.io
• winston