Telemetry

@stone-js/telemetry observes the app from the same place everything else attaches: a blueprint and a middleware. It records spans and metrics around each event and hands them to an exporter, so observability is configuration, not code scattered through handlers.

#Install & enable

npm i @stone-js/telemetry

import { StoneApp } from '@stone-js/core'
import { Telemetry } from '@stone-js/telemetry'

@Telemetry()   // spans and metrics around each event
@StoneApp({ name: 'tasks' })
export class Application {}

import { defineStoneApp } from '@stone-js/core'
import { telemetryBlueprint } from '@stone-js/telemetry'

export const App = defineStoneApp(
  { name: 'tasks' },
  [telemetryBlueprint]
)

#What it records

With telemetry enabled, each event is wrapped in a span and timed; you add your own spans and counters where a domain operation is worth measuring. The Telemetry service is injected like any other.

constructor ({ telemetry }) { this.telemetry = telemetry }

create (event: IncomingHttpEvent) {
  return this.telemetry.span('task.create', () => {
    const task = this.tasks.add(event.get('title'))
    this.telemetry.count('task.created')
    return task
  })
}

#The health probe

Telemetry is what you read after the fact; a health probe is the question asked in the moment, by something that cannot read: a load balancer deciding whether to route traffic, a platform deciding whether to replace an instance. Enabling telemetry publishes it at /health, and the answer is a status code first: 200 to route here, 503 to stop. The body is for the person who follows up.

With nothing registered it answers 200, which is the truthful answer to "is this process up and routing". Register a check and the answer starts meaning more:

import { HealthCheck } from '@stone-js/telemetry'

@HealthCheck('database')
export class DatabaseCheck {
  constructor ({ db }) { this.db = db }          // resolved, like any service

  async check () {
    return await this.db.ping()                   // true, or { healthy: false, detail: '…' }
  }
}

#Which build is answering

A different question from the probe, and worth keeping separate. A probe is asked by a platform that cannot read and only needs a verdict; this one is asked by a person mid-investigation, and the answer is a fact. Is the deploy live yet. Is that canary the new build. Why does production behave differently. Enabling telemetry publishes it at /version:

curl https://api.example/version
{"name":"my-api","env":"production","platform":"aws_lambda_http","release":"2026.08.21-3"}

platform earns its place: one artefact can carry several adapters, each claiming the runtime it detects, so which one won is not knowable from the outside. The release is declared, never guessed from the environment, because an application already knows it and already has a place to put what it knows:

@Configuration()
export class BuildConfiguration implements IConfiguration {
  configure (blueprint: IBlueprint): void {
    blueprint.set('stone.telemetry.version.release', myReleaseTag)
  }
}

#Exporters

Where telemetry goes is an exporter, swapped without touching your instrumentation. The console exporter ships for development; point it at your platform in production.