@opens/observability

Overview

@opens/observability is a lightweight wrapper over popular instrumentation agents like Elasticsearch APM and OpenTelemetry. It provides a unified API to set up and use tracing, making it easier to integrate observability into your application.

Features

• Supports Elastic APM and OpenTelemetry.
• Provides a unified API for tracing.
• Allows custom logging levels.
• Enables function instrumentation with tracing.
• Supports flexible configuration options.

Installation

When using Elastic APM

npm install elastic-apm-node @opens/observability

Usage

Setting Up the Tracer

You need to configure the observer before using it.

import { observer, TRACE_PROVIDER, LOG_LEVEL_TYPES } from "@opens/observability";

observer.setup({
  provider: TRACE_PROVIDER.APM, // Use TRACE_PROVIDER.OTEL for OpenTelemetry
  logLevel: LOG_LEVEL_TYPES.INFO, // Set log level (DEBUG, INFO, WARN, ERROR) - Optional
  config: {
    serviceName: "my-service",
    serverUrl: "http://localhost:8200", // Elastic APM Server URL,
    secretToken: '<secretToken from your Elastic Stack deployment>',
    environment: '...', // https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#environment
  },
});

Instrumenting a Function

Wrap a function with tracing using instrumentFunc.

const tracedFunction = observer.tracer.instrumentFunc(
  { name: "fetchData", type: "custom" },
  async () => {
    console.log("Fetching data...");
    return "Data retrieved";
  }
);

tracedFunction().then(console.log);

Available Constants

TRACE_PROVIDER

• TRACE_PROVIDER.APM → Uses Elastic APM for tracing.
• TRACE_PROVIDER.OTEL → Uses OpenTelemetry for tracing.

LOG_LEVEL_TYPES

• DEBUG
• INFO
• WARN
• ERROR

Configuration

You can pass a configuration object when setting up the tracer. The configuration varies depending on the provider:

Elastic APM Configuration

{
  serviceName: "my-service",
  secretToken: "my-secret",
  serverUrl: "http://localhost:8200",
}

OpenTelemetry Configuration

{
  resource: { serviceName: "my-otel-service" }
}

License

MIT