Skip to content
Buy me a coffee

Events catalog

Every event reaches three places at once:

  • onTelemetry(listener) listeners, in every runtime;
  • the @ylcnfrht/resilience diagnostics_channel on Node, Bun and Deno;
  • the adapters built on them: /otel, /prometheus, createStats(), /hystrix.

Each message is a TelemetryEvent: { event, source: { pipelineName, strategyName, tags? }, context, args }. The tables list args. Events are only built when someone listens, and a pipeline built with telemetry: false emits none.

The strategy-level on* callbacks receive the same args object, so you can move code between a callback and a listener.

import {
function onTelemetry(listener: (event: TelemetryEvent) => void): () => void

Subscribe to every strategy event in the process. Works in every runtime (diagnostics_channel is Node-only). Returns an unsubscribe function.

onTelemetry
} from '@ylcnfrht/resilience';
const
const off: () => void
off
=
function onTelemetry(listener: (event: TelemetryEvent) => void): () => void

Subscribe to every strategy event in the process. Works in every runtime (diagnostics_channel is Node-only). Returns an unsubscribe function.

onTelemetry
(({
event: string
event
,
source: TelemetrySource
source
,
args: unknown
args
}) => {
if (
event: string
event
=== 'OnCircuitOpened')
var console: Console

The console module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers.

The module exports two specific components:

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
  • A global console instance configured to write to process.stdout and process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the note on process I/O for more information.

Example using the global console:

console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr

Example using the Console class:

const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err

@see ― source

console
.
Console.warn(message?: any, ...optionalParams: any[]): void (+1 overload)

The console.warn() function is an alias for

error

.

@since ― v0.1.100

warn
(`${
source: TelemetrySource
source
.
TelemetrySource.pipelineName: string | undefined
pipelineName
}: circuit opened`,
args: unknown
args
);
});
// later: off();

Emitted by every pipeline, whatever strategies it has.

Event When args Callback
OnPipelineExecuting An execution starts. { context } none
OnPipelineExecuted An execution ends. { outcome, duration } none
OnStrategyExecuted Each strategy finishes its part of an execution. source.strategyName names it. { outcome, duration, context } none
OnExecutionAttempt Every call of your callback: the single attempt, each retry, each hedged attempt. { outcome, context, attemptNumber, duration } none

Durations are milliseconds. attemptNumber is 0 for the first attempt; in OnExecutionAttempt it is the execution-wide context.attemptNumber, in strategy events the strategy’s own count.

Event Emitted by When args Callback
OnRetry Retry Before each retry’s delay. { outcome, context, attemptNumber, retryDelay, duration } onRetry
OnRetryExhausted Retry Retries ran out (or maxRetryTime passed) and the last outcome is still a failure. { outcome, context, attemptNumber } onRetryExhausted
OnRetryBudgetExhausted Retry with budget The shared budget refused a retry. { outcome, context, attemptNumber } onBudgetExhausted
OnTimeout Timeout The timeout fired. { context, timeout } onTimeout
OnCircuitOpened Circuit breaker The circuit opened, or was isolated by hand (isManual: true, breakDuration: Infinity). { outcome, breakDuration, isManual, context } onOpened
OnCircuitHalfOpened Circuit breaker The break ended and the first probe is let through. { context } onHalfOpened
OnCircuitClosed Circuit breaker The circuit closed (probes passed, or closed by hand). { outcome, isManual, context } onClosed
OnCircuitRejected Circuit breaker Every call the open (or full half-open) circuit refused. { context, state, retryAfter } onRejected
OnHalfOpenProbeTimedOut Circuit breaker A probe ran longer than halfOpenMaxWait; it counts as failed. { context, halfOpenMaxWait } none
OnHealthCheckFailed circuitHealthCheck() extension The periodic check failed (the circuit is then tripped). { error } none
OnCircuitStoreError sharedCircuitState() extension Reading or writing the shared store failed. { error } none
OnCircuitStateSynced sharedCircuitState() extension A newer state from another instance was adopted. { snapshot } none
OnFallback Fallback, addFallbackOn Before the fallback value is produced. { outcome, context } onFallback
OnHedging Hedging Before each extra (hedged) attempt starts. { attemptNumber, duration, context } onHedging
OnRateLimiterRejected Concurrency limiter, adaptive limiter, token bucket, fixed/sliding window, partitioned A call was rejected. { context, retryAfter } onRejected
OnRateLimiterInsuranceUsed Any permit limiter with insurance The remote algorithm failed or was slow; the in-memory one answered. { context, error } none
OnLimitChanged Adaptive concurrency limiter The limit moved. { oldLimit, newLimit, sample } onLimitChanged
OnCacheHit Cache A fresh value was served. { context, key, value, age } onCacheHit
OnCacheMiss Cache No fresh value; the call goes through. { context, key } onCacheMiss
OnStaleServed Cache with staleTtl, stale fallback The call failed and a stale value hid the failure. { context, key, value, age, outcome } onStaleServed
OnCacheStoreFailed Cache The store threw; the call continues as if uncached. { context, key, operation, error } none
OnCoalesced Cache, coalesce A call joined an identical one already in flight. { context, key, waiters } none
OnLockRejected Lock The lease wasn’t acquired within wait. { context, key } none
OnLockLost Lock Lease renewal failed while the callback ran. { context, key } onLockLost
Chaos.OnFault Chaos fault A fault was injected. { context, fault } onFaultInjected
Chaos.OnOutcome Chaos outcome A fake outcome was injected. { context, outcome } onOutcomeInjected
Chaos.OnLatency Chaos latency Latency was injected. { context, latency } onLatencyInjected
Chaos.OnBehavior Chaos behavior The behavior ran. { context } onBehaviorInjected
Chaos.OnGlobal setGlobalChaos() Global chaos touched a callback. { context, latency, fault } (fault is a boolean) none

Retry’s onFailedAttempt (every handled failure, with retriesLeft) has no event: OnExecutionAttempt covers every attempt.

A custom strategy can emit events into the same stream with report(source, 'OnMyEvent', context, args). Use the source your factory receives, so the event carries the pipeline’s name and tags.

Related: Telemetry, OpenTelemetry, Prometheus, createStats.