Observability NodeJS SDK

The NodeJS observability sdk is a npm package used to setup and implement opentelemetry instrumentation.

Installation

pnpm

pnpm i --save @ogcio/o11y-sdk-node

npm

npm i @ogcio/o11y-sdk-node

Usage

Setup using constructor function

// instrumentation.ts

import("@ogcio/o11y-sdk-node/lib/index").then((sdk) =>
  sdk.instrumentNode({
    serviceName: "node-microservice",
    collectorUrl: "http://localhost:4317",
    resourceAttributes: {
      "team.infra.cluster": "dev-01",
      "team.infra.pod": "01",
      "team.service.type": "fastify",
    },
    spanAttributes: {
      "signal.namespace": "documentation",
    },
    ignoreUrls: [{ type: "equals", url: "/api/health" }],
  }),
);

Run your node script with instrumentation

node --import instrumentation.js server.js

Or setup inside your package.json

{
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "start": "node --env-file=.env --import ./dist/instrumentation.js dist/index.js"
  }
}

Traces

Span Customization

It is possible to customize spans such as traces and logs globally or in a single code statement using predefined functions.

Global Configuration

In the SDK configuration, you can set the following properties:

• spanAttributes Object containing static properties or functions used to evaluate custom attributes for every logs and traces.
• resourceAttributes Object containing static properties used as resources attributes for any signal.
• traceRatio Faction value from 0 to 1, used by TraceIdRatioBasedSampler which it deterministically samples a percentage of traces that you pass in as a parameter.

function generateRandomString(): string {
  return Math.random() + "_" + Date.now();
}

instrumentNode({
  resourceAttributes: {
    "property.name.one": "value_one",
    "property.name.two": "value_two",
  },
  spanAttributes: {
    "custom.span.value": "example",
    "custom.span.value_with_function": generateRandomString,
  },
});

PII Detection

By default the sdk detect and redact email PII from traces and logs

example:

input: user access: [email protected]
output: user access: [REDACTED EMAIL]

You can disable PII detection with detection object inside NodeSDKConfig

instrumentNode({
  detection: {
    email: false,
  },
});

PII Detection

By default the sdk detect and redact email PII from traces and logs

example:

input: user acces: [email protected]
output: user access: [REDACTED EMAIL]

You can disable PII detection with detection object inside NodeSDKConfig

instrumentNode({
  detection: {
    email: false,
  },
});

Utils:

• withSpan:

  Key Features

  • Automatic Span Management: Spans are automatically started, ended, and their status is set based on execution success or failure
    • Exception Recording: Errors are automatically recorded with proper span status codes
    • Flexible Configuration: Support for custom tracer names, span options, and attributes
    • Promise Support: Works seamlessly with both synchronous and asynchronous functions
    • Nested Tracing: Spans created within existing trace contexts automatically become child spans

  Usage:

  import { SpanOptions } from "@opentelemetry/api";
  
  export type WithSpanParams<T> = {
    /**
     * The name of the trace the span should belong to.
     * NOTE: If you want the new span to belong to an already existing trace, you should provide the same tracer name
     */
    traceName?: string;
    spanName: string;
    spanOptions?: SpanOptions;
    /** A function defining the task you want to be wrapped by this span */
    fn: (span: Span) => T | Promise<T>;
  };

  examples:

  Creating a Top-Level Trace (e.g. Worker Job)

  Use to create a top-level trace for background jobs, workers, or any standalone operations: withSpan

  import { withSpan } from "@ogcio/o11y-sdk-node";
  
  async function processEmailQueue() {
    return withSpan({
      traceName: "email-worker",
      spanName: "process-email-queue",
      fn: async (span) => {
        // Your worker logic here
        const emails = await fetchPendingEmails();
        span.setAttributes({
          "email.count": emails.length,
          "worker.batch.id": generateBatchId(),
        });
  
        for (const email of emails) {
          await sendEmail(email);
        }
  
        return { processed: emails.length };
      },
    });
  }

  Nesting Spans Inside Existing Traces

  Create child spans within existing trace contexts to provide detailed operation breakdown:

  async function orderProcessing(orderId: string) {
    return withSpan({
      spanName: "process-order",
      fn: async (parentSpan) => {
        // Child span for validation
        const validation = await withSpan({
          spanName: "validate-order",
          fn: async (span) => {
            span.setAttribute("order.id", orderId);
            return await validateOrder(orderId);
          },
        });
        // Child span for payment
        const payment = await withSpan({
          spanName: "process-payment",
          fn: async (span) => {
            span.setAttribute("payment.amount", validation.amount);
            return await processPayment(orderId, validation.amount);
          },
        });
  
        parentSpan.setAttributes({
          "order.status": "completed",
          "order.total": payment.amount,
        });
  
        return { orderId, status: "completed" };
      },
    });
  }

• getActiveSpan:

  Using getActiveSpan function, you can access to current transaction span and customize it.

  Examples:

  Edit Active Span

  You can use the function everywhere in your code, and set some custom attributes that are enabled for that single span

  import { getActiveSpan } from "@ogcio/o11y-sdk-node";
  
  async function routes(app: FastifyInstance) {
    app.get("/", async (req, reply) => {
      // validation and business logic
  
      // set span attribute
      getActiveSpan()?.setAttribute("business.info", "dummy");
  
      reply.status(200).send(response);
    });
  }

Sending Custom Metrics

This package gives the possibility to send custom metrics and define them as desired in the code, you can choose between sync metrics and observable async metrics.

To use this functionality, you only need to import getMetric and enable the application instrumentation.

import { getMetric } from "@ogcio/o11y-sdk-node";

Sync

Sync metrics are signals sent when the function has been called.

Creating a counter, there are 2 types of counter:

• counter a simple counter that can only add positive numbers
• updowncounter counter that support also negative numbers

const counter = getMetric("counter", {
  attributeName: "counter",
  metricName: "fastify-counter",
});

counter.add(1, {
  my: "my",
  custom: "custom",
  attributes: "attributes",
});

Creating a Histogram

const histogram = getMetric("histogram", {
  metricName: "response_duration",
  attributeName: "http_response",
  options: {
    advice: {
      explicitBucketBoundaries: [0, 100, 200, 500, 1000],
    },
    description: "Response durations",
  },
});

histogram.record(120, { path: "/home" });

Async

Async metrics are called by the scraper collector to read current data using the Observable pattern. Creating an async metric means that the application will subscribe to the observability URL and record data on call (default 60s).

keep in mind, you can't send signals on-demand with this component

Creating an async Gauge

const asyncGauge = getMetric("async-gauge", {
  metricName: "cpu_usage",
  attributeName: "server_load",
  options: { unit: "percentage" },
}).addCallback((observer) => {
  observer.observe(50, { host: "server1" });
});

Creating an async Counter

getMetric("async-counter", {
  attributeName: "scraped-memory",
  metricName: "fastify-counter",
}).addCallback((observer) => {
  observer.observe(freemem(), {
    "application.os.memory": "free-memory",
  });
});

API Reference

Protocol

protocol is a string parameter used to define how to send signals to observability infrastructure

• grpc Use gRPC protocol, usually default port use 4317. Is the most performant option for server side applications.
• http Use HTTP standard protocol, usually default port use 4318. Mainly used on web or UI client applications.
• console Used for debugging sending signals to observability cluster, every information will be printed to your runtime console.

Shared Types

export type SDKLogLevel =
  | "NONE"
  | "ERROR"
  | "WARN"
  | "INFO"
  | "DEBUG"
  | "VERBOSE"
  | "ALL";

Config

| Parameter | Type | Description | | :--------------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------- | | collectorUrl | string | Required. The opentelemetry collector entrypoint url, if null, instrumentation will not be activated | | serviceName | string | Name of your application used for the collector to group logs | | diagLogLevel | SDKLogLevel | Diagnostic log level for the internal runtime instrumentation | | collectorMode | single \| batch | Signals sending mode, default is batch for performance | | enableFS | boolean | Deprecated. Use autoInstrumentationConfig instead. Flag to enable or disable the tracing for node:fs module | | autoInstrumentationConfig | InstrumentationConfigMap | Configuration object for auto instrumentations. Default: {"@opentelemetry/instrumentation-fs":{enabled:false}} | | additionalInstrumentations | Instrumentation[] | Additional custom instrumentations to be added to the NodeSDK. Default: [] | | protocol | string | Type of the protocol used to send signals |