@observantic/sdk

The official Node.js SDK and zero-friction OpenTelemetry auto-instrumentation package for the Observantic observability platform.

⚡ Quick Start

1. Install

npm install @observantic/sdk

2. Initialize in your application

Initialize @observantic/sdk at the very top of your application entry point before importing express or other modules:

import { initObservantic } from "@observantic/sdk";

initObservantic({
  apiKey: "cw_live_sec_your_api_key_here",
  endpoint: "https://api.observantic.com",
  serviceName: "my-express-app",
  environment: "production",
});

import express from "express";

const app = express();

app.get("/users", (req, res) => {
  res.json({ message: "Hello Observantic!" });
});

app.listen(3000, () => console.log("Server running on port 3000"));

⚙️ Configuration

Programmatic Options (ObservanticOptions)

You can pass options directly into initObservantic(options):

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKey | string | process.env.OBSERVANTIC_API_KEY | Ingestion API key for your Observantic workspace. | | endpoint | string | https://api.observantic.com | Observantic base ingestion endpoint URL. | | serviceName | string | process.env.npm_package_name | "node-service" | Service name displayed in the Observantic dashboard. | | environment | string | process.env.NODE_ENV | "development" | Environment (e.g., production, staging). | | serviceVersion | string | process.env.npm_package_version | "1.0.0" | Version of your application. | | traceSampleRate | number | 1.0 | Sampling ratio from 0.0 (0%) to 1.0 (100%). | | autoShutdown | boolean | true | Automatically flush telemetry on SIGTERM and SIGINT. | | debug | boolean | false | Enable OpenTelemetry internal diagnostic logging. | | disabled | boolean | false | Disable all telemetry collection (e.g. in unit tests). | | headers | Record<string, string> | {} | Custom HTTP headers sent to the OTLP exporter. | | resourceAttributes | Record<string, any> | {} | Custom resource attributes attached to all spans/metrics/logs. | | batchTimeoutMillis | number | 5000 | Batch delay before flushing spans. | | signals | { traces?, metrics?, logs? } | All true | Selectively enable or disable individual telemetry signals. |

Environment Variables

Alternatively, configure the SDK entirely through environment variables without hardcoding secrets:

# Required authentication
export OBSERVANTIC_API_KEY="cw_live_sec_xxxxx"

# Optional overrides
export OBSERVANTIC_ENDPOINT="https://api.observantic.com"
export OBSERVANTIC_SERVICE_NAME="auth-service"
export OBSERVANTIC_ENVIRONMENT="production"
export OBSERVANTIC_SERVICE_VERSION="2.4.0"
export OBSERVANTIC_TRACE_SAMPLE_RATE="1.0"
export OBSERVANTIC_DEBUG="false"
export OBSERVANTIC_DISABLED="false"

Then initialize with zero arguments:

import { initObservantic } from "@observantic/sdk";

initObservantic();

🔍 Features

🚀 Express & Node.js Auto-Instrumentation

Automatically instruments HTTP requests, routes, middleware, and database operations without requiring manual span creation:

• Preserves Trace ID & Span ID across asynchronous workflows.
• Captures HTTP method, status codes, route templates, client IP, and query parameters.
• Records unhandled exceptions and errors automatically.

📊 Custom Tracing & OpenTelemetry API Re-exports

@observantic/sdk re-exports standard OpenTelemetry APIs (trace, context, metrics, logs, SpanStatusCode, SpanKind) so you don't need additional dependencies for manual instrumentation:

import { initObservantic, trace, SpanStatusCode } from "@observantic/sdk";

const client = initObservantic({ apiKey: "cw_live_sec_..." });
const tracer = client.getTracer("order-processor");

async function processOrder(orderId) {
  return await tracer.startActiveSpan("order.process", async (span) => {
    try {
      span.setAttribute("order.id", orderId);
      span.setAttribute("order.amount", 99.99);

      // Business logic
      const result = await saveToDatabase(orderId);
      return result;
    } catch (err) {
      span.recordException(err);
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
      throw err;
    } finally {
      span.end();
    }
  });
}

🤖 AI & LLM Observability (Generations)

Observantic provides first-class GenAI observability to track LLM completions, prompt inputs, generated outputs, token usage, and cost estimates. These calls are rendered with rich prompt/completion preview in the Observantic Tracing UI:

import { trackGeneration } from "@observantic/sdk";
import OpenAI from "openai";

const openai = new OpenAI();

const response = await trackGeneration({
  name: "chat.completion",
  model: "gpt-4o",
  system: "openai",
  input: "Summarize the latest AI trends in 2026",
  run: async (span) => {
    return await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Summarize the latest AI trends in 2026" }],
    });
  },
});

You can also attach AI attributes to an existing span:

import { recordGeneration } from "@observantic/sdk";

recordGeneration(span, {
  model: "claude-3-5-sonnet",
  system: "anthropic",
  input: promptText,
  output: completionText,
  tokens: { prompt: 150, completion: 320, total: 470 },
  cost: 0.005,
});

📈 Custom Metrics

import { metrics } from "@observantic/sdk";

const meter = metrics.getMeter("order-service");
const orderCounter = meter.createCounter("orders_total", {
  description: "Total number of completed orders",
});

orderCounter.add(1, { "order.type": "subscription" });

🛑 Graceful Shutdown

The SDK automatically registers shutdown handlers for SIGTERM and SIGINT to ensure all in-flight spans and metrics are flushed to Observantic before process exit.

You can also trigger shutdown manually:

import { shutdownObservantic } from "@observantic/sdk";

await shutdownObservantic();

🏗 Architecture

User Application (Express / Node.js)
      ↓
@observantic/sdk (initObservantic)
      ↓
OpenTelemetry NodeSDK
      ↓
OTLP HTTP Exporters (Traces, Logs, Metrics)
      ↓ (HTTP POST + Bearer Auth)
Observantic Ingestion (/v1/traces, /v1/logs, /v1/metrics)

• Standard OpenTelemetry protocol (OTLP/HTTP).
• Ingestion token sent via Authorization: Bearer <apiKey> and x-cw-token: <apiKey> headers.
• Zero vendor lock-in: compatible with the entire OpenTelemetry ecosystem.

📄 License

Apache-2.0