Node.js

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

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

npm install @hyperdx/node-opentelemetry 

yarn add @hyperdx/node-opentelemetry 

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

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 * 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.

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).

    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;

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;

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.

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);

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);

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);
}

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

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.

export HDX_NODE_CONSOLE_CAPTURE=0

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

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.

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

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.

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

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

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

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.

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