@btravstack/observability

---

@btravstack/observability / index

index

Classes

LoggerConfig

Defined in: observability/src/observability.ts:21

What the graph bound from the environment: the level every logger in it filters at. A port of its own, like a starter's HttpConfig, so anything that wants to know reads it rather than re-deriving it.

Extends

• PortInstance<"LoggerConfig", LoggerSettings>

Constructors

Constructor

new LoggerConfig(): LoggerConfig;

Defined in: di/dist/index.d.mts:16

Returns

LoggerConfig

Inherited from

Port("LoggerConfig")<LoggerSettings>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
[ID]	readonly	"LoggerConfig"	Port("LoggerConfig").[ID]	di/dist/index.d.mts:12
[SERVICE]	readonly	LoggerSettings	Port("LoggerConfig").[SERVICE]	di/dist/index.d.mts:13
portId	readonly	"LoggerConfig"	Port("LoggerConfig").portId	di/dist/index.d.mts:17

Type Aliases

Line

type Line = object;

Defined in: observability/src/logger.ts:10

One line, as the implementation hands it to a Sink: the message, its severity, and everything known about it.

Properties

Property	Modifier	Type	Description	Defined in
attributes	readonly	Attributes	-	observability/src/logger.ts:13
cause	readonly	unknown	-	observability/src/logger.ts:14
level	readonly	Level	-	observability/src/logger.ts:11
message	readonly	string	-	observability/src/logger.ts:12
time	readonly	number	Milliseconds since the epoch, stamped when the line was written.	observability/src/logger.ts:16
unit	readonly	| { tenantId?: string; traceId: string; unitId: string; } | undefined	What currentUnit() carried, or undefined outside a unit.	observability/src/logger.ts:18

---

LoggerSettings

type LoggerSettings = object;

Defined in: observability/src/config.ts:32

What observability() binds from the environment.

Properties

Property	Modifier	Type	Defined in
level	readonly	Level	observability/src/config.ts:32

---

ObservabilityOptions

type ObservabilityOptions = object;

Defined in: observability/src/observability.ts:23

Properties

Property	Modifier	Type	Description	Defined in
level?	readonly	Level	Pins the level instead of reading LOG_LEVEL — a test's "fatal", a CLI's "debug".	observability/src/observability.ts:31
sink?	readonly	Sink	Where lines go. Default: one JSON object per line on stdout. The @btravstack/observability/pino subpath is the same seam for a deployment that wants pino's throughput.	observability/src/observability.ts:29

---

Sink

type Sink = (line) => void;

Defined in: observability/src/logger.ts:24

Where a line goes. Given a Line, writes it — and never throws, which createLogger guarantees on its behalf.

Parameters

Parameter	Type
line	Line

Returns

void

Functions

createLogger()

function createLogger(sink, level?): LoggerService;

Defined in: observability/src/logger.ts:41

A logger over sink, filtered at level and correlated with the ambient unit.

The correlation is read per call, not captured: one logger is built per scope and every unit the kernel opens has its own record, so a logger that captured it at construction would stamp the wrong trace id on every line but the first. with layers attributes and nothing else, so a child costs one object and shares the sink.

Every path is wrapped: a sink that throws is swallowed here, because a logger that takes the process down is worse than a line nobody sees.

Parameters

Parameter	Type	Default value
sink	Sink	undefined
level	Level	"info"

Returns

LoggerService

---

jsonSink()

function jsonSink(stream?): Sink;

Defined in: observability/src/json-sink.ts:34

One JSON object per line on stream.

The caller's attributes are spread FIRST and the line's own fields after them, and that order is the precedence: an attributes: { level: "info" } cannot rewrite an error line's severity, nor its traceId.

The unit's ids are spread at the top level rather than nested under unit, because traceId is the field an operator searches.

Parameters

Parameter	Type	Default value
stream	{ write: (chunk) => unknown; }	process.stdout
stream.write	(chunk) => unknown	undefined

Returns

Sink

---

kernelEvents()

function kernelEvents(logger): EventSink;

Defined in: observability/src/observability.ts:94

The kernel's nine lifecycle events, as log lines on logger — the adapter between StartOptions.onEvent and an application's own stream.

The mapping is deliberate rather than mechanical: startFailed and uncaught are error, teardownError is warn (the application is already stopping and the exit code says so), everything else info. Each event's own fields become attributes, so a drain is queryable by field.

The logger is a PARAMETER, not resolved: building is emitted while the graph is still being built, so the sink cannot come from the context it watches.

Parameters

Parameter	Type
logger	LoggerService

Returns

EventSink

---

logLevel()

function logLevel(options?): ConfigField<Level>;

Defined in: observability/src/config.ts:16

LOG_LEVEL, as a ConfigField of the six levels and nothing else.

A value outside the set is a ConfigInvalid naming the variable — exit 78 under runMain, before a line is written — rather than a silent fallback to info: a deployment that meant debug and typed verbose should be told, not quietly under-logged for a week. Built on Config.string, so it inherits the semantics every other variable has: an unset variable takes the default, a set-but-blank one is an error.

Parameters

Parameter	Type
options	{ default?: Level; }
options.default?	Level

Returns

ConfigField<Level>

---

observability()

function observability(options?): Module<LoggerConfig | Logger | Observers, ConfigInvalid, Env>;

Defined in: observability/src/observability.ts:43

The observability starter: a module providing the application's Logger and the LoggerConfig it was built from. Import it next to the application and export Logger.

Every line carries the ambient unit's traceId, because the logger reads currentUnit() per call — so a request's lines are attributable with no argument threaded through the call stack.

Parameters

Parameter	Type
options	ObservabilityOptions

Returns

Module<LoggerConfig | Logger | Observers, ConfigInvalid, Env>