Class MetricsService

Performance Metrics Service Cyclomatic complexity: 8

Index

Constructors

Properties

Methods

buildKey clear getHistogramSummary getMetric incrementCounter observeHistogram partition percentileFromUnsorted selectKth setGauge

Constructors

constructor

new MetricsService(maxHistogramSamples?: number): MetricsService
Parameters
- maxHistogramSamples: number = 1000
Returns MetricsService
- Defined in services/MetricsService.ts:73

Properties

`Private` `Readonly`maxHistogramSamples

maxHistogramSamples: number

`Private` `Readonly`metrics

metrics: Map<string, MetricValue> = ...

Methods

`Private`buildKey

buildKey(name: MetricKey, labels?: Record<string, string>): string
Build metric key from name and labels Cyclomatic complexity: 2
Parameters
- name: MetricKey
- Optionallabels: Record<string, string>
Returns string
- Defined in services/MetricsService.ts:289

clear

clear(): void
Clears all recorded metrics from memory.

Intended for use in tests to ensure metric isolation between cases. Calling this in production will silently discard all instrumentation data.

Returns void
Example
```
afterEach(() => {
  metricsService.clear();
});
```
Since
0.8.0
- Defined in services/MetricsService.ts:281

getHistogramSummary

getHistogramSummary(
    name: MetricKey,
    labels?: Record<string, string>,
):
    | {
        avg: number;
        count: number;
        p50: number;
        p95: number;
        p99: number;
        sum: number;
    }
    | undefined
Returns a statistical summary of a histogram metric.

Computes count, sum, average, and p50 / p95 / p99 percentiles from the stored samples. Returns undefined if the metric does not exist, is not a histogram, or has no samples yet.
Parameters
- name: MetricKey
  Histogram metric name to summarise
- Optionallabels: Record<string, string>
  Optional label dimensions to scope the lookup
Returns
    | {
        avg: number;
        count: number;
        p50: number;
        p95: number;
        p99: number;
        sum: number;
    }
    | undefined
Summary object with count, sum, avg, p50, p95, p99, or undefined if no histogram data exists
Example
```
const summary = metricsService.getHistogramSummary('ep_api_latency_ms');
if (summary) {
  console.log(`p95 latency: ${summary.p95}ms`);
}
```
Since
0.8.0
- Defined in services/MetricsService.ts:241

getMetric

getMetric(name: MetricKey, labels?: Record<string, string>): number | undefined
Returns the current scalar value of a counter or gauge metric.

Returns undefined for histogram metrics (use getHistogramSummary instead) and for metrics that have not been recorded yet.
Parameters
- name: MetricKey
  Metric name to query
- Optionallabels: Record<string, string>
  Optional label dimensions to scope the lookup
Returns number | undefined
Current numeric value, or undefined if not found / is a histogram
Example
```
const errors = metricsService.getMetric(MetricName.EP_API_ERROR_COUNT) ?? 0;
if (errors > 10) {
  console.warn('High EP API error rate');
}
```
Since
0.8.0
- Defined in services/MetricsService.ts:212

incrementCounter

incrementCounter(
    name: MetricKey,
    value?: number,
    labels?: Record<string, string>,
): void
Increments a counter metric by the given value.

Creates the counter at zero if it does not exist yet, then adds value. Counters are monotonically increasing — use setGauge for values that can decrease.
Parameters
- name: MetricKey
  Metric name (use a MetricName enum value for type safety)
- value: number = 1
  Amount to add to the counter (default: 1)
- Optionallabels: Record<string, string>
  Optional key/value label dimensions (e.g., { endpoint: '/meps' })
Returns void
Throws
If name is not a string
Example
```
metricsService.incrementCounter(MetricName.EP_API_CALL_COUNT);
metricsService.incrementCounter(MetricName.EP_API_CALL_COUNT, 1, { endpoint: '/meps' });
```
Since
0.8.0
- Defined in services/MetricsService.ts:97

observeHistogram

observeHistogram(
    name: MetricKey,
    value: number,
    labels?: Record<string, string>,
): void
Records a single observation into a histogram metric.

Uses reservoir sampling to keep sample count bounded at maxHistogramSamples. Use getHistogramSummary to retrieve computed percentiles.
Parameters
- name: MetricKey
  Metric name (use a MetricName enum value for type safety)
- value: number
  Observed value (e.g., response time in milliseconds)
- Optionallabels: Record<string, string>
  Optional key/value label dimensions
Returns void
Throws
If name is not a string
Example
```
const start = Date.now();
await fetchFromEPAPI('/meps');
metricsService.observeHistogram('ep_api_latency_ms', Date.now() - start);
```
Since
0.8.0
- Defined in services/MetricsService.ts:160

`Private`partition

partition(
    arr: number[],
    left: number,
    right: number,
    pivotIndex: number,
): number
Partition helper for quickselect (Lomuto-style) Cyclomatic complexity: 4
Parameters
- arr: number[]
  Array to partition
- left: number
  Left bound
- right: number
  Right bound
- pivotIndex: number
  Pivot index
Returns number
New pivot index
- Defined in services/MetricsService.ts:366

`Private`percentileFromUnsorted

percentileFromUnsorted(values: number[], percentile: number): number
Compute a percentile value from an unsorted array using quickselect Cyclomatic complexity: 3
Parameters
- values: number[]
  Array of samples
- percentile: number
  Percentile to compute (0-100)
Returns number
Percentile value
- Defined in services/MetricsService.ts:308

`Private`selectKth

selectKth(arr: number[], k: number): number
Select the k-th smallest element using quickselect Cyclomatic complexity: 5
Parameters
- arr: number[]
  Array to select from (will be mutated)
- k: number
  Index of element to select (0-based)
Returns number
The k-th smallest element
- Defined in services/MetricsService.ts:330

setGauge

setGauge(name: MetricKey, value: number, labels?: Record<string, string>): void
Sets a gauge metric to an absolute value.

Unlike counters, gauges can be set to any value including decreasing values (e.g., current queue depth, active connection count).
Parameters
- name: MetricKey
  Metric name (use a MetricName enum value for type safety)
- value: number
  Absolute gauge value to record
- Optionallabels: Record<string, string>
  Optional key/value label dimensions
Returns void
Throws
If name is not a string
Example
```
metricsService.setGauge('active_connections', 5);
metricsService.setGauge('queue_depth', 12, { queue: 'ep_api' });
```
Since
0.8.0
- Defined in services/MetricsService.ts:129

Class MetricsService

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns MetricsService

Properties

Private ReadonlymaxHistogramSamples

Private Readonlymetrics

Methods

PrivatebuildKey

Parameters

Returns string

clear

Returns void

Example

Since

getHistogramSummary

Parameters

Returns | { avg: number; count: number; p50: number; p95: number; p99: number; sum: number; } | undefined

Example

Since

getMetric

Parameters

Returns number | undefined

Example

Since

incrementCounter

Parameters

Returns void

Throws

Example

Since

observeHistogram

Parameters

Returns void

Throws

Example

Since

Privatepartition

Parameters

Returns number

PrivatepercentileFromUnsorted

Parameters

Returns number

PrivateselectKth

Parameters

Returns number

setGauge

Parameters

Returns void

Throws

Example

Since

Settings

On This Page

`Private` `Readonly`maxHistogramSamples

`Private` `Readonly`metrics

`Private`buildKey

Returns
| {
avg: number;
count: number;
p50: number;
p95: number;
p99: number;
sum: number;
}
| undefined

`Private`partition

`Private`percentileFromUnsorted

`Private`selectKth