Investigation into Ruby Linter Rules for Fields

Objective

Investigate and implement a dynamic linting approach for enforcing field logging standards in the GitLab codebase, using runtime warnings and a custom TODO list instead of static RuboCop rules.

Background

As part of defining field logging standards for developers, we need a mechanism to identify and track unknown/non-standard logging fields across the codebase. Initial investigation ruled out RuboCop (static linting) due to the dynamic nature of logging field construction (see example).

Approach

Dynamic linting via runtime inspection:

  • Hook into json-logger's format_message method to inspect logging field keys at runtime
  • Compare emitted fields against an allow list (standard fields + TODO list)
  • Emit warnings for unknown fields during development and CI

Configuration-based management:

  • Maintain a YAML configuration file (field_standard_config.yml) with three categories:
    • allow_list: Approved standard fields (e.g., correlation_id, gl_user_id, gl_user_name)
    • ignore: System fields to ignore (e.g., time, severity, message)
    • todo: Fields currently in use but not yet standardized (temporary allowlist)

Implementation Details

Reference MR: gitlab-org/gitlab!214212

The implementation:

  • Prepends a Checker module to Labkit::Logging::JsonLogger
  • Intercepts format_message to parse JSON output and extract field keys
  • Compares fields against the combined allow list
  • Warns once per unique set of unknown fields (deduplication via Set)
  • Only runs in non-production environments

Example warning output:

Logger Gitlab::Database::LoadBalancing::Logger emitted unknown fields: ["event", "model", "start_service_discovery"]
Logger Gitlab::AuthLogger emitted unknown fields: ["gitlab_throttle_user_allowlist"]

Next Steps

  1. Compile comprehensive TODO list: Run CI pipelines and parse warning output to identify all existing non-standard fields
  2. Categorize fields: Review discovered fields and determine which should be:
    • Standardized and moved to allow_list
    • Deprecated and removed from code
    • Temporarily kept in todo list
  3. Create remediation plan: For each TODO field, create issues/MRs to either standardize or remove
  4. Monitor and iterate: Track progress on reducing TODO list over time

Related Resources

Edited by Mohga Gamea