ReadonlytraceCore trace information (W3C compatible)
ReadonlytraceTrace ID (unique identifier for the entire trace)
ReadonlyspanSpan ID (unique identifier for this specific span)
ReadonlyresourceResource context (service name, version, instance ID, environment, region) Automatically populated from plugin configuration
ReadonlyattributesCustom attributes attached to this observable Attributes are immutable - use setAttribute() to create new observable with additional attributes
Logging methods with automatic trace context
All log methods automatically include trace context (trace ID, span ID) in the output. Logs support placeholder syntax for structured logging.
Log a debug message
The message to log with optional {placeholder} syntax
Metadata to replace placeholders and add to log
Log an info message
The message to log with optional {placeholder} syntax
Metadata to replace placeholders and add to log
Log a warning message
The message to log with optional {placeholder} syntax
Metadata to replace placeholders and add to log
Log an error message or BSBError
Either a message string or BSBError instance
Metadata (only used if first arg is a message)
Metrics methods for creating counters, gauges, histograms, and timers
Create a counter metric
Metric name
Short description
Detailed help text
Optionallabels: LABELS[]Optional label names
Create a gauge metric
Metric name
Short description
Detailed help text
Optionallabels: LABELS[]Optional label names
Create a histogram metric
Metric name
Short description
Detailed help text
Optionalboundaries: number[]Optional histogram boundaries
Optionallabels: LABELS[]Optional label names
Create a timer to measure elapsed time
// Counter for tracking requests
const requests = obs.metrics.counter(
"requests_total",
"Total requests",
"Count of all incoming requests",
["method", "status"]
);
requests.increment(1, { method: "GET", status: "200" });
// Timer for measuring duration
const timer = obs.metrics.timer();
await processRequest();
const duration = timer.stop();
obs.log.info("Request took {ms}ms", { ms: duration });
Create a child span with inherited attributes
Child spans inherit all attributes from the parent and form a parent-child relationship in the distributed trace. Always call end() when done.
Name of the span
Optionalattributes: Record<string, string | number | boolean>Additional attributes for this span
New Observable representing the child span
public async fetchUser(obs: Observable, userId: string) {
const span = obs.startSpan("fetch-user", { "user.id": userId });
try {
const user = await this.db.query("SELECT * FROM users WHERE id = ?", [userId]);
span.end({ "user.found": true });
return user;
} catch (error) {
span.error(error as Error);
span.end({ "user.found": false });
throw error;
}
}
Create a new Observable with an additional attribute
Observables are immutable - this returns a new instance. Attributes are propagated to all child operations (logs, spans, metrics).
New Observable with the added attribute
public async handleRequest(obs: Observable, req: Request) {
// Add request ID to all subsequent operations
const withRequestId = obs.setAttribute("request.id", req.id);
withRequestId.log.info("Handling request");
// Chain multiple attributes
const withUser = withRequestId.setAttribute("user.id", req.userId);
const span = withUser.startSpan("process-request");
}
Create a new Observable with multiple attributes
Observables are immutable - this returns a new instance. More efficient than calling setAttribute multiple times.
Attributes to add
New Observable with the added attributes
Record an error to both logs and traces
Automatically records the error to both the logging system and the active span. This ensures errors are captured in both systems for complete observability.
Error or BSBError to record
Optionalattributes: Record<string, string | number | boolean>Additional attributes to attach
End the span (only applies if this Observable was created via span())
Completes the span and records the final state. If this Observable was not created via span(), this method does nothing.
Optionalattributes: Record<string, string | number | boolean>Final attributes to attach before ending
Observable context for unified observability across logging, metrics, and tracing.
Observable replaces DTrace in the public API and provides a unified interface for:
See
API: Observable
Example