Module @pamoja/telemetry

Ergonomic facade over the generated telemetry binding.

A node that ships every event it produces will spend more on reporting than on the job it was installed to do, and on a satellite link that is money. A reporter ships what is worth its bytes, counts everything either way, and moves its own bar as the link gets more expensive, so the aggregate picture survives even when the detail cannot be sent.

The generated binding decides on the level alone, since that is all the core reporter reads. The event a caller writes travels no further than this layer, which hands it straight back when it should be shipped.

@pamoja/telemetry

Observability that ships only what is worth the bytes as link cost rises, while counting everything. One capability of pamoja, one memory-safe Rust core with bindings for TypeScript, Python, and C#.

Install

npm install @pamoja/telemetry

This pulls in @pamoja/native, the compiled engine. npm install pamoja is the whole framework in one package.

Example

The test that runs in CI, spliced here as it ran.

From bindings/node/guides/telemetry.ts:

import { Level, LinkCost, Reporter, linkCostThreshold } from '@pamoja/telemetry'

// The node is willing to record everything, then finds out it is reporting over a metered
// link, which puts the bar at Info.
const reporter = new Reporter(Level.Trace)
reporter.adaptTo(LinkCost.Metered)
console.log(`on a metered link, nothing below ${reporter.threshold} is sent`)

// Routine detail stops going out. A reading and the warning that follows it still do, and
// a shipped event comes back with the measurement that triggered it.
const tick = reporter.record({ level: Level.Debug, code: 'loop.tick' })
const reading = reporter.record({ level: Level.Info, code: 'reading.ok', value: 4.8 })
console.log(`loop.tick sent: ${tick !== null}`)
console.log(`reading.ok sent: ${reading !== null}`)
const warned = reporter.record({ level: Level.Warn, code: 'battery.low', value: 0.18 })!
console.log(`sent      ${warned.code} carrying ${warned.value}`)

// The node falls back to satellite, which raises the bar to Warn. The same reading is no
// longer worth its bytes; a failure still is.
reporter.adaptTo(LinkCost.Expensive)
const dearer = reporter.record({ level: Level.Info, code: 'reading.ok', value: 4.9 })
const lost = reporter.record({ level: Level.Error, code: 'link.lost' })
console.log(`on satellite, reading.ok sent: ${dearer !== null}`)
console.log(`on satellite, link.lost sent: ${lost !== null}`)

// Only the stream was thinned, not the counts, so every event is still accounted for and
// the snapshot is what the node ships in place of them.
const counts = reporter.snapshot()
console.log(
  `of ${reporter.total} events, ${counts.emitted} went out and ${counts.dropped} were counted only`,
)

The same capability in every language

Language	Package	Reference
Rust	`pamoja-telemetry`	reference, docs.rs, install
TypeScript	`@pamoja/telemetry`	reference, install
Python	`pamoja-telemetry`	reference, install
C#	`Pamoja.Telemetry`	reference, install

Documentation

@pamoja/telemetry reference, every class, function, and type this package exports.
The Telemetry guide, with the same example in Rust, Python, and C#.
Every capability, and the install page.