Configuring OpenTelemetry for your instance

Learn how to configure OpenTelemetry metrics collection on your GitHub Enterprise Server instance for enhanced monitoring and observability.

이 문서의 내용

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 관리 콘솔

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

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

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

  4. In the monitoring settings, select Enable OpenTelemetry.

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

    참고 항목

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

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

Using the command line

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

    Shell
    ssh -p 122 admin@HOSTNAME

  2. Run the following command to enable OpenTelemetry metrics.

    ghe-config observability.metrics.next-enabled true

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

    참고 항목

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

    Shell
    ghe-config-apply

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

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

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

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

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

  4. In the monitoring settings, under Metrics scrape interval, enter the desired interval in seconds (for example, 60).

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

    참고 항목

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

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

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

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

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

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

  4. In the monitoring settings, under Metrics retention, enter the desired retention period in days (for example, 15).

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

    참고 항목

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

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

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