OpenTelemetry Support

The io.Manager Server can be configured to export metrics via OpenTelemetry.

By default, the io.Manager Server supports exporting metrics to an OpenTelemetry Collector. It's also possible to provide your own custom metrics exporter and metrics reader pointing to a different backend service.

The io.Manager Server publishes a set of metrics which you can enable or disable and configure individually.

Publishing metrics data is disabled by default. To enable publishing metrics, you must enable OpenTelemetry support in the io.Manager Server and explicitly enable the metrics feature via the configuration object for initializing the io.Manager Server, or via environment variables, depending on your deployment approach.

Environment Variables

To enable and configure publishing metrics, register the following environment variables with the proper values. The API_OTEL_METRICS_ENABLED environment variable must be set to true:

The following example demonstrates how to enable OpenTelemetry support, how to enable publishing metrics, and how to configure the interval for publishing metrics:

# Enabling OpenTelemetry support.
API_OTEL_ENABLED=true
API_OTEL_RESOURCE_SERVICE_NAME=io-manager

# Enabling and configuring metrics.
API_OTEL_METRICS_ENABLED=true
API_OTEL_METRICS_URL=http://localhost:4318/v1/metrics
API_OTEL_METRICS_PUBLISH_INTERVAL=10000

Configuration Object

To enable publishing metrics, use the metrics property under the otel top-level key of the optional Config object for initializing the io.Manager Server.

The following example demonstrates how to enable OpenTelemetry support, how to enable publishing metrics, and how to configure the interval for publishing metrics:

import { start } from "@interopio/manager";

const config = {
    // Enabling OpenTelemetry support.
    otel: {
        enabled: true,
        resource: {
            serviceName: "io-manager"
        },
        // Enabling and configuring metrics.
        metrics: {
            enabled: true,
            url: "http://localhost:4318/v1/metrics",
            publishInterval: 10000
        }
    }
};

const server = await start(config);

The metrics object has the following properties:

The io.Manager Server exports the following metrics:

All available metrics are enabled by default. It's possible to disable all available metrics and explicitly enable and configure individual ones via the configuration object for initializing the io.Manager Server, or via environment variables, depending on your deployment approach. Each metric has specific configurable properties (for more details about each individual metric, see the respective metric section).

To disable all available metrics via environment variables, set the API_OTEL_METRICS_DEFAULT_METRICS_ENABLED variable to false. To explicitly enable and configure individual metrics, use the respective environment variables listed in the sections describing the individual metrics.

The following example demonstrates how to disable all available metrics and explicitly enable and configure the "io_manager.active_sessions" metric via environment variables:

# Enabling OpenTelemetry support.
API_OTEL_ENABLED=true
API_OTEL_RESOURCE_SERVICE_NAME=io-manager

# Enabling metrics.
API_OTEL_METRICS_ENABLED=true
API_OTEL_METRICS_URL=http://localhost:4318/v1/metrics

# Disabling all available metrics.
API_OTEL_METRICS_DEFAULT_METRICS_ENABLED=false

# Enabling and configuring the `"io_manager.active_sessions"` metric.
API_OTEL_METRICS_DEFINITIONS_ACTIVE_SESSIONS_ENABLED=true
API_OTEL_METRICS_DEFINITIONS_ACTIVE_SESSIONS_PUBLISH_INTERVAL=45000

To disable all available metrics via the configuration object for initializing the io.Manager Server, set the defaultMetricsEnabled property of the metrics object to false. To explicitly enable and configure individual metrics, use the metrics property of the metrics object. It accepts a list of metrics definition objects. To specify the metric you want to enable and configure, provide the metric name as a value to the type property of the metrics definition object.

The following example demonstrates how to disable all available metrics and explicitly enable and configure the "io_manager.active_sessions" metric:

import { start } from "@interopio/manager";

const config = {
    otel: {
        enabled: true,
        resource: {
            serviceName: "io-manager"
        },
        metrics: {
            enabled: true,
            url: "http://localhost:4318/v1/metrics",
            // Disabling all available metrics
            defaultMetricsEnabled: false,
            // Enabling and configuring the `"io_manager.active_sessions"` metric.
            metrics: [
                {
                    type: "io_manager.active_sessions",
                    enabled: true,
                    publishInterval: 45000
                }
            ]
        }
    }
};

const server = await start(config);

The following sections describe each individual metric published by the io.Manager Server.

http.server.active_requests

The instrument type of the "http.server.active_requests" metric is UpDownCounter.

The following environment variables are available for configuring the "http.server.active_requests" metric:

The following properties are available for configuring the "http.server.active_requests" metric via the configuration object for initializing the io.Manager Server:

http.server.request.body.size

The instrument type of the "http.server.request.body.size" metric is Histogram.

The following environment variables are available for configuring the "http.server.request.body.size" metric:

The following properties are available for configuring the "http.server.request.body.size" metric via the configuration object for initializing the io.Manager Server:

http.server.request.duration

The instrument type of the "http.server.request.duration" metric is Histogram.

The following environment variables are available for configuring the "http.server.request.duration" metric:

The following properties are available for configuring the "http.server.request.duration" metric via the configuration object for initializing the io.Manager Server:

http.server.response.body.size

The instrument type of the "http.server.response.body.size" metric is Histogram.

The following environment variables are available for configuring the "http.server.response.body.size" metric:

The following properties are available for configuring the "http.server.response.body.size" metric via the configuration object for initializing the io.Manager Server:

io_manager.active_sessions

The instrument type of the "io_manager.active_sessions" metric is Gauge.

The following environment variables are available for configuring the "io_manager.active_sessions" metric:

The following properties are available for configuring the "io_manager.active_sessions" metric via the configuration object for initializing the io.Manager Server:

Metrics Exporter

The io.Manager Server provides an out-of-the-box implementation of an OTLPMetricExporter for sending metrics to an OpenTelemetry Collector via HTTP.

For more advanced scenarios, it's possible to provide an instance of a custom metrics exporter by using the customExporter property of the metrics object in the configuration object for initializing the io.Manager Server.

⚠️ Note that it isn't possible to provide a custom metrics exporter via environment variables.

For a complete example, see the OpenTelemetry Custom Metrics Exporter example on GitHub.

Metrics Reader

The io.Manager Server provides an out-of-the-box implementation of a PeriodicExportingMetricReader for exporting metrics periodically.

For more advanced scenarios, it's possible to provide an instance of a custom metrics reader by using the customReader property of the metrics object in the configuration object for initializing the io.Manager Server.

⚠️ Note that it isn't possible to provide a custom metrics reader via environment variables.

For a complete example, see the OpenTelemetry Custom Metrics Reader example on GitHub.