Configuring OpenTelemetry for your instance

OpenTelemetry metrics are the future foundation for monitoring, available from GitHub Enterprise Server 3.18 onward. This new monitoring stack provides enhanced observability and management capabilities compared to the legacy collectd system.

Collectd metrics continue to be gathered by default and remain fully supported in this release.

注意

OpenTelemetry metrics are in 公共预览版 and subject to change. We would love to hear your feedback on the preview. You can share it with your customer success team, or leave a comment in the community discussion post.

Prerequisites

GitHub Enterprise Server 3.18 or later
Administrative access to the 管理控制台
SSH access to your GitHub Enterprise Server appliance

Enabling OpenTelemetry metrics

OpenTelemetry metrics are disabled by default. You can enable them through the 管理控制台 or command line.

Using the 管理控制台

在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。
如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。
在“ 站点管理”边栏中，单击“管理控制台”****。
In the monitoring settings, select Enable OpenTelemetry.
在“设置”边栏下，单击“保存设置”。

注意

保存管理控制台中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。
等待配置运行完毕。

Using the command line

通过 SSH 连接到你的 GitHub Enterprise Server 实例。如果实例包含多个节点，例如，如果配置了高可用性或异地复制，则通过 SSH 连接到主节点。如果使用群集，则可以通过 SSH 连接到任何节点。将 HOSTNAME 替换为实例的主机名，或节点的主机名或 IP 地址。有关详细信息，请参阅“访问管理 shell (SSH)”。
Shell
```
ssh -p 122 admin@HOSTNAME
```
```
ssh -p 122 admin@HOSTNAME
```
Run the following command to enable OpenTelemetry metrics.
```
ghe-config observability.metrics.next-enabled true
```
若要应用配置，请运行以下命令。

注意

在配置运行过程中，你的 GitHub Enterprise Server 实例上的服务可能会重启，这可能会导致用户短暂停机。
Shell
```
ghe-config-apply
```
```
ghe-config-apply
```
等待配置运行完毕。

Performance considerations

When configuring OpenTelemetry metrics, consider the following performance factors:

Collection frequency: More frequent collection increases system load
Data retention: Longer retention periods require more storage
Custom exporters: Additional exporters may increase CPU and memory usage
Network bandwidth: External metric shipping affects network usage

Configuring metrics collection

After enabling OpenTelemetry metrics, you can customize various aspects of the metrics collection process.

Setting collection intervals

The default metrics collection interval is 30 seconds. You can adjust this based on your monitoring needs.

重要

Setting shorter intervals increases the precision of metrics but also increases storage requirements and system load. Consider your system resources and monitoring requirements before adjusting this setting.

Using the 管理控制台 to set intervals

在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。
如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。
在“ 站点管理”边栏中，单击“管理控制台”****。
In the monitoring settings, under Metrics scrape interval, enter the desired interval in seconds (for example, 60).
在“设置”边栏下，单击“保存设置”。

注意

保存管理控制台中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。
等待配置运行完毕。

Using the command line to set intervals

SSH into your GitHub Enterprise Server appliance and run the following commands:

# Set scrape interval to 60 seconds
ghe-config observability.metrics.interval 60
ghe-config-apply

Configuring data retention

By default, metrics data is retained for 30 days. You can modify this setting using either the 管理控制台 or command line.

Using the 管理控制台 to configure retention

在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。
如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。
在“ 站点管理”边栏中，单击“管理控制台”****。
In the monitoring settings, under Metrics retention, enter the desired retention period in days (for example, 15).
在“设置”边栏下，单击“保存设置”。

注意

保存管理控制台中的设置会重启系统服务，这可能会导致用户可察觉的停机时间。
等待配置运行完毕。

Using the command line to configure retention

SSH into your GitHub Enterprise Server appliance and run the following commands:

# Set retention to 15 days
ghe-config observability.metrics.retention 15
ghe-config-apply

Configuring the verbosity level for internal telemetry

The OpenTelemetry collector generates its own internal telemetry data for monitoring the health and performance of the collector itself. You can configure the verbosity of this internal telemetry using the command line.

The available telemetry levels are:

none: Disables internal telemetry
basic: Provides essential telemetry data (default)
normal: Provides standard telemetry data
detailed: Provides verbose telemetry data for debugging

SSH into your GitHub Enterprise Server appliance and run the following commands:

# Set internal telemetry level to normal
ghe-config observability.metrics.internal-otel-telemetry-level normal
ghe-config-apply

注意

Higher telemetry levels provide more detailed information about the collector's internal operations but also increase resource usage. The basic level is recommended for production environments unless you need to troubleshoot collector issues.

Troubleshooting configuration issues

If you encounter problems with OpenTelemetry configuration, the following information can help you identify and resolve common issues.

Common configuration problems

Service startup failures: Check system logs for error messages
Resource constraints: Monitor system resources when adjusting collection intervals

Viewing local logs

SSH into the node you want to debug and run the following commands:

View OpenTelemetry collector logs:

sudo journalctl -u otelcol-contrib -f

View VictoriaMetrics logs:

sudo journalctl -u victoriametrics -f

Next steps

To enable advanced monitoring dashboards, see Enabling advanced dashboards of OpenTelemetry metrics
To set up external monitoring, see Setting up external monitoring with OpenTelemetry.

本文内容