Node.js

SDK para Node.js do ClickStack - A stack de observabilidade do ClickHouse

O ClickStack usa o padrão OpenTelemetry para coletar dados de telemetria (logs, métricas, traces e exceções). Os traces são gerados automaticamente por instrumentação automática, portanto não é necessário fazer instrumentação manual para aproveitar o tracing.

Este guia integra:

• Logs
• Métricas
• Traces
• Exceções

​

Primeiros passos

​

Instale o pacote de instrumentação OpenTelemetry da HyperDX

Use o comando a seguir para instalar o pacote OpenTelemetry do ClickStack.

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

Inicializando o SDK

Para inicializar o SDK, você precisará chamar a função init no início do ponto de entrada da sua aplicação.

require

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

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Omita no 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', // Omita no Managed ClickStack
    service: 'my-service'
});

Isso capturará automaticamente tracing, métricas e logs da sua aplicação Node.js.

​

Configurar a coleta de logs

Por padrão, os logs de console.* são coletados. Se você estiver usando um logger como winston ou pino, precisará adicionar um transport ao logger para enviar logs ao ClickStack. Se estiver usando outro tipo de logger, entre em contato ou explore uma de nossas integrações de plataforma, se aplicável (como Kubernetes).

Winston

Se você estiver usando winston como logger, precisará adicionar o transport abaixo ao 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', { // Envia logs de info e superiores
          detectResources: true,
        }),
      ],
    });

    export default logger;

Pino

Se você estiver usando pino como logger, precisará adicionar o transport abaixo ao logger e especificar um mixin para correlacionar logs com traces.

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

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

export default logger;

console.log

Por padrão, os métodos console.* têm suporte nativo. Nenhuma configuração adicional é necessária.

Você pode desativar isso definindo a variável de ambiente HDX_NODE_CONSOLE_CAPTURE como 0 ou passando consoleCapture: false para a função init.

​

Configurar a coleta de erros

O SDK do ClickStack pode capturar automaticamente exceções não tratadas e erros na sua aplicação com stack trace completo e contexto do código.

Para habilitar esse recurso, você precisará adicionar o código abaixo ao final do middleware de tratamento de erros da sua aplicação ou capturar exceções manualmente usando a função recordException.

Express

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

// Adicione suas rotas etc.

// Adicione isto após todas as rotas,
// mas antes de definir qualquer outro middleware de tratamento de erros
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', // Omita para Managed ClickStack
    service: 'my-service'
});

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

HyperDX.setupKoaErrorHandler(app);

// Adicione suas rotas etc.

app.listen(3030);

Manual

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

function myErrorHandler(error, req, res, next) {
    // Isto pode ser usado em qualquer lugar da sua aplicação
    HyperDX.recordException(error);
}

​

Solução de problemas

Se você estiver tendo problemas com o SDK, pode ativar o logging detalhado definindo a variável de ambiente OTEL_LOG_LEVEL como debug.

export OTEL_LOG_LEVEL=debug

​

Configuração avançada de instrumentação

​

Capturar logs do console

Por padrão, o SDK do ClickStack captura logs do console. Você pode desativar isso definindo a variável de ambiente HDX_NODE_CONSOLE_CAPTURE como 0.

copy

export HDX_NODE_CONSOLE_CAPTURE=0

​

Adicionar informações do usuário ou metadados

Para marcar facilmente todos os eventos relacionados a um determinado atributo ou identificador (ex.: ID do usuário ou e-mail), você pode chamar a função setTraceAttributes, que marcará cada log/span associado ao trace atual após a chamada com os atributos declarados. Recomenda-se chamar essa função o mais cedo possível dentro de uma determinada requisição/trace (ex.: o quanto antes na pilha de middlewares do Express).

Essa é uma forma prática de garantir que todos os logs/spans sejam marcados automaticamente com os identificadores corretos para facilitar pesquisas posteriores, em vez de precisar marcar e propagar os identificadores manualmente.

userId, userEmail, userName e teamName preencherão a UI de sessões com os valores correspondentes, mas podem ser omitidos. Quaisquer outros valores adicionais podem ser especificados e usados para pesquisar eventos.

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

app.use((req, res, next) => {
  // Obtém informações do usuário a partir da requisição...

  // Anexa informações do usuário ao trace atual
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

Certifique-se de ativar o modo beta definindo a variável de ambiente HDX_NODE_BETA_MODE como 1 ou passando betaMode: true para a função init, para habilitar os atributos de trace.

export HDX_NODE_BETA_MODE=1

​

Google Cloud Run

Se você executa sua aplicação no Google Cloud Run, o Cloud Trace injeta automaticamente cabeçalhos de amostragem nas solicitações de entrada, o que atualmente limita a amostragem de traces a 0,1 solicitação por segundo por instância.

Por padrão, o pacote @hyperdx/node-opentelemetry substitui a taxa de amostragem para 1,0.

Para alterar esse comportamento ou configurar outras instalações do OpenTelemetry, você pode definir manualmente as variáveis de ambiente OTEL_TRACES_SAMPLER=parentbased_always_on e OTEL_TRACES_SAMPLER_ARG=1 para obter o mesmo resultado.

Para saber mais e forçar o tracing de solicitações específicas, consulte a documentação do Google Cloud Run.

​

Bibliotecas com instrumentação automática

As bibliotecas a seguir serão instrumentadas automaticamente para rastreamento pelo SDK:

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

​

Instalação alternativa

​

Execute a aplicação com a CLI OpenTelemetry do ClickStack

Como alternativa, você pode instrumentar automaticamente sua aplicação sem precisar alterar o código usando a CLI opentelemetry-instrument ou a flag --require do Node.js. A instalação da CLI oferece uma variedade maior de bibliotecas e frameworks com instrumentação automática.

Usando NPX

Managed ClickStack

A HYPERDX_API_KEY pode ser omitida no Managed ClickStack.

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

Ponto de entrada personalizado (ex.: Nodemon, ts-node etc.)

Managed ClickStack

A HYPERDX_API_KEY pode ser omitida no 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

Importação de código

// Importe isto no início do primeiro arquivo carregado pela sua aplicação
// Você ainda deverá especificar sua API key por meio da variável de ambiente `HYPERDX_API_KEY`
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // opcional, padrão: true
    additionalInstrumentations: [], // opcional, padrão: []
});

A variável de ambiente OTEL_SERVICE_NAME é usada para identificar seu serviço no HyperDX e pode ter qualquer nome que você quiser.

​

Habilitando a captura de exceções

Para habilitar a captura de exceções não tratadas, defina a variável de ambiente HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE como 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

Depois, para capturar automaticamente exceções do Express, do Koa ou capturá-las manualmente, siga as instruções na seção Configurar a coleta de erros acima.

​

Bibliotecas com instrumentação automática

As bibliotecas a seguir serão instrumentadas automaticamente (com rastreamento) pelos métodos de instalação acima:

• amqplib
• AWS Lambda Functions
• 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