OpenTelemetry Support

Available since io.Manager Server 1.7.0

io.Manager offers OpenTelemetry support for publishing metrics, traces, and logs.

⚠️ Note that the io.Manager Admin UI isn't instrumented to generate OpenTelemetry signals. The io.Manager Server will still generate metrics, traces, and logs for requests made by the io.Manager Admin UI, but the <AdminUI /> component itself won't generate any OpenTelemetry signals.

For details on the OpenTelemetry concepts, terminology, and APIs, see the official OpenTelemetry documentation.

OpenTelemetry support is disabled by default. You can enable it via the configuration object for initializing the io.Manager Server, or via environment variables, depending on your deployment approach.

⚠️ Note that all supported features, such as metrics, traces, and logs, are disabled by default and must be enabled explicitly. For details on how to enable and configure the supported OpenTelemetry features, see the respective sections.

Environment Variables

To enable OpenTelemetry support for the io.Manager Server and configure the resource attributes, register the following environment variables with the proper values. The API_OTEL_ENABLED environment variable must be set to true:

Environment Variable	Description
API_OTEL_ENABLED	If true, will enable publishing OpenTelemetry data. Defaults to false.
API_OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT	Value for the deployment.environment.name resource attribute. Name of the deployment environment.
API_OTEL_RESOURCE_INSTANCE_ID	Value for the service.instance.id resource attribute. Must be unique for each service.namespace and service.name pair. The instance ID helps to distinguish instances of the same service that exist at the same time (e.g., instances of a horizontally scaled service).
API_OTEL_RESOURCE_SERVICE_NAME	Value for the service.name resource attribute. Logical name of the service. Must be the same for all instances of horizontally scaled services. Required if API_OTEL_ENABLED is set to true.
API_OTEL_RESOURCE_SERVICE_NAMESPACE	Value for the service.namespace resource attribute. Namespace for the service.name attribute. This should be a value that will help distinguish a group of services semantically from other groups of services - e.g., the name of the team that owns the group of services. The value of each service.name attribute within the same namespace must be unique. If a service.namespace attribute isn't specified for the resource, then the service.name attribute must be unique among all services without an explicitly defined namespace (an unspecified namespace is simply one more valid namespace). A zero-length string value for a namespace equals an unspecified namespace.

Example configuration:

API_OTEL_ENABLED=true
API_OTEL_RESOURCE_SERVICE_NAME=io-manager
API_OTEL_RESOURCE_SERVICE_NAMESPACE=servers
API_OTEL_RESOURCE_INSTANCE_ID=instance1
API_OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=production

Configuration Object

To enable OpenTelemetry support for the io.Manager Server and configure the resource attributes, use the otel property of the optional Config object for initializing the io.Manager Server:

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

const config = {
    // Enabling OpenTelemetry support and configuring the resource attributes.
    otel: {
        enabled: true,
        resource: {
            serviceName: "io-manager",
            serviceNamespace: "servers",
            serviceInstanceID: "instance1",
            deploymentEnvironment: "production",
        }
    }
};

const server = await start(config);

The otel object has the following properties:

Property	Type	Description
diagnosticLoggerLevel	enum	DiagLogLevel enumeration specifying the logging level for the OpenTelemetry diagnostic logger. This is only used to diagnose issues with the OpenTelemetry setup or SDK. Defaults to DiagLogLevel.WARN.
enabled	boolean	If true, will enable publishing OpenTelemetry data. Defaults to false.
logs	object	Settings for publishing OpenTelemetry logs.
metrics	object	Settings for publishing OpenTelemetry metrics.
resource	object	Required. OpenTelemetry resource configuration.
traces	object	Settings for publishing OpenTelemetry traces.

The resource object has the following properties:

Property	Type	Description
customAttributes	object	An Attributes object representing a set of custom attributes that will be applied to the resource.
deploymentEnvironment	string	Value for the deployment.environment.name resource attribute. Name of the deployment environment.
serviceInstanceID	string	Value for the service.instance.id resource attribute. Must be unique for each service.namespace and service.name pair. The instance ID helps to distinguish instances of the same service that exist at the same time (e.g., instances of a horizontally scaled service).
serviceName	string	Required. Value for the service.name resource attribute. Logical name of the service. Must be the same for all instances of horizontally scaled services.
serviceNamespace	string	Value for the service.namespace resource attribute. Namespace for the service.name attribute. This should be a value that will help distinguish a group of services semantically from other groups of services - e.g., the name of the team that owns the group of services. The value of each service.name attribute within the same namespace must be unique. If a service.namespace attribute isn't specified for the resource, then the service.name attribute must be unique among all services without an explicitly defined namespace (an unspecified namespace is simply one more valid namespace). A zero-length string value for a namespace equals an unspecified namespace.