From 5aafafd82fe9c8bc38c6afaebeeb641d06c4a485 Mon Sep 17 00:00:00 2001 From: Kacz <71774507+KaczDev@users.noreply.github.com> Date: Fri, 30 Oct 2026 17:35:01 +0000 Subject: [PATCH 1/2] GHES: collectd to OpenTelemetry stack migration guidance (#63856) Co-authored-by: Dan O'Brien Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> --- .../about-monitoring-your-instance.md | 15 +++- .../about-the-monitor-dashboards.md | 6 +- ...iguring-opentelemetry-for-your-instance.md | 16 +++- .../opentelemetry-metrics/index.md | 1 + .../migration-guidance.md | 80 +++++++++++++++++++ .../recommended-alert-thresholds.md | 4 + .../enterprise/collectd-metrics-future.md | 4 +- .../enterprise/opentelemetry-migration.md | 12 ++- 8 files changed, 125 insertions(+), 13 deletions(-) create mode 100644 content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance.md diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-monitoring-your-instance.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-monitoring-your-instance.md index 6b14648c7aa1..dd000f8c2988 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-monitoring-your-instance.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-monitoring-your-instance.md @@ -10,12 +10,21 @@ category: ## Metrics -OpenTelemetry metrics were introduced in {% data variables.product.prodname_ghe_server %} 3.18 and are the future foundation for monitoring your {% data variables.product.prodname_ghe_server %} instance. -Collectd metrics will continue to be gathered by default, but we expect collectd metrics to be discontinued in a future release. +OpenTelemetry metrics were introduced in {% data variables.product.prodname_ghe_server %} 3.18 and are the foundation for monitoring {% data variables.product.prodname_ghe_server %} instances. + +{% ifversion ghes < 3.23 %} + +New installations of version 3.19 and later use OpenTelemetry metrics by default. On version 3.18, and on instances upgraded from earlier releases, collectd metrics are still gathered by default. Collectd is retired in version 3.23, and upgrading to 3.23 disables it. For migration guidance for instances that still use collectd, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). + +{% else %} + +Collectd is retired in version 3.23 and can no longer be run. Upgrading to 3.23 disables collectd, and OpenTelemetry metrics are the only metrics stack. + +{% endif %} For more information about OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics). -For more information about Collectd metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics/about-collectd-metrics). +For more information about collectd metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics/about-collectd-metrics). ## Dashboards diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md index a1e9c9ff5ce7..7832b7d2e803 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md @@ -52,12 +52,14 @@ Starting with {% data variables.product.prodname_ghe_server %} 3.18, you can cre > [!IMPORTANT] Pre-built dashboards can be opened and edited for inspection, but changes cannot be saved. Create a copy of a dashboard to apply and retain any customizations. -You can use OpenTelemetry and collectd metrics concurrently for external monitoring. During the {% data variables.release-phases.public_preview %}, collectd remains enabled and cannot be disabled. - For more information about OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics). +{% ifversion ghes < 3.23 %} + For more information about collectd metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics/about-collectd-metrics). +{% endif %} + ## About the metrics on the monitor dashboards The monitor dashboards provide a comprehensive view of various metrics that help in understanding the performance and health of your {% data variables.product.prodname_ghe_server %} instance. These metrics are categorized into different sections to make it easier to analyze specific aspects of the system. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md index 7d76dd58077d..d9e8b7266919 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/configuring-opentelemetry-for-your-instance.md @@ -25,13 +25,17 @@ category: ## Enabling OpenTelemetry metrics +{% ifversion ghes < 3.23 %} + {% ifversion ghes > 3.18 %} -OpenTelemetry metrics are enabled by default for **new installations** of {% data variables.product.prodname_ghe_server %} 3.19 and later. Upgrades to {% data variables.product.prodname_ghe_server %} 3.19 will still have `collectd` metrics enabled by default, but you can choose to switch to OpenTelemetry metrics. +OpenTelemetry metrics are enabled by default for **new installations** of {% data variables.product.prodname_ghe_server %} 3.19 and later. Instances upgraded from earlier releases still have collectd metrics enabled by default. For the complete migration procedure for instances that still use collectd, including how to disable collectd, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). {% else %} -OpenTelemetry metrics are disabled by default. You can enable them through the {% data variables.enterprise.management_console %} or command line. +OpenTelemetry metrics are disabled by default. They can be enabled through the {% data variables.enterprise.management_console %} or command line. + +{% endif %} ### Using the {% data variables.enterprise.management_console %} @@ -49,10 +53,14 @@ OpenTelemetry metrics are disabled by default. You can enable them through the { ```shell ghe-config observability.metrics.next-enabled true - ``` + ``` {% data reusables.enterprise.apply-configuration %} +{% else %} + +OpenTelemetry metrics are always enabled and are the only supported metrics stack. Collectd is retired in {% data variables.product.prodname_ghe_server %} 3.23 and later, and upgrading from an earlier version disables it. For information about post-upgrade checks and historical collectd data, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). + {% endif %} ## Performance considerations @@ -166,5 +174,5 @@ sudo journalctl -u victoriametrics -f ## Next steps * To enable advanced monitoring dashboards, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/advanced-dashboards) -* Exploring OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/using-grafana-to-analyze-opentelemetry-metrics). +* To explore OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/using-grafana-to-analyze-opentelemetry-metrics) * To set up external monitoring, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry). diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md index 968337abe0bc..bcc4390f7322 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/index.md @@ -5,6 +5,7 @@ versions: feature: ghes-opentelemetry children: - /about-opentelemetry-metrics + - /migration-guidance - /configuring-opentelemetry-for-your-instance - /advanced-dashboards - /using-grafana-to-analyze-opentelemetry-metrics diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance.md new file mode 100644 index 000000000000..6f24022bfd3f --- /dev/null +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance.md @@ -0,0 +1,80 @@ +--- +title: Migrating from collectd to OpenTelemetry +intro: This guide describes the migration of a {% data variables.product.prodname_ghe_server %} instance from collectd to the OpenTelemetry metrics stack. +versions: + feature: ghes-opentelemetry +shortTitle: Migration guidance +contentType: how-tos +category: + - Monitor and audit your enterprise +--- + +{% data variables.product.prodname_ghe_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](#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 {% data variables.enterprise.management_console %} or the command line. + +### Using the {% data variables.enterprise.management_console %} + +{% data reusables.enterprise_site_admin_settings.access-settings %} +{% data reusables.enterprise_site_admin_settings.management-console %} + +1. In the monitoring settings, select **Enable OpenTelemetry**. +1. Under **Metrics - Collectd**, select **Disable collectd metrics**. + +{% data reusables.enterprise_management_console.save-settings %} + +### Using the command line + +{% data reusables.enterprise_installation.ssh-into-instance %} +1. To enable OpenTelemetry metrics and disable collectd, run the following commands. + + ```shell + ghe-config observability.metrics.next-enabled true + ghe-config observability.metrics.legacy-disabled true + ``` + +{% data reusables.enterprise.apply-configuration %} + +### 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 {% data variables.enterprise.management_console %}. +* Update monitoring integrations that depend on collectd metrics. For information about connecting external tools, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/setting-up-external-monitoring-with-opentelemetry). +* For information about analyzing metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/using-grafana-to-analyze-opentelemetry-metrics). + +### 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. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md index c234855b7330..e545874d262a 100644 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md +++ b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md @@ -24,8 +24,12 @@ You can configure external monitoring systems to alert you to storage, CPU, and For more information about OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics). +{% ifversion ghes < 3.23 %} + For more information about collectd metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics/about-collectd-metrics). +{% endif %} + For more information about the monitor dashboards, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards). ## Monitoring storage diff --git a/data/reusables/enterprise/collectd-metrics-future.md b/data/reusables/enterprise/collectd-metrics-future.md index d7e0a8b1c0ff..0b7dfa895ff1 100644 --- a/data/reusables/enterprise/collectd-metrics-future.md +++ b/data/reusables/enterprise/collectd-metrics-future.md @@ -2,7 +2,7 @@ Collectd metrics are gathered by default and are fully supported in this release. OpenTelemetry metrics are the future foundation for monitoring, available from {% data variables.product.prodname_ghe_server %} 3.18 onward. -> [!NOTE] -> Collectd metrics are expected to be {% data variables.release-phases.closing_down %} and then {% data variables.release-phases.retired %} in a future release of {% data variables.product.prodname_ghe_server %}. We recommend that your long-term monitoring strategy includes a migration to OpenTelemetry metrics. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics). +> [!IMPORTANT] +> Collectd metrics are {% data variables.release-phases.retired %} in {% data variables.product.prodname_ghe_server %} 3.23. We recommend migrating to OpenTelemetry metrics before upgrading. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). {% endif %} diff --git a/data/reusables/enterprise/opentelemetry-migration.md b/data/reusables/enterprise/opentelemetry-migration.md index 1ebe5f2ce7ac..8308cfb1e798 100644 --- a/data/reusables/enterprise/opentelemetry-migration.md +++ b/data/reusables/enterprise/opentelemetry-migration.md @@ -1,7 +1,15 @@ {% ifversion ghes-opentelemetry %} -OpenTelemetry metrics are the future foundation for monitoring, available from {% data variables.product.prodname_ghe_server %} 3.18 onward. This new monitoring stack provides enhanced observability and management capabilities compared to the legacy collectd system. +OpenTelemetry metrics are the foundation for monitoring {% data variables.product.prodname_ghe_server %}, available from version 3.18 onward. This 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. +{% ifversion ghes < 3.23 %} + +New installations of version 3.19 and later use OpenTelemetry metrics by default. On version 3.18, and on instances upgraded from earlier releases, collectd metrics are still gathered by default and remain supported in this release. Collectd is retired in version 3.23, and upgrading to 3.23 disables it. Migration to OpenTelemetry is recommended before upgrading instances that still use collectd. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). + +{% else %} + +Collectd is retired in this release and can no longer be run. Upgrading to version 3.23 disables collectd, and OpenTelemetry metrics become the only metrics stack. For information about post-upgrade checks, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/migration-guidance). + +{% endif %} {% endif %} From 7789d8b90cca3ee60ccfb43329b81e42c836d7d8 Mon Sep 17 00:00:00 2001 From: Leyla Azizova Date: Fri, 30 Oct 2026 19:47:05 +0000 Subject: [PATCH 2/2] Clarify license compliance snapshot requirements (#64481) Co-authored-by: Leyla Azizova <289007686+leyla-zova@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../open-source-license-compliance.md | 8 ++++++++ .../configure-license-policies.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/content/code-security/concepts/supply-chain-security/open-source-license-compliance.md b/content/code-security/concepts/supply-chain-security/open-source-license-compliance.md index 45f27ac2b8b4..6d724533c0bd 100644 --- a/content/code-security/concepts/supply-chain-security/open-source-license-compliance.md +++ b/content/code-security/concepts/supply-chain-security/open-source-license-compliance.md @@ -36,6 +36,14 @@ If there is a ruleset in **Active** mode which uses the "Requires license compli Additionally, a [branch protection rule](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) that requires comment resolution before merging will track annotations from license checks, so even alerts generated by **Evaluate** rulesets will be subject to the protection. +### Dependency snapshots + +Dependency snapshots describe a repository's dependencies at a specific commit. License compliance compares snapshots for the base and head commits of a pull request to identify added dependencies and evaluate their licenses against your policy. + +For each detector that submitted a snapshot for the base commit, the check waits for a snapshot from that detector for the exact head commit. The check resumes when all required snapshots arrive. For example, if a workflow or external system submits snapshots only for commits to the default branch, the head commit does not receive that detector's snapshot and the check remains waiting. + +Automatic dependency submission runs on both the base and head commits. When it submits the snapshots your repository needs, you do not need to add another detector. For more information about automatic dependency submission, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/submit-dependencies-automatically). + ## Where results appear If a dependency's license isn't in your policy, findings will appear in pull request annotations. The annotations do not automatically generate an exception request, because the developer could decide to modify their code to avoid the noncompliant dependency. If they do want to use the dependency, {% data variables.product.github %} will prompt the developer for more information, then send the closure request to the Enterprise Open Source License Managers, who have permission to modify the policy. diff --git a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-license-policies.md b/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-license-policies.md index 586929943e71..dc0e5862139e 100644 --- a/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-license-policies.md +++ b/content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configure-license-policies.md @@ -106,6 +106,14 @@ For more information about rulesets, see [AUTOTITLE](/repositories/configuring-b If the ruleset is in **Active** mode, the pull request remains blocked until all license policy violations are resolved. +## Troubleshooting checks waiting for dependency snapshots + +If a license compliance check reports `Waiting for dependency snapshots on head`, the pull request's head commit is missing one or more snapshots that were submitted for the base commit. This can happen when a workflow submits snapshots for the base branch but does not submit them for the pull request's head commit. + +The message can list detectors that submitted a snapshot for the base commit but not yet for the head commit. Review those detectors and the workflows or external systems that submit their snapshots. If you submit snapshots through your own workflow or the {% data variables.dependency-submission-api.name %}, configure it to also submit snapshots for the pull request's head commit. If automatic dependency submission is enabled and already submits the snapshots your repository needs, you do not need to add another detector. Adding another detector can increase the number of snapshots the check expects on the head commit. + +For more information about snapshot submission, see [AUTOTITLE](/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/use-dependency-submission-api). + ## Managing license compliance requests and policy ### Review and handle exception requests