# Overview

Source: https://docs.interop.io/manager/opentelemetry-support/overview/index.html

## Overview

Available since io.Manager Server 1.7

**io.Manager** offers [OpenTelemetry](https://opentelemetry.io/) support for publishing [metrics](https://docs.interop.io/manager/opentelemetry-support/metrics/index.md), [traces](https://docs.interop.io/manager/opentelemetry-support/traces/index.md), and [logs](https://docs.interop.io/manager/opentelemetry-support/logs/index.md).

> ⚠️ *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](https://opentelemetry.io/docs/).*

> ℹ️ *For complete examples of enabling OpenTelemetry support in **io.Manager** and customizing the supported OpenTelemetry features, see the [**io.Manager** Examples](https://github.com/InteropIO/manager-examples) repository on GitHub.*

## Enabling OpenTelemetry Support

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](https://docs.interop.io/manager/deployment/index.md) approach.

> ⚠️ *Note that all supported features, such as [metrics](https://docs.interop.io/manager/opentelemetry-support/metrics/index.md), [traces](https://docs.interop.io/manager/opentelemetry-support/traces/index.md), and [logs](https://docs.interop.io/manager/opentelemetry-support/logs/index.md), 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](https://opentelemetry.io/docs/concepts/resources/) 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`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/deployment/#deployment-environment-name) resource attribute. Name of the deployment environment. |
| `API_OTEL_RESOURCE_INSTANCE_ID` | Value for the [`service.instance.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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:

```cmd
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](https://opentelemetry.io/docs/concepts/resources/) attributes, use the `otel` property of the optional `Config` object for initializing the **io.Manager** Server:

```javascript
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",
    	},
        // You must explicitly enable each supported feature.
        // For more details on the available settings for metrics, traces, and logs,
        // see the respective documentation section.
        metrics: {
    	    enabled: true,
    	    url: "http://localhost:4318/v1/metrics"
        },
        traces: {
    	    enabled: true,
    	    url: "http://localhost:4318/v1/traces"
        },
        logs: {
    	    enabled: true,
    	    url: "http://localhost:4318/v1/logs"
        }
    }
};

const server = await start(config);
```

The `otel` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `diagnosticLoggerLevel` | `enum` | [`DiagLogLevel`](https://open-telemetry.github.io/opentelemetry-js/enums/_opentelemetry_api._opentelemetry_api.DiagLogLevel.html) 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](https://docs.interop.io/manager/opentelemetry-support/logs/index.md). |
| `metrics` | `object` | Settings for publishing OpenTelemetry [metrics](https://docs.interop.io/manager/opentelemetry-support/metrics/index.md). |
| `resource` | `object` | **Required.** OpenTelemetry [resource](https://opentelemetry.io/docs/concepts/resources/) configuration. |
| `traces` | `object` | Settings for publishing OpenTelemetry [traces](https://docs.interop.io/manager/opentelemetry-support/traces/index.md). |

The `resource` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `customAttributes` | `object` | An [`Attributes`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api._opentelemetry_api.Attributes.html) object representing a set of custom attributes that will be applied to the resource. |
| `deploymentEnvironment` | `string` | Value for the [`deployment.environment.name`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/deployment/#deployment-environment-name) resource attribute. Name of the deployment environment. |
| `serviceInstanceID` | `string` | Value for the [`service.instance.id`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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`](https://opentelemetry.io/docs/specs/semconv/attributes-registry/service/#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

For a complete example of enabling OpenTelemetry support in **io.Manager**, see the [Basic OpenTelemetry](https://github.com/InteropIO/manager-examples/tree/main/otel-basic) example on GitHub.