@observability-os/sdk

@observability-os/sdk

Zero-dependency TypeScript logger SDK for ObservabilityOS — an AI-native DevOps intelligence and log analytics platform.

Features

• Zero runtime dependencies — uses only built-in fetch, setInterval, clearInterval
• Batch-and-flush architecture — logs are queued in memory and flushed when the batch size or flush interval is reached
• Automatic retry — failed API calls re-queue logs for the next flush attempt
• Timer safety — flush interval uses .unref() so it doesn't block Node.js process exit
• TypeScript first — full type definitions included

Installation

npm install @observability-os/sdk
# or
yarn add @observability-os/sdk
# or
pnpm add @observability-os/sdk

Quick Start

import { Logger } from "@observability-os/sdk";

const logger = new Logger({
  apiKey: "your-api-key",
  defaultService: "my-app",
  defaultEnvironment: "prod",
});

logger.info("Application started");
logger.warn("High memory usage", { metadata: { memoryMb: 2048 } });
logger.error("Failed to connect to database", {
  service: "db-worker",
  traceId: "abc-123",
});

API

LoggerConfig

Option	Type	Default	Description
apiKey	string	—	API key for the ingestion endpoint
endpoint	string	http://localhost:3000/api/ingest	Ingestion API URL
defaultService	string	—	Default service name for logs
defaultEnvironment	"prod" | "staging" | "dev"	"dev"	Default deployment environment
batchSize	number	20	Logs queued before automatic flush
flushIntervalMs	number	1000	Interval in ms between automatic flushes (set to 0 to disable)

LogOptions

Option	Type	Description
service	string	Override the service name for this log
environment	"prod" | "staging" | "dev"	Override the environment for this log
timestamp	Date	Custom timestamp (defaults to new Date())
traceId	string	Trace identifier for distributed tracing
metadata	Record<string, any>	Arbitrary key-value metadata

Logger methods

Method	Description
log(level, message, options?)	Log at any severity level
info(message, options?)	Log at info level
warn(message, options?)	Log at warn level
error(message, options?)	Log at error level
debug(message, options?)	Log at debug level
flush()	Immediately flush all queued logs
destroy()	Clear the flush interval timer for cleanup

Architecture

Logs are queued in memory and flushed to the ObservabilityOS ingestion API in batches. If the API is unreachable or returns an error, logs are automatically re-queued and retried on the next flush cycle.

Your App → Logger.log() → In-memory Queue → /api/ingest → ObservabilityOS
                          (flush on batch  │
                           size or timer)  └→ Re-queue on failure

License

MIT