SDK Reference

Package: orion-monitoring — TypeScript SDK for sending logs to Orion. Zero runtime dependencies, ESM only, Node.js 18+.

Installation

npm install orion-monitoring

Configuration

OrionConfig

interface OrionConfig {
  /** Project source token (required) */
  token: string
  /** Orion API base URL. Default: http://localhost:3001/api */
  apiUrl?: string
  /** Enable offline queue when the API is unreachable. Default: true */
  offline?: boolean
  /** Max entries in the offline queue. Default: 1000 */
  maxQueueSize?: number
  /** Queue retry interval in ms. Default: 30000 */
  retryInterval?: number
  /** Called when a log is dropped because the queue is full */
  onDrop?: (dropped: LogPayload) => void
}

Config is resolved from these sources in order (last wins):

1. Defaults (offline: true, maxQueueSize: 1000, retryInterval: 30000)
2. .orion/config.json found by walking up from the script directory
3. Manual override passed to createLogger()

LogLevel

type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'verbose' | 'trace'

Factory functions

createLogger(override?)

Creates a Logger with config auto-resolved from .orion/config.json:

import { createLogger } from 'orion-monitoring'

// Auto-detect config
const logger = createLogger()

// Override specific fields
const logger = createLogger({ apiUrl: 'https://api.example.com/api' })

Orion.createLogger(levelOrConfig?)

Namespace shortcut — useful when you want a fixed default level for send():

import { Orion } from 'orion-monitoring'

// All logger.send('message') calls will use 'debug' level
const logger = Orion.createLogger('debug')
logger.send('Cache invalidated')

Logger methods

Level methods

logger.info(message: string, meta?: Record<string, unknown>, tags?: string[]): void
logger.warn(message: string, meta?: Record<string, unknown>, tags?: string[]): void
logger.error(message: string, meta?: Record<string, unknown>, tags?: string[]): void
logger.debug(message: string, meta?: Record<string, unknown>, tags?: string[]): void
logger.verbose(message: string, meta?: Record<string, unknown>, tags?: string[]): void
logger.trace(message: string, meta?: Record<string, unknown>, tags?: string[]): void

Examples:

logger.info('User signed in', { userId: 'u_123', ip: '1.2.3.4' })
logger.error('Payment failed', { orderId: 'ord_456', reason: 'card_declined' }, ['payments'])
logger.debug('Query executed', { sql: 'SELECT ...', durationMs: 12 })

send() — flexible overload

// Use default level (set via Orion.createLogger('debug'))
logger.send('Cache hit')

// Explicit level
logger.send('warn', 'Rate limit approaching')

// Structured object — extra keys become metadata
logger.send({
  level: 'error',
  message: 'Webhook delivery failed',
  endpoint: 'https://example.com/hook',
  statusCode: 503,
  tags: ['webhooks'],
})

close()

Stops retry intervals and prevents new logs from being queued. Call on process shutdown:

process.on('SIGTERM', () => logger.close())

Offline queue

When offline: true (default), failed sends are queued in memory and retried every retryInterval ms. Logs are dropped silently when the queue reaches maxQueueSize — use onDrop to observe this:

const logger = createLogger({
  onDrop: (log) => console.warn('[orion] log dropped:', log.message),
})

Express middleware

Automatically logs every HTTP request with method, path, status code, and duration:

import { createOrionMiddleware } from 'orion-monitoring'

const orionMiddleware = await createOrionMiddleware({
  exclude: ['/health', '/metrics'],
  level: {
    success: 'info',      // 2xx (default)
    clientError: 'warn',  // 4xx (default)
    serverError: 'error', // 5xx (default)
  },
  logBody: false,         // include req.body in metadata
  logHeaders: false,      // include req.headers in metadata
})

app.use(orionMiddleware)

Logs format: GET /api/v1/users 200 — 23ms

MiddlewareOptions

interface MiddlewareOptions {
  logBody?: boolean
  logHeaders?: boolean
  exclude?: string[]
  level?: {
    success?: LogLevel      // default: 'info'
    clientError?: LogLevel  // default: 'warn'
    serverError?: LogLevel  // default: 'error'
  }
}

Fastify plugin

import { orionPlugin } from 'orion-monitoring'

await fastify.register(orionPlugin, {
  exclude: ['/health'],
  logBody: false,
})

The plugin adds three hooks: onRequest (timestamps), onResponse (logs with duration), onError (logs uncaught errors with stack trace).

LogPayload type

interface LogPayload {
  level: LogLevel
  message: string
  timestamp: string          // ISO 8601
  meta?: Record<string, unknown>
  tags?: string[]
}