Migrating from collectd to OpenTelemetry

GitHub Enterprise Server is transitioning from the collectd metrics stack to OpenTelemetry. Collectd is retired in version 3.23, and upgrading to 3.23 disables it.

Migration timeline

Version	Default for new installations	Default for instances upgraded from earlier releases	Notes
3.18	Collectd	Collectd	OpenTelemetry is opt-in.
3.19 to 3.22	OpenTelemetry	Collectd	Migration to OpenTelemetry is possible before upgrading to 3.23.
3.23 and later	OpenTelemetry	OpenTelemetry	Collectd is retired and cannot be used. The upgrade disables it.

Preparing to migrate

Before you migrate, complete the following preparations:

• Test the migration on a staging instance before applying it in production.
• Identify the monitoring integrations that depend on collectd metrics, such as external dashboards and alerts.
• If you plan to run both metrics stacks during a transition period, review the caveats in Running both metrics stacks.

Migrating to OpenTelemetry

You can migrate to OpenTelemetry on instances running version 3.19 to 3.22. On version 3.18, OpenTelemetry is opt-in, so you can also enable it there. We recommend migrating before you upgrade to 3.23, so that you can verify your monitoring setup while you can still use collectd.

If you don't migrate, upgrading to version 3.23 or later does it for you: collectd is disabled and cannot be re-enabled, and OpenTelemetry metrics are enabled and become the only metrics stack.

Migration requires enabling OpenTelemetry metrics and disabling collectd. Both settings are available through the 관리 콘솔 or the command line.

Using the 관리 콘솔

1. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.

2. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.

3. " 사이트 관리자" 사이드바에서 관리 콘솔 을 클릭합니다.

4. In the monitoring settings, select Enable OpenTelemetry.

5. Under Metrics - Collectd, select Disable collectd metrics.

6. "설정" 사이드바에서 설정 저장을 클릭합니다.

   참고

   관리 콘솔에 설정을 저장하면 시스템 서비스가 다시 시작되어 사용자에게 표시되는 가동 중지 시간이 발생할 수 있습니다.

7. 구성 실행이 완료될 때까지 기다립니다.

Using the command line

1. SSH into GitHub Enterprise Server 인스턴스. 인스턴스가 여러 노드로 구성된 경우(예: 고가용성 또는 지역 복제가 구성된 경우) 주 노드에 대한 SSH를 수행합니다. 클러스터를 사용하는 경우 임의 노드에 대해 SSH를 수행할 수 있습니다. HOSTNAME을 인스턴스의 호스트 이름 또는 노드의 호스트 이름이나 IP 주소로 바꿉니다. 자세한 내용은 관리 셸(SSH)에 액세스을(를) 참조하세요.

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. To enable OpenTelemetry metrics and disable collectd, run the following commands.

   ghe-config observability.metrics.next-enabled true
   ghe-config observability.metrics.legacy-disabled true
   

3. 구성을 적용하려면 다음 명령을 실행합니다.

   참고

   구성을 실행하는 동안 GitHub Enterprise Server 인스턴스의 서비스가 다시 시작될 수 있으므로 짧은 가동 중지 시간이 발생할 수 있습니다.

   Shell

   ghe-config-apply
   

4. 구성 실행이 완료될 때까지 기다립니다.

Running both metrics stacks

On version 3.18 to 3.22, running the collectd and OpenTelemetry stacks at the same time is possible but not recommended. This configuration has the following caveats:

• Some metric names may differ to remain compatible with the collectd format.
• Some OpenTelemetry metrics do not include labels.
• Increased resource utilization to deliver metrics to both solutions.

Collectd is retired in version 3.23, so running both stacks is not possible after upgrading.

Post-upgrade checks

After the configuration run completes, whether you migrated manually or upgraded to version 3.23 or later:

• Verify that the metrics are visible and collected in the Monitoring tab of the 관리 콘솔.
• Update monitoring integrations that depend on collectd metrics. For information about connecting external tools, see OpenTelemetry를 사용하여 외부 모니터링 설정.
• For information about analyzing metrics, see Grafana를 사용하여 OpenTelemetry 메트릭 분석.

Viewing historical collectd data

Since patches 3.22.3, 3.21.8, 3.20.10, and 3.19.14, the Monitoring tab includes collectd dashboards for viewing historical data. These dashboards display collectd metrics recorded up to the time the collectd stack was disabled.