lambda-live-debugger
Version:
Debug Lambda functions locally like it is running in the cloud
94 lines (93 loc) • 3.82 kB
TypeScript
/**
* Outcome of a request, recorded by the framework via {@link MetricsRecorder.recordRequestOutcome}.
*
* @public
*/
export type RequestOutcome = "Success" | "Fault";
/**
* Unit attached to a recorded metric value. The vocabulary follows the
* CloudWatch unit names so backends that emit to CloudWatch can pass it
* through, but it carries no backend-specific semantics — a recorder is free
* to map or ignore it.
*
* @public
*/
export type MetricUnit = "Seconds" | "Microseconds" | "Milliseconds" | "Bytes" | "Kilobytes" | "Megabytes" | "Gigabytes" | "Terabytes" | "Bits" | "Kilobits" | "Megabits" | "Gigabits" | "Terabits" | "Percent" | "Count" | "None" | "Bytes/Second" | "Kilobytes/Second" | "Megabytes/Second" | "Gigabytes/Second" | "Terabytes/Second" | "Bits/Second" | "Kilobits/Second" | "Megabits/Second" | "Gigabits/Second" | "Terabits/Second" | "Count/Second";
/**
* Backend-agnostic recorder for per-request metrics. The framework drives the
* lifecycle and records request-level metrics through this interface; user
* handlers record their own business metrics through the same methods. Concrete
* recorders (e.g. an EMF recorder, or a future OpenTelemetry recorder) translate
* these abstract calls into their own primitives.
*
* @typeParam Native - the concrete backend handle returned by
* {@link MetricsRecorder.getMetrics}, e.g. an OpenTelemetry `Meter`. The
* parameter is required so that native access is always typed rather than
* erased to `unknown`.
*
* @public
*/
export interface MetricsRecorder<Native> {
/**
* Open the recorder for the current request. Called by the framework once at
* the start of request handling.
*/
begin(): void;
/**
* Close the recorder for the current request. Called by the framework once at
* the end of request handling; this is where an implementation typically
* flushes its event.
*/
end(): void;
/**
* Records the outcome and duration of a request. The concrete backend decides
* how to express this.
*/
recordRequestOutcome(outcome: RequestOutcome, durationMs: number): void;
/**
* Records a count. Values should be non-negative for cross-backend portability.
*/
addCount(name: string, value: number): void;
/**
* Records a duration in milliseconds.
*/
addTime(name: string, value: number): void;
/**
* Records a level — a sampled value that should average meaningfully across
* calls (e.g. queue depth, batch size).
*/
addLevel(name: string, value: number, unit?: MetricUnit): void;
/**
* Records a discrete data point where percentiles matter (e.g. per-call
* latency, item size).
*/
addMetric(name: string, value: number, unit?: MetricUnit): void;
/**
* Records a unitless ratio (e.g. cache hit rate, throttle rate).
*/
addRatio(name: string, value: number): void;
/**
* Attaches a property to the request's metrics. A nullish or empty value
* removes the property.
*/
setProperty(name: string, value: string | null | undefined): void;
/**
* Returns the recorder's native backend handle, so callers can reach
* library-specific features the abstract methods do not expose (e.g. an
* OpenTelemetry `Meter`).
*/
getMetrics(): Native;
}
/**
* Creates a per-request {@link MetricsRecorder}. Created once at startup and
* passed to the service handler; the framework calls {@link MetricsRecorderFactory.create}
* once per request to obtain a scoped recorder.
*
* @typeParam Native - the native backend handle exposed by recorders this
* factory produces. See {@link MetricsRecorder}.
*
* @public
*/
export interface MetricsRecorderFactory<Native> {
create(): MetricsRecorder<Native>;
}