# Class MetricsService

Performance Metrics Service Cyclomatic complexity: 8

- Defined in services/MetricsService.ts:69

##### Index

### Constructors

constructor

### Properties

maxHistogramSamples
metrics

### 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

- Defined in services/MetricsService.ts:71

### `Private` `Readonly` metrics

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

- Defined in services/MetricsService.ts:70

## Methods

### `Private` buildKey

- buildKey(name: MetricKey, labels?: Record<string, string>): string

  Build metric key from name and labels Cyclomatic complexity: 2

  #### Parameters

  - name: MetricKey
  - `Optional` labels: Record<string, string>

  #### Returns string

  - Defined in services/MetricsService.ts:286

### 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:278

### 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

  - `Optional` labels: 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:238

### 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

  - `Optional` labels: 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:209

### 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`)

  - `Optional` labels: 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)

  - `Optional` labels: 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:361

### `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:305

### `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:325

### 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

  - `Optional` labels: 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