io.Manager Documentation

OpenTelemetry Support

Overview

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

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

Enabling Logs Exports

Publishing logs is disabled by default. To enable publishing logs, you must enable OpenTelemetry support in the io.Manager Server and explicitly enable the logs 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 logs, register the following environment variables with the proper values. The API_OTEL_LOGS_ENABLED environment variable must be set to true:

Environment Variable Description
API_OTEL_LOGS_ENABLED If true, will enable publishing OpenTelemetry logs. Defaults to false.
API_OTEL_LOGS_MAX_LEVEL The maximum event level to emit via the OpenTelemetry SDK. Possible values are ALL, MARK, TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Defaults to FATAL.
API_OTEL_LOGS_MIN_LEVEL The minimum event level to emit via the OpenTelemetry SDK. Possible values are ALL, MARK, TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Defaults to INFO.
API_OTEL_LOGS_PUBLISH_INTERVAL Interval in milliseconds between two consecutive log exports. Passed as a value to the scheduledDelayMillis property of the BufferConfig constructor parameter when creating a BatchLogRecordProcessor instance. This is the default log processor used by the io.Manager Server. Ignored when a custom log processor is used. Defaults to 5000.
API_OTEL_LOGS_URL URL pointing to an OpenTelemetry Collector where the generated logs will be sent via HTTP. Passed as a value to the url property of the OTLPExporterNodeConfigBase constructor parameter when creating an OTLPLogExporter instance. This is the default log exporter used by the io.Manager Server. Required if using the default log exporter and log processor. Ignored when either a custom log exporter or a custom log processor is used.

The following example demonstrates how to enable OpenTelemetry support, how to enable publishing logs, and how to configure the minimum log level and the interval for publishing logs:

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

# Enabling and configuring logs.
API_OTEL_LOGS_ENABLED=true
API_OTEL_LOGS_URL=http://localhost:4318/v1/logs
API_OTEL_LOGS_MIN_LEVEL=WARN
API_OTEL_LOGS_PUBLISH_INTERVAL=10000

Configuration Object

To enable publishing logs, use the logs 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 logs, and how to configure the minimum log level and the interval for publishing logs:

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

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

const server = await start(config);

The logs object has the following properties:

Property Type Description
customExporter object LogRecordExporter instance of a custom log exporter to be used instead of the default log exporter. Ignored when a custom log processor is used.
customProcessor object LogRecordProcessor instance of a custom log processor to be used instead of the default log processor.
enabled boolean If true, will enable publishing OpenTelemetry logs. Defaults to false.
maxLevel string The maximum event level to emit via the OpenTelemetry SDK. Possible values are "ALL", "MARK", "TRACE", "DEBUG", "INFO", "WARN", "ERROR", and "FATAL". Defaults to "FATAL".
minLevel string The minimum event level to emit via the OpenTelemetry SDK. Possible values are "ALL", "MARK", "TRACE", "DEBUG", "INFO", "WARN", "ERROR", and "FATAL". Defaults to "INFO".
publishInterval number Interval in milliseconds between two consecutive log exports. Passed as a value to the scheduledDelayMillis property of the BufferConfig constructor parameter when creating a BatchLogRecordProcessor instance. This is the default log processor used by the io.Manager Server. Ignored when a custom log processor is used. Defaults to 5000.
url string URL pointing to an OpenTelemetry Collector where the generated logs will be sent via HTTP. Passed as a value to the url property of the OTLPExporterNodeConfigBase constructor parameter when creating an OTLPLogExporter instance. This is the default log exporter used by the io.Manager Server. Required if using the default log exporter and log processor. Ignored when either a custom log exporter or a custom log processor is used.

Customization

Log Exporter

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

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

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

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

Log Processor

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

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

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

For a complete example, see the OpenTelemetry Custom Log Processor example on GitHub.