@ogcio/o11y-sdk-node v0.1.0-beta.12

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"
  }
}

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

Edit Active Span

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

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