Home

Awesome

<a name="iapetus"></a>

Iapetus 🔱

Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Prometheus metrics server.

<a name="iapetus-behaviour"></a>

Behaviour

Creates a HTTP service on port 9050 (default) with a /metrics endpoint exposing default metrics and user-defined metrics.

<a name="iapetus-behaviour-no-op-in-non-kubernetes-execution-context"></a>

No-op in non-Kubernetes execution context

The default behaviour is that all Iapetus operations become no-op if Iapetus detects that it is running in a non-Kubernetes environment (e.g. your local machine). This behaviour can be changed using detectKubernetes configuration.

<a name="iapetus-behaviour-user-defined-metrics"></a>

User-defined metrics

There are 4 types of metrics to choose from: counter, gauge, summary and histogram. See the Prometheus documentation on metric types and best practices for when to use which.

<a name="iapetus-behaviour-user-defined-metrics-counter"></a>

Counter

A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors.

Do not use a counter to expose a value that can decrease. For example, do not use a counter for the number of currently running processes; instead use a gauge.

export type CounterMetricConfigurationType = {|
  +description: string,
  +labelNames?: $ReadOnlyArray<string>,
  +name: string
|};

/**
 * @property timestamp Time in milliseconds.
 */
type CounterMetricPayloadType = {|
  +labels?: LabelsType,
  +timestamp?: number,
  +value: number
|};

export type CounterMetricType = {|
  +increment: (payload?: CounterMetricPayloadType) => void
|};

<a name="iapetus-behaviour-user-defined-metrics-gauge"></a>

Gauge

A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.

Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of running active HTTP requests.

export type GaugeMetricConfigurationType = {|
  +description: string,
  +labelNames?: $ReadOnlyArray<string>,
  +name: string
|};

/**
 * @property timestamp Time in milliseconds.
 */
type GaugeMetricPayloadType = {|
  +labels?: LabelsType,
  +timestamp?: number,
  +value: number
|};

export type GaugeMetricType = {|
  +decrement: (payload?: GaugeMetricPayloadType) => void,
  +increment: (payload?: GaugeMetricPayloadType) => void,
  +set: (payload: GaugeMetricPayloadType) => void
|};

<a name="iapetus-behaviour-user-defined-metrics-summary"></a>

Summary

N/A

<a name="iapetus-behaviour-user-defined-metrics-histogram"></a>

Histogram

N/A

<a name="iapetus-behaviour-default-metrics"></a>

Default metrics

The following metrics are collected and reported by default:

NameLabelsDescription
process_cpu_user_seconds_totalTotal user CPU time spent in seconds.
process_cpu_system_seconds_totalTotal system CPU time spent in seconds.
process_cpu_seconds_totalTotal user and system CPU time spent in seconds.
process_start_time_secondsStart time of the process since unix epoch in seconds.
process_resident_memory_bytesResident memory size in bytes.
nodejs_eventloop_lag_secondsLag of event loop in seconds.
nodejs_active_handles_totalNumber of active handles.
nodejs_active_requests_totalNumber of active requests.
nodejs_heap_size_total_bytesProcess heap size from node.js in bytes.
nodejs_heap_size_used_bytesProcess heap size used from node.js in bytes.
nodejs_external_memory_bytesNodejs external memory size in bytes.
nodejs_heap_space_size_total_bytesspaceProcess heap space size total from node.js in bytes.
nodejs_heap_space_size_used_bytesspaceProcess heap space size used from node.js in bytes.
nodejs_heap_space_size_available_bytesspaceProcess heap space size available from node.js in bytes.
nodejs_version_infoversion, major, minor, patchNode.js version info.
nodejs_gc_runs_totalgctypeCount of total garbage collections.
nodejs_gc_pause_seconds_totalgctypeTime spent in GC Pause in seconds.
nodejs_gc_reclaimed_bytes_totalgctypeTotal number of bytes reclaimed by GC.
<!-- const metrics = register.getMetricsAsArray(); for (const metric of metrics) { console.log('|`' + metric.name + '`|' + (metric.labelNames.length ? '`' + metric.labelNames.join('`, `') + '`' : '') + '|' + metric.help + '|'); } -->

<a name="iapetus-behaviour-metrics"></a>

<code>/metrics</code>

/metrics endpoint produces metrics for Prometheus consumption.

<a name="iapetus-usage"></a>

Usage

Use createIapetus to create an instance of Iapetus.

import {
  createIapetus
} from 'iapetus';

const configuration: IapetusConfigurationType = {};

const iapetus: IapetusType = createIapetus(configuration);

The following types describe the configuration shape and the resulting Iapetus instance interface.

/**
 * @property detectKubernetes Run Iapetus only if service is detected ro be running in Kubernetes. Default: true.
 * @property port The port on which the Iapetus service listens. This port must be different than your main service port, if any. The default port is 9050.
 */
type IapetusConfigurationType = {|
  +detectKubernetes?: boolean,
  +port?: number
|};

/**
 * @property stop Stops the Iapetus server.
 */
type IapetusType = {|
  +createCounterMetric: (configuration: CounterMetricConfigurationType) => CounterMetricType,
  +createGaugeMetric: (configuration: GuageMetricConfigurationType) => GaugeMetricType,
  +getMetrics: () => $ReadOnlyArray<MetricDescriptorType>,
  +stop: () => Promise<void>
|};

<a name="iapetus-usage-example"></a>

Example

const iapetus = createIapetus();

const iapetusMetrics = {
  activeRequestCount: iapetus.createGaugeMetric({
    description: 'Active request count',
    labelNames: [],
    name: 'activeRequestCount'
  })
};

// Increase `activeRequestCount` value by 1.
iapetusMetrics.activeRequestCount.increment();

<a name="iapetus-usage-kubernetes-configuration"></a>

Kubernetes configuration

This section assumes that you have installed Prometheus using Helm Prometheus chart.

Add the following annotations to your Pod:

annotations:
  prometheus.io.scrape: 'true'
  prometheus.io.port: '9050'
  prometheus.io.path: '/metrics'

<a name="iapetus-usage-logging"></a>

Logging

iapetus is using Roarr to implement logging.

Set ROARR_LOG=true environment variable to enable logging.

<a name="iapetus-faq"></a>

FAQ

<a name="iapetus-faq-where-does-the-name-_iapetus_-come-from"></a>

Where does the name <em>Iapetus</em> come from?

In Greek mythology, Iapetus (/aɪˈæpɪtəs/), was a Titan, the son of Uranus and Gaia, and father of Atlas, Prometheus, Epimetheus and Menoetius.

<a name="iapetus-faq-what-is-the-difference-from-prom-client"></a>

What is the difference from <code>prom-client</code>?

Iapetus is a high-level abstraction of prom-client with integrated HTTP server and pre-configured default metrics.

<a name="iapetus-related-projects"></a>

Related projects