Node.js

HyperDX uses the OpenTelemetry standard for collecting telemetry data (logs and traces). Traces are auto-generated with automatic instrumentation, so manual instrumentation isn't required to get value out of tracing.

This Guide Integrates:

✅ Logs

✅ Metrics

✅ Traces

Getting Started

Install HyperDX OpenTelemetry Instrumentation Package

Use the following command to install the HyperDX OpenTelemetry package (opens in a new tab).

NPM

Yarn

npm install @hyperdx/node-opentelemetry

yarn add @hyperdx/node-opentelemetry

Add The Logger Transport

To collect logs from your application, you'll need to add a few lines of code to configure your logging module. If you're using another type of logger, reach out or explore one of our platform integrations if applicable (such as Kubernetes or Fly.io)

console.log

Winston

Pino

By default, `console.*` methods are supported out of the box. No additional configuration is required.

If you're using `winston` as your logger, you'll need to add the following transport to your logger.

import winston from 'winston';
import { getWinsonTransport } from '@hyperdx/node-opentelemetry';
 
const MAX_LEVEL = 'info';
 
const logger = winston.createLogger({
  level: MAX_LEVEL,
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    getWinsonTransport(MAX_LEVEL), // append this to the existing transports
  ],
});
 
export default logger;

If you're using `pino` as your logger, you'll need to add the following transport to your logger.

import pino from 'pino';
import { getPinoTransport } from '@hyperdx/node-opentelemetry';
 
const MAX_LEVEL = 'info';
 
const logger = pino(
  pino.transport({
    targets: [
      getPinoTransport(MAX_LEVEL),
      // other transports
    ],
  }),
);

Run the Application with HyperDX OpenTelemetry CLI

Using NPX

Custom Entry Point (ex. Nodemon, ts-node, etc.)

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

The OTEL_SERVICE_NAME environment variable is used to identify your service in the HyperDX app, it can be any name you want.

Advanced Configuration

(Optional) Advanced Instrumentation Configuration

Capture Console Logs

By default, the HyperDX SDK will capture console logs. You can disable it by setting HDX_NODE_CONSOLE_CAPTURE environment variable to 0.

export HDX_NODE_CONSOLE_CAPTURE=0

Advanced Network Capture

By enabling advanced network capture, the SDK will additionally capture full HTTP request/response headers and bodies for all inbound/outbound HTTP requests, to help with more in-depth request debugging. This can be accomplished by setting HDX_NODE_ADVANCED_NETWORK_CAPTURE environment variable to 1.

export HDX_NODE_ADVANCED_NETWORK_CAPTURE=1

By default, all request/response headers will be captured. You can specify a custom list of headers to capture by setting OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST, OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE, OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST, OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE environment variable to a comma-separated list of headers.

For example:

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST=authorization,accept

(Optional) Attach User Information or Metadata - BETA

To easily tag all events related to a given attribute or identifier (ex. user id or email), you can call the setTraceAttributes function which will tag every log/span associated with the current trace after the call with the declared attributes. It's recommended to call this function as early as possible within a given request/trace (ex. as early in an Express middleware stack as possible).

This is a convenient way to ensure all logs/spans are automatically tagged with the right identifiers to be searched on later, instead of needing to manually tagging and propagating identifiers yourself.

userId, userEmail, userName, and teamName will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events.

import { setTraceAttributes } from '@hyperdx/node-opentelemetry';
 
app.use((req, res, next) => {
  // Get user information from the request...
 
  // Attach user information to the current trace
  setTraceAttributes({
    userId,
    userEmail,
  });
  next();
});

Then enable HyperDX beta mode by setting HDX_NODE_BETA_MODE environment variable to 1.

export HDX_NODE_BETA_MODE=1

Google Cloud Run

If you're running your application on Google Cloud Run, Cloud Trace automatically injects sampling headers into incoming requests, currently restricting traces to be sampled at 0.1 requests per second for each instance.

The @hyperdx/node-opentelemetry package overwrites the sample rate to 1.0 by default.

To change this behavior, or to configure other OpenTelemetry installations, you can manually configure the environment variables OTEL_TRACES_SAMPLER=parentbased_always_on and OTEL_TRACES_SAMPLER_ARG=1 to achieve the same result.

To learn more, and to force tracing of specific requests, please refer to the Google Cloud Run documentation (opens in a new tab).

Next.js Python