gitlab-labkit 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0cf5e5935ee28f4b6bcc2165d6df81c38006f2b503044563850e744cfb85737
-  data.tar.gz: e5c6137d9430cedfc0984d279d09c9758cdc43e6c25734c91d5b558cf92452e5
+  metadata.gz: 888cc5479aac46e57a89719bf13d9403a83f4d92c4f6c2a280b4c71950fee250
+  data.tar.gz: 2d5cc94125a609627065b10faa15a85eec3998285686db906a3ce1f54ed1f89d
 SHA512:
-  metadata.gz: 4fab0460afaf9c9912e0225942395669336232f1de591a638e71715ea198cb9cee3f8c5dd462478fc62d1f3ca1741d7d4561983fb5a01cc6760efea2ed2d9374
-  data.tar.gz: ed6778b22816c5e4b301f12b71b28a97d126f4238b896941674a543631a89b7d0624d0c2b2210918f2621f1a9cf8d4c874f3cb0df0c9e67018dbe5d420ba5330
+  metadata.gz: bc655d31560edac3cc29db253c3ea9c20f5fddfc479ac6f76563d56dfd795f265b0119a4480fa9bd10f90c9652eba31f458625a48570b70119004e4bf8ff609f
+  data.tar.gz: 992a1a49adecaf7a52bb4caaec4484dc8feddcfc88fc83a8ddb4ada3b0aca0f6b50de32bf6a64062c9380482958175ff237a037d3c61023e4e541cb1efbd2230

data/.gitlab/CODEOWNERS

@@ -1 +1 @@
-* @andrewn @ayufan @reprazent @mkaeppler
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael

data/.gitlab-ci.yml

@@ -19,13 +19,13 @@ include:
   # It includes standard checks, gitlab-scanners, validations and release processes
   # common to all projects using this template library.
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/standard.md
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.4
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.5
 
   # Runs rspec tests and rubocop on the project
   # see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/ruby.md
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.4
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.5
 
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.4
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.5
 
 .test_template: &test_definition
   extends: .with_bundle

data/.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
   # Documentation available at
   # https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/pre-commit.md
   - repo: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks
-    rev: v3.4  # renovate:managed
+    rev: v3.5  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/CODEOWNERS

@@ -1,4 +1,4 @@
 # CODEOWNERS is used to lookup assignees for
 # Renovate Bot dependency change Merge Requests.
 # https://docs.renovatebot.com/configuration-options/#assigneesfromcodeowners
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael

data/doc/FIELD_STANDARDIZATION.md

@@ -0,0 +1,249 @@
+# LabKit Field Standardization
+
+## Overview
+
+The LabKit Field Validator detects when your code uses deprecated logging field names and helps you migrate to standardized fields. This supports the [Observability Field Standardisation initiative](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/).
+
+**Goal:** Standardize logging field names across GitLab so logs are queryable and actionable across all systems.
+
+**How it works:** The validator intercepts logging calls during development and testing, detects deprecated fields, and compares them against a frozen baseline. New offenses fail CI; known offenses are tracked in `.labkit_logging_todo.yml`. The validator is **not** active in production environments.
+
+For the architectural decision and rationale, see [ADR: Dynamic Runtime Linting](./architecture/decisions/001_field_standardization_dynamic_runtime_linting.md).
+
+## Key Concepts
+
+**Offense**
+- A unique combination of [File Path] + [Deprecated Field] + [Logger Class]
+- Multiple log calls in the same file using the same deprecated field = 1 offense
+- Offenses exist until the deprecated field is entirely removed from the file
+
+**TODO Baseline**
+- A list of known offenses tracked in `.labkit_logging_todo.yml`
+- Existing offenses in this baseline are allowed
+- Any new offenses detected during development raise an error
+- Prevents regression while allowing incremental cleanup
+
+## Quick Start
+
+### First-Time Setup
+
+1. **Initialize the todo file:**
+
+   ```bash
+   bundle exec labkit-logging init
+   ```
+
+   This creates `.labkit_logging_todo.yml` with `skip_ci_failure: true`, which allows CI to pass while collecting the initial baseline.
+
+2. **Commit and push:**
+
+   ```bash
+   git add .labkit_logging_todo.yml
+   git commit -m "Add LabKit logging todo baseline"
+   git push
+   ```
+
+3. **Wait for CI to complete**, then fetch the baseline:
+
+   ```bash
+   bundle exec labkit-logging fetch <project> <pipeline_id>
+   ```
+
+   For example:
+   ```bash
+   bundle exec labkit-logging fetch gitlab-org/gitlab 12345
+   ```
+
+   This fetches all detected offenses from the CI pipeline logs and populates the todo file. The `skip_ci_failure` flag is automatically removed.
+
+4. **Commit the populated baseline:**
+
+   ```bash
+   git add .labkit_logging_todo.yml
+   git commit -m "Populate LabKit logging todo baseline"
+   git push
+   ```
+
+Future CI runs will now enforce this baseline—new offenses will fail the pipeline.
+
+## Developer Workflow
+
+### Fixing Offenses (Recommended)
+
+Replace deprecated fields with standard constants:
+
+```ruby
+# Before
+logger.info(user_id: current_user.id)
+
+# After
+logger.info(Labkit::Fields::GL_USER_ID => current_user.id)
+```
+
+When you fix an offense, it's automatically removed from the baseline on the next test run. Run your tests locally to verify:
+
+```bash
+LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+```
+
+### Adding Offenses Temporarily
+
+If you can't fix an offense immediately, add it to the baseline:
+
+```bash
+LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+```
+
+This updates `.labkit_logging_todo.yml` with any new offenses found during the test run. Commit the updated file with your changes.
+
+**Note:** Justify in your MR why you can't fix immediately. Keep the baseline as small as possible.
+
+### Regenerating the Baseline
+
+To regenerate the entire baseline from scratch:
+
+```bash
+rm .labkit_logging_todo.yml
+bundle exec labkit-logging init
+# Run CI, then:
+bundle exec labkit-logging fetch <project> <pipeline_id>
+```
+
+## CI Behavior
+
+### Baseline Generation Mode
+
+When `skip_ci_failure: true` is set in the todo file:
+
+- CI passes even when deprecated fields are detected
+- Offenses are logged for collection via `labkit-logging fetch`
+- Use this mode only during initial setup
+
+### Enforcement Mode
+
+When `skip_ci_failure` is not set (normal operation):
+
+- **New offenses fail the pipeline** with a detailed error message
+- **Known offenses** (in the baseline) are allowed
+- **Fixed offenses** are automatically detected and can be removed from the baseline
+
+Example CI failure output:
+
+```
+================================================================================
+LabKit Logging Field Standardization: New Offenses Detected
+================================================================================
+
+app/services/user_service.rb:42: 'user_id' is deprecated. Use 'Labkit::Fields::GL_USER_ID' instead.
+app/models/project.rb:15: 'project_id' is deprecated. Use 'Labkit::Fields::GL_PROJECT_ID' instead.
+
+================================================================================
+Total: 2 new offense(s) in 2 file(s)
+================================================================================
+```
+
+### When Offenses Are Fixed
+
+When you fix offenses that were in the baseline, you'll see a message indicating which offenses were resolved. Update the baseline locally to remove them:
+
+```bash
+LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+git add .labkit_logging_todo.yml
+git commit -m "Remove fixed logging offenses from baseline"
+```
+
+## CLI Reference
+
+The `labkit-logging` command provides subcommands for managing the field validator.
+
+```bash
+bundle exec labkit-logging <command> [options]
+```
+
+### labkit-logging init
+
+Creates a new `.labkit_logging_todo.yml` file with `skip_ci_failure: true`.
+
+```bash
+bundle exec labkit-logging init
+```
+
+### labkit-logging fetch
+
+Fetches offense logs from a GitLab CI pipeline and updates the todo file.
+
+```bash
+bundle exec labkit-logging fetch <project> <pipeline_id>
+```
+
+**Arguments:**
+- `project` - GitLab project ID or path (e.g., `278964` or `gitlab-org/gitlab`)
+- `pipeline_id` - CI pipeline ID number
+
+**Environment Variables:**
+- `GITLAB_TOKEN` - GitLab API token (required)
+- `CI_API_V4_URL` - GitLab API URL (default: `https://gitlab.com/api/v4`)
+
+**Examples:**
+
+```bash
+# Using project path
+bundle exec labkit-logging fetch gitlab-org/gitlab 12345
+
+# Using project ID
+bundle exec labkit-logging fetch 278964 12345
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LABKIT_LOGGING_TODO_UPDATE=true` | Update the baseline with new offenses (local development) |
+| `GITLAB_TOKEN` | GitLab API token for fetching CI logs |
+| `CI_API_V4_URL` | GitLab API URL (defaults to gitlab.com) |
+
+## Troubleshooting
+
+**"New Offenses Detected" in CI**
+- Fix the deprecated fields in your code, or
+- Update the baseline locally: `LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec`
+- Commit the updated `.labkit_logging_todo.yml`
+
+**Offenses not detected**
+- Ensure `.labkit_logging_todo.yml` exists in your project root
+- Verify you're using `Labkit::Logging::JsonLogger`
+- Check you're logging with a Hash (not String)
+- Verify the code path is executed during tests
+
+**Pipeline not found when fetching**
+- Verify the project path/ID is correct
+- Ensure the pipeline has completed (not still running)
+- Check your `GITLAB_TOKEN` has read access to the project
+
+**No offenses found in pipeline**
+- Ensure `skip_ci_failure: true` was set during the CI run
+- Verify the pipeline ran tests that exercise the logging code
+- Check job logs are accessible with your token
+
+## TODO File Format
+
+```yaml
+# LabKit Logging Field Standardization TODO
+# AUTO-GENERATED FILE. DO NOT EDIT MANUALLY.
+
+offenses:
+  - logger_class: "Labkit::Logging::JsonLogger"
+    callsite: "app/services/user_service.rb"
+    deprecated_field: "user_id"
+    standard_field: "Labkit::Fields::GL_USER_ID"
+  - logger_class: "Labkit::Logging::JsonLogger"
+    callsite: "app/models/project.rb"
+    deprecated_field: "project_id"
+    standard_field: "Labkit::Fields::GL_PROJECT_ID"
+```
+
+## References
+
+- [ADR: Dynamic Runtime Linting](./architecture/decisions/001_field_standardization_dynamic_runtime_linting.md)
+- [Observability Field Standardisation](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/)
+- [Quality Epic](https://gitlab.com/groups/gitlab-org/quality/-/epics/235)

data/exe/labkit-logging

@@ -0,0 +1,198 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'yaml'
+require 'set'
+require 'labkit/fields'
+require 'labkit/logging/field_validator/config'
+
+module Labkit
+  module Logging
+    module FieldValidator
+      class CLI
+        THREAD_POOL_SIZE = 10
+        DETECTED_OFFENSE_PREFIX = 'LABKIT_LOGGING_OFFENSE'
+
+        def run(args)
+          case args.shift
+          when 'init' then init_todo_file
+          when 'fetch' then fetch(args)
+          else puts "Usage: labkit-logging <init|fetch> [options]\n\n  init   Initialize .labkit_logging_todo.yml\n  fetch  Fetch offenses: labkit-logging fetch <project> <pipeline_id>"
+          end
+        end
+
+        def init_todo_file
+          Config.init_file!
+          warn "Created #{Config.file_name} with skip_ci_failure enabled.\n\nNext steps:\n1. Commit this file\n2. Push and let CI run\n3. Run: labkit-logging fetch <project> <pipeline_id>"
+        end
+
+        private
+
+        def fetch(args)
+          @project = args[0]
+          @pipeline = args[1]
+          abort "Usage: labkit-logging fetch <project> <pipeline_id>" unless @project && @pipeline&.match?(/^\d+$/)
+          abort "GITLAB_TOKEN environment variable is required" unless token
+
+          warn "Fetching offenses from pipeline #{@pipeline}..."
+          validate_pipeline!
+          jobs = fetch_jobs
+
+          detected = process_jobs(jobs)
+          new_off, removed_off = compute_diff(detected)
+
+          if new_off.empty? && removed_off.empty?
+            warn "\nNo changes detected."
+            return
+          end
+
+          save_results(new_off, removed_off)
+        end
+
+        def validate_pipeline!
+          resp = api_get("/projects/#{enc(@project)}/pipelines/#{@pipeline}")
+          abort "Pipeline not found" unless resp.is_a?(Net::HTTPSuccess)
+          status = JSON.parse(resp.body)['status']
+          abort "Pipeline still running" if status == 'running'
+          abort "Pipeline status: #{status}" unless %w[success failed].include?(status)
+        end
+
+        def fetch_jobs
+          jobs = []
+          page = 1
+          loop do
+            resp = api_get("/projects/#{enc(@project)}/pipelines/#{@pipeline}/jobs?per_page=100&page=#{page}")
+            abort "Failed to fetch jobs" unless resp.is_a?(Net::HTTPSuccess)
+            batch = JSON.parse(resp.body)
+            break if batch.empty?
+
+            jobs.concat(batch)
+            page += 1
+          end
+          jobs
+        end
+
+        def process_jobs(jobs)
+          detected = []
+          mutex = Mutex.new
+          queue = Queue.new
+          jobs.each { |j| queue << j }
+          total = jobs.size
+          done = 0
+
+          threads = Array.new(THREAD_POOL_SIZE) do
+            Thread.new do
+              loop do
+                job = begin
+                  queue.pop(true)
+                rescue StandardError
+                  nil
+                end
+                break unless job
+
+                begin
+                  resp = api_get("/projects/#{enc(@project)}/jobs/#{job['id']}/trace")
+                  if resp.is_a?(Net::HTTPSuccess)
+                    offenses = parse_log(resp.body)
+                    mutex.synchronize { detected.concat(offenses) }
+                  end
+                rescue StandardError => e
+                  mutex.synchronize { warn "\nWarning: #{job['name']}: #{e.message}" }
+                ensure
+                  mutex.synchronize do
+                    done += 1
+                    $stderr.print "\rProcessing jobs: #{done}/#{total}"
+                  end
+                end
+              end
+            end
+          end
+          threads.each(&:join)
+          warn ""
+
+          dedupe(detected)
+        end
+
+        def parse_log(log)
+          offenses = []
+          log.each_line do |line|
+            clean = line.gsub(/\e\[[0-9;]*[a-zA-Z]/, '').strip
+            next unless clean.include?(DETECTED_OFFENSE_PREFIX)
+
+            idx = clean.index(DETECTED_OFFENSE_PREFIX)
+            next unless idx
+
+            json = clean[(idx + DETECTED_OFFENSE_PREFIX.length)..].sub(/^[:\s]+/, '')
+            offense = begin
+              JSON.parse(json)
+            rescue StandardError
+              nil
+            end
+            offenses << offense if offense
+          end
+          offenses
+        end
+
+        def compute_diff(detected)
+          baseline = Config.load.fetch('offenses', [])
+
+          baseline_keys = baseline.to_set { |o| [o['callsite'], o['deprecated_field'], o['logger_class']] }
+          detected_keys = detected.to_set { |o| [o['callsite'], o['deprecated_field'], o['logger_class']] }
+
+          new_offenses = detected.reject do |o|
+            key = [o['callsite'], o['deprecated_field'], o['logger_class']]
+            baseline_keys.include?(key)
+          end
+
+          removed_offenses = baseline.select do |o|
+            key = [o['callsite'], o['deprecated_field'], o['logger_class']]
+            !detected_keys.include?(key) # rubocop:disable Rails/NegateInclude -- Set has no exclude? method
+          end
+
+          [new_offenses, removed_offenses]
+        end
+
+        def dedupe(offenses)
+          offenses.uniq { |o| [o['callsite'], o['deprecated_field'], o['logger_class']] }
+        end
+
+        def save_results(new_off, removed_off)
+          skip_removed = Config.load.fetch('skip_ci_failure', false)
+          updated = Config.update!(new_off, removed_off)
+          warn "\n✓ Added #{new_off.size} new offenses" if new_off.any?
+          warn "✓ Removed #{removed_off.size} fixed offenses" if removed_off.any?
+          warn "✓ Removed skip_ci_failure flag" if skip_removed
+          warn "✓ Total: #{updated.size} offenses\n\nCommit the updated #{Config.file_name} file."
+        end
+
+        def api_get(path)
+          uri = URI.parse("#{api_url}#{path}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.open_timeout = 10
+          http.read_timeout = 30
+          req = Net::HTTP::Get.new(uri.request_uri)
+          req['PRIVATE-TOKEN'] = token
+          http.request(req)
+        end
+
+        def token
+          ENV['GITLAB_API_PRIVATE_TOKEN'] || ENV['GITLAB_TOKEN'] || ENV.fetch('CI_JOB_TOKEN', nil)
+        end
+
+        def api_url
+          ENV['GITLAB_API_ENDPOINT'] || ENV['CI_API_V4_URL'] || 'https://gitlab.com/api/v4'
+        end
+
+        def enc(str)
+          URI.encode_www_form_component(str.to_s)
+        end
+      end
+    end
+  end
+end
+
+Labkit::Logging::FieldValidator::CLI.new.run(ARGV)

data/gitlab-labkit.gemspec

@@ -16,6 +16,8 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
 
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|tools)/}) }
+  spec.bindir = "exe"
+  spec.executables = %w[labkit-logging]
   spec.require_paths = ["lib"]
   spec.required_ruby_version = "~> 3.2"
 

data/lib/labkit/logging/field_validator/config.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Logging
+    module FieldValidator
+      module Config
+        FILE_NAME = '.labkit_logging_todo.yml'
+
+        class << self
+          def root
+            @root ||= detect_root.freeze
+          end
+
+          def path
+            @path ||= File.join(root, file_name).freeze
+          end
+
+          def file_name
+            FILE_NAME
+          end
+
+          def deprecated_fields
+            @deprecated_fields ||= Labkit::Fields::Deprecated.all.freeze
+          end
+
+          def load
+            return {} unless config_file_exists?
+
+            YAML.safe_load_file(path) || {}
+          end
+
+          def update!(new_offenses, removed_offenses = [])
+            baseline_offenses = load.fetch('offenses', [])
+
+            if removed_offenses.any?
+              removed_keys = removed_offenses.to_set { |o| offense_key(o) }
+              baseline_offenses = baseline_offenses.reject { |o| removed_keys.include?(offense_key(o)) }
+            end
+
+            updated = process_offenses(baseline_offenses + new_offenses)
+            write_file({ 'offenses' => updated }, header: header)
+            updated
+          end
+
+          def init_file!
+            return if config_file_exists?
+
+            content = <<~YAML
+              # LabKit Logging Field Standardization TODO
+              # This file tracks deprecated logging fields that need migration.
+              #
+              # To collect offenses from CI:
+              #   bundle exec labkit-logging fetch <project> <pipeline_id>
+              #
+              # To collect offenses locally:
+              #   LABKIT_LOGGING_TODO_UPDATE=true <local development process>
+              #
+              # More info: https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md
+
+              skip_ci_failure: true  # Remove this flag once baseline is established
+
+              offenses: []
+            YAML
+
+            write_file(nil, header: content)
+          end
+
+          def config_file_exists?
+            File.exist?(path)
+          end
+
+          def skip_ci_failure?
+            load.fetch('skip_ci_failure', false) == true
+          end
+
+          def detect_root
+            return Bundler.root.to_s if defined?(Bundler) && Bundler.respond_to?(:root)
+            return Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root)
+
+            Dir.pwd
+          end
+
+          def header
+            <<~HEADER
+              # LabKit Logging Field Standardization TODO
+              # AUTO-GENERATED FILE. DO NOT EDIT MANUALLY.
+              #
+              # This file tracks deprecated logging fields that need to be migrated to standard fields.
+              # Each offense represents a file using a deprecated field that should be replaced.
+              #
+              # === HOW TO FIX ===
+              #
+              # 1. Replace the deprecated field with the standard field constant
+              # 2. Remove the deprecated field entirely (adding the new field is not enough)
+              # 3. Run your tests - the offense will be automatically removed
+              #
+              # Example:
+              #   # Before
+              #   logger.info(user_id: 123)
+              #
+              #   # After
+              #   logger.info(Labkit::Fields::GL_USER_ID => 123)
+              #
+              # === ADDING OFFENSES (if fixing is not immediately possible) ===
+              #
+              # Run: LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec <spec_file>
+              #
+              # === REGENERATE ENTIRE TODO ===
+              #
+              # Delete this file and run: LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+
+            HEADER
+          end
+
+          private
+
+          def write_file(data, header: self.header)
+            content = data ? header + YAML.dump(data, line_width: -1) : header
+            File.write(path, content)
+          end
+
+          def offense_key(offense)
+            [offense['callsite'], offense['deprecated_field'], offense['logger_class']]
+          end
+
+          def process_offenses(offenses)
+            offenses
+              .uniq { |o| offense_key(o) }
+              .sort_by { |o| offense_key(o) }
+              .map { |o| format_offense(o) }
+          end
+
+          def format_offense(offense)
+            {
+              'logger_class' => offense['logger_class'],
+              'callsite' => offense['callsite'],
+              'deprecated_field' => offense['deprecated_field'],
+              'standard_field' => standard_field_constant(offense['standard_field'])
+            }
+          end
+
+          def standard_field_constant(standard_field)
+            const_name = Labkit::Fields.constant_name_for(standard_field)
+            const_name ? "Labkit::Fields::#{const_name}" : standard_field
+          end
+        end
+      end
+    end
+  end
+end

data/lib/labkit/logging/field_validator/log_interceptor.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Labkit
+  module Logging
+    module FieldValidator
+      module LogInterceptor
+        IGNORE_PATHS = [
+          %r{/gems/logger-},
+          %r{/lib/labkit/logging/},
+          %r{/gems/rspec-},
+          %r{/ruby/\d+\.\d+\.\d+/}
+        ].freeze
+
+        LOGGER_WRAPPER_PATTERNS = [
+          %r{/.*logger\.rb$}
+        ].freeze
+
+        class << self
+          def register_wrapper_pattern(pattern)
+            wrapper_patterns << pattern
+          end
+
+          def wrapper_patterns
+            @wrapper_patterns ||= LOGGER_WRAPPER_PATTERNS.dup
+          end
+
+          def reset_wrapper_patterns!
+            @wrapper_patterns = nil
+          end
+        end
+
+        def format_data(severity, timestamp, progname, message)
+          data = super
+          location = determine_callsite
+
+          return data unless location
+
+          callsite_path = normalize_path(location.path)
+          return data unless callsite_path
+
+          all_fields = extract_string_keys(data)
+          logger_class = self.class.name || 'AnonymousLogger'
+
+          all_fields.each do |field|
+            standard_field = Labkit::Fields::Deprecated.standard_field_for(field)
+            next unless standard_field
+
+            Registry.instance.record_offense(callsite_path, location.lineno, field, standard_field, logger_class)
+          end
+
+          Registry.instance.check_for_removed_offenses(callsite_path, all_fields, logger_class)
+
+          data
+        end
+
+        private
+
+        def determine_callsite
+          locations = caller_locations(1, 30) || []
+
+          locations.find do |loc|
+            path = loc.path
+
+            next if path == __FILE__
+            next if IGNORE_PATHS.any? { |pattern| pattern.match?(path) }
+            next if LogInterceptor.wrapper_patterns.any? { |pattern| pattern.match?(path) }
+
+            true
+          end
+        end
+
+        def normalize_path(absolute_path)
+          root = Config.root
+          return nil unless absolute_path.start_with?(root)
+
+          start_idx = root.length
+          start_idx += 1 if absolute_path[start_idx] == '/'
+          absolute_path[start_idx..]
+        end
+
+        def extract_string_keys(data)
+          return Set.new unless data.is_a?(Hash)
+
+          data.keys.to_set(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/labkit/logging/field_validator/registry.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'set'
+
+module Labkit
+  module Logging
+    module FieldValidator
+      class Registry
+        include Singleton
+
+        attr_reader :offenses
+
+        def initialize
+          @mutex = Mutex.new
+          @offenses = Set.new
+          @offense_keys = Set.new # For O(1) lookup
+          @removed_offenses = Set.new
+          @baseline_by_callsite = nil
+          @resolved_fields = {} # Cache for resolved standard fields
+        end
+
+        def record_offense(callsite, lineno, deprecated_field, standard_field, logger_class)
+          key = [callsite, deprecated_field, logger_class].freeze
+
+          return if @offense_keys.include?(key)
+
+          @mutex.synchronize do
+            next if @offense_keys.include?(key)
+
+            @offense_keys << key
+            @offenses << {
+              'callsite' => callsite,
+              'lineno' => lineno,
+              'deprecated_field' => deprecated_field,
+              'standard_field' => standard_field,
+              'logger_class' => logger_class
+            }.freeze
+
+            @removed_offenses.reject! { |r| offense_key(r) == key }
+          end
+        end
+
+        def check_for_removed_offenses(callsite, fields, logger_class)
+          baseline = baseline_by_callsite[[callsite, logger_class]]
+          return unless baseline
+
+          @mutex.synchronize do
+            baseline.each do |offense|
+              key = offense_key(offense)
+              next if @offense_keys.include?(key)
+
+              deprecated = offense['deprecated_field']
+              standard = resolve_standard_field(offense['standard_field'])
+
+              next unless fields.include?(standard) && fields.exclude?(deprecated)
+
+              @removed_offenses << offense
+            end
+          end
+        end
+
+        # Returns [detected_offenses, new_offenses, removed_offenses]
+        def finalize
+          @mutex.synchronize do
+            baseline_keys = load_baseline.to_set { |b| offense_key(b) }
+
+            new_offenses = @offenses.reject { |o| baseline_keys.include?(offense_key(o)) }
+
+            [@offenses.to_a, new_offenses, @removed_offenses.to_a]
+          end
+        end
+
+        def clear!
+          @mutex.synchronize do
+            @offenses.clear
+            @offense_keys.clear
+            @removed_offenses.clear
+            @baseline_by_callsite = nil
+            @resolved_fields.clear
+          end
+        end
+
+        private
+
+        def offense_key(offense)
+          [offense['callsite'], offense['deprecated_field'], offense['logger_class']].freeze
+        end
+
+        def baseline_by_callsite
+          @baseline_by_callsite ||= load_baseline.group_by { |o| [o['callsite'], o['logger_class']] }
+        end
+
+        def resolve_standard_field(standard_field)
+          # Convert "Labkit::Fields::GL_USER_ID" to actual value "gl.user_id"
+          @resolved_fields[standard_field] ||= resolve_labkit_field_constant(standard_field)
+        end
+
+        def resolve_labkit_field_constant(standard_field)
+          return standard_field unless standard_field.start_with?('Labkit::Fields::')
+
+          const_name = standard_field.delete_prefix('Labkit::Fields::')
+          return standard_field unless Labkit::Fields.const_defined?(const_name)
+
+          Labkit::Fields.const_get(const_name)
+        end
+
+        def load_baseline
+          config = Config.load
+          config.fetch('offenses', [])
+        end
+      end
+    end
+  end
+end

data/lib/labkit/logging/field_validator.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'json'
+require 'yaml'
+
+require_relative 'field_validator/config'
+require_relative 'field_validator/log_interceptor'
+require_relative 'field_validator/registry'
+
+module Labkit
+  module Logging
+    ##
+    # Runtime validator for logging fields.
+    # Validates logged fields against standard and deprecated field lists.
+    # This validator is automatically injected in non-production environments.
+    # Offenses are collected during test runs and development.
+    module FieldValidator
+      class << self
+        # Inject the validator into JsonLogger
+        def inject!
+          return if @injected
+
+          # If the config file does not exist, we don't inject the validator.
+          # To enable field validation in a repository, a config file must exist.
+          return unless Config.config_file_exists?
+
+          ::Labkit::Logging::JsonLogger.prepend(LogInterceptor)
+          Kernel.at_exit { FieldValidator.process_violations }
+          @injected = true
+        end
+
+        def initialize_todo_file
+          Config.init_file!
+          warn "Created .labkit_logging_todo.yml with skip_ci_failure enabled."
+          warn ""
+          warn "Next steps:"
+          warn "1. Commit this file to source control"
+          warn "2. Push and let CI run to generate offense logs"
+          warn "3. Run: bundle exec labkit-logging fetch <project> <pipeline_id>"
+          warn "4. Commit the populated todo file (skip_ci_failure will be removed automatically)"
+        end
+
+        def process_violations
+          detected_offenses, new_offenses, removed_offenses = Registry.instance.finalize
+
+          return if detected_offenses.empty? && new_offenses.empty? && removed_offenses.empty?
+
+          in_ci = ENV['CI'] == 'true'
+
+          output_ndjson(detected_offenses) if in_ci
+
+          # Auto-remove fixed offenses (not in CI to avoid race conditions)
+          handle_removed_offenses(removed_offenses) if removed_offenses.any? && !in_ci
+
+          if ENV['LABKIT_LOGGING_TODO_UPDATE'] == 'true'
+            handle_update(new_offenses)
+          elsif new_offenses.any?
+            handle_new_offenses(new_offenses)
+          end
+        end
+
+        def clear_offenses!
+          Registry.instance.clear!
+        end
+
+        private
+
+        def handle_removed_offenses(removed_offenses)
+          Config.update!([], removed_offenses)
+
+          warn thank_you_message(removed_offenses)
+        end
+
+        def thank_you_message(removed_offenses)
+          lines = [
+            "",
+            "=" * 80,
+            "Thank you for improving our logging standards!",
+            "=" * 80,
+            "",
+            "You fixed #{removed_offenses.size} deprecated field offense(s):",
+            ""
+          ]
+
+          removed_offenses.each do |o|
+            lines << "  - #{o['callsite']}: '#{o['deprecated_field']}' -> '#{format_standard_field(o['standard_field'])}'"
+          end
+
+          lines << ""
+          lines << "#{Config.file_name} has been automatically updated."
+          lines << "Please commit the changes to complete the cleanup."
+          lines << ""
+          lines << ("=" * 80)
+          lines << ""
+
+          lines.join("\n")
+        end
+
+        def handle_new_offenses(new_offenses)
+          if ENV['CI'] == 'true' && Config.skip_ci_failure?
+            warn baseline_generation_message(new_offenses)
+          else
+            warn report_new_offenses(new_offenses)
+            raise "New LabKit logging offenses detected"
+          end
+        end
+
+        def baseline_generation_message(offenses)
+          lines = [
+            "",
+            "ℹ️  LabKit Logging: Baseline generation mode active",
+            "",
+            "Deprecated fields detected but skip_ci_failure is enabled.",
+            "Offenses are being logged for collection.",
+            "",
+            "To establish baseline:",
+            "  bundle exec labkit-logging fetch <project> <pipeline_id>",
+            "",
+            "Documentation: https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md",
+            "",
+            "--- Offenses Summary ---",
+            "Total offenses: #{offenses.size} across #{offenses.map { |o| o['callsite'] }.uniq.size} file(s)",
+            ""
+          ]
+          lines.join("\n")
+        end
+
+        def output_ndjson(detected_offenses)
+          detected_offenses.each do |offense|
+            puts "LABKIT_LOGGING_OFFENSE: #{JSON.generate(offense)}"
+          end
+        end
+
+        def handle_update(new_offenses)
+          updated_offenses = Config.update!(new_offenses)
+
+          warn "\n✓ Updated .labkit_logging_todo.yml"
+          warn "\n  Added #{new_offenses.size} new offenses ✓" if new_offenses.any?
+
+          warn "Total: #{updated_offenses.size} offenses"
+          warn "\nCommit the updated #{Config.file_name}."
+        end
+
+        def report_new_offenses(new_offenses)
+          lines = [
+            "",
+            "=" * 80,
+            "LabKit Logging Field Standardization: New Offenses Detected",
+            "=" * 80,
+            ""
+          ]
+
+          new_offenses.each do |o|
+            lines << "#{o['callsite']}:#{o['lineno']}: '#{o['deprecated_field']}' is deprecated. Use '#{format_standard_field(o['standard_field'])}' instead."
+          end
+
+          lines << ""
+          lines << ("=" * 80)
+          lines << "Total: #{new_offenses.size} new offense(s) in #{new_offenses.map { |o| o['callsite'] }.uniq.size} file(s)"
+          lines << ""
+          lines << "See https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md"
+          lines << ("=" * 80)
+          lines << ""
+
+          lines.join("\n")
+        end
+
+        def format_standard_field(standard_field)
+          const_name = Labkit::Fields.constant_name_for(standard_field)
+          const_name ? "Labkit::Fields::#{const_name}" : standard_field
+        end
+      end
+    end
+  end
+end
+
+Labkit::Logging::FieldValidator.inject!

data/lib/labkit/logging.rb

@@ -7,5 +7,9 @@ module Labkit
     autoload :GRPC, "labkit/logging/grpc"
     autoload :Sanitizer, "labkit/logging/sanitizer"
     autoload :JsonLogger, "labkit/logging/json_logger"
+
+    # Eagerly load FieldValidator in non-production environments
+    # This ensures injection happens before JsonLogger instances are created
+    require "labkit/logging/field_validator" unless ENV['RAILS_ENV'] == 'production'
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Andrew Newdigate
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -451,7 +451,8 @@ dependencies:
         version: 1.7.0
 email:
 - andrew@gitlab.com
-executables: []
+executables:
+- labkit-logging
 extensions: []
 extra_rdoc_files: []
 files:
@@ -481,7 +482,9 @@ files:
 - Rakefile
 - config/user_experience_slis/schema.json
 - config/user_experience_slis/testing_sample.yml
+- doc/FIELD_STANDARDIZATION.md
 - doc/architecture/decisions/001_field_standardization_dynamic_runtime_linting.md
+- exe/labkit-logging
 - gitlab-labkit.gemspec
 - lib/gitlab-labkit.rb
 - lib/labkit/context.rb
@@ -498,6 +501,10 @@ files:
 - lib/labkit/json_schema/README.md
 - lib/labkit/json_schema/ref_resolver.rb
 - lib/labkit/logging.rb
+- lib/labkit/logging/field_validator.rb
+- lib/labkit/logging/field_validator/config.rb
+- lib/labkit/logging/field_validator/log_interceptor.rb
+- lib/labkit/logging/field_validator/registry.rb
 - lib/labkit/logging/grpc.rb
 - lib/labkit/logging/grpc/server_interceptor.rb
 - lib/labkit/logging/json_logger.rb