Node.js

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.

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
Yarn

npm install @hyperdx/node-opentelemetry

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
import

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Omítelo en Managed ClickStack
    service: 'my-service'
});

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    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
Pino
console.log

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;

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;

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
Koa
Manual

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    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);

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    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);

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:

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
Punto de entrada personalizado (p. ej., Nodemon, ts-node, etc.)
Importación de código

Managed ClickStackPuedes omitir HYPERDX_API_KEY en Managed ClickStack.

HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' npx opentelemetry-instrument index.js

Managed ClickStackPuedes omitir HYPERDX_API_KEY en Managed ClickStack.

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

// 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:

Primeros pasos

Funcionalidades

Gestionar ClickStack

Guías

Socios de integración

Primeros pasos

Instalar el paquete de instrumentación de OpenTelemetry de HyperDX

Inicialización del SDK

Configurar la recopilación de logs

Configurar la recopilación de errores

Solución de problemas

Configuración avanzada de la instrumentación

Capturar logs de la consola

Añadir información de usuario o metadatos

Google Cloud Run

Bibliotecas instrumentadas automáticamente

Instalación alternativa

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

Activar la captura de excepciones

Bibliotecas instrumentadas automáticamente

​Primeros pasos

​Instalar el paquete de instrumentación de OpenTelemetry de HyperDX

​Inicialización del SDK

​Configurar la recopilación de logs

​Configurar la recopilación de errores

​Solución de problemas

​Configuración avanzada de la instrumentación

​Capturar logs de la consola

​Añadir información de usuario o metadatos

​Google Cloud Run

​Bibliotecas instrumentadas automáticamente

​Instalación alternativa

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

​Activar la captura de excepciones

​Bibliotecas instrumentadas automáticamente

Primeros pasos

Instalar el paquete de instrumentación de OpenTelemetry de HyperDX

Inicialización del SDK

Configurar la recopilación de logs

Configurar la recopilación de errores

Solución de problemas

Configuración avanzada de la instrumentación

Capturar logs de la consola

Añadir información de usuario o metadatos

Google Cloud Run

Bibliotecas instrumentadas automáticamente

Instalación alternativa

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

Activar la captura de excepciones

Bibliotecas instrumentadas automáticamente