@lickle/trace

Minimal structured tracing for TypeScript/JavaScript, inspired by Rust’s tracing.
Provides spans, events, and a pluggable subscriber system.

Install

npm install @lickle/trace

Quick Start

By default nothing is logged—you need to attach a subscriber.
The simplest option is the built-in ConsoleLayer:

import { Builder, ConsoleLayer, Level } from '@lickle/trace/subscribe'

new Builder().withMinLevel(Level.INFO).withLayer(new ConsoleLayer()).install()

Now INFO+ events will print to the console.

Examples

Events

import { event, Level } from '@lickle/trace/trace'

event('startup', Level.INFO, 'Application ready')
// [INFO] (startup): Application ready

Spans

import { span, exit, Level } from '@lickle/trace/trace'

const s = span('db.query', Level.DEBUG, { sql: 'SELECT *' })
try {
  // run query...
} finally {
  exit.exit(s)
}
// [DEBUG] enter -> (db.query)
// [DEBUG] exit <- (db.query) 5.67ms { sql: 'SELECT *' }

Custom Subscriber

import { Builder } from '@lickle/trace/subscribe'
import { Level, Subscriber } from '@lickle/trace/trace'

const metrics: Subscriber = {
  minLevel: Level.INFO,
  onEvent(evt) {
    console.log(`METRIC: Event '${evt.meta.name}'`)
  },
}

new Builder().withLayer(metrics).install()

API

Core (@lickle/trace/trace)

• Trace – manages spans and events
• event(name, level, message?, fields?)
• span(name, level?, fields?) → Span
• enter(span), exit(span)
• setSubscriber(sub), getSubscriber()
• defaultTrace – global instance
• Level – severity enum (TRACE, DEBUG, INFO, WARN, ERROR)

Subscribe (@lickle/trace/subscribe)

• Builder – fluent builder for subscribers
  • .withMinLevel(level)
  • .withLayer(subscriber)
  • .install(trace?)
• ConsoleLayer – logs spans/events to the console

License

MIT © Dan Beaven