Improve RebuildableSetCache structured logging

What does this MR do and why?

Improve RebuildableSetCache structured logging

Contributes to https://gitlab.com/gitlab-org/gitlab/-/issues/586463

Problem

During the rollout of the ref_cache_with_rebuild_queue feature flag, three logging issues were identified:

  1. json.meta.project was missing in logs when accessed from GraphQL code paths where the project was not in the ApplicationContext.
  2. json.ref displayed as NaN in Kibana due to a field name collision with an existing indexed field.
  3. json.message was always RebuildableSetCache, duplicating json.class without adding value. Additionally, high-volume info logs (e.g. cache_hit on every page load) could significantly increase log volume at scale.

Solution

  • Wrap log emission in Gitlab::ApplicationContext.with_context(project:) so json.meta.project is always populated.
  • Nest domain-specific fields under a rebuildable_cache key (e.g. json.rebuildable_cache.ref) to avoid Kibana field collisions.
  • Set json.message to the event name (e.g. cache_hit, rebuild_started) for better readability.
  • Gate all non-error info logs behind a new ref_cache_verbose_logging feature flag (disabled by default). Error logs always emit.

References

Screenshots or screen recordings

{
  "severity": "INFO",
  "time": "2026-05-13T09:25:57.948Z",
  "correlation_id": "e102b8ed3b9962f595315c6a179bfd13",
  "meta.project": "namespace1/project-1",
  "meta.root_namespace": "namespace1",
  "message": "rebuild_started",
  "class": "Gitlab::Repositories::RebuildableSetCache",
  "rebuildable_cache": {
    "event": "rebuild_started",
    "cache_key": "branch_names",
    "canonical_count": 4
  }
}

How to set up and validate locally

  1. Enable the feature flags:
    Feature.enable(:ref_cache_with_rebuild_queue)
    Feature.enable(:ref_cache_verbose_logging)
  2. Push a branch to a project.
  3. Check log/application_json.log for entries with "message": "simple_update" or "message": "cache_hit".
  4. Verify rebuildable_cache nested key contains event, cache_key, ref, etc.
  5. Verify meta.project is populated.
  6. Disable verbose logging:
    Feature.disable(:ref_cache_verbose_logging)
  7. Repeat push — verify no info-level RebuildableSetCache logs appear.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Vasilii Iakliushin

Merge request reports

Loading