gitlab-labkit 1.5.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf6262472d851bcdfeb96b0ed3b7acf25f462b0b968d2ac2f431ea946b68b33a
-  data.tar.gz: b04bfc82c7ea63848849af40c7940788796b486a16c41416de824b7440f01992
+  metadata.gz: e99cf18b21d9da22b488d0dd0031fc9030aeded745239b4e72e8d3f7c1c36555
+  data.tar.gz: 664ba45d3535d3310431eece7890c58ddfa9cd8a9dfa3c235b66fd20b2b5480e
 SHA512:
-  metadata.gz: 7c5a7b9002239cf23e7609fd8c07174bf588c0f2f1f2177616d6f98f4490c8e32f74cb7c8e62c1bf8ae839da24e30023e9bd733f1a6e40bbf75484d614a3d9ad
-  data.tar.gz: e699b4a653c268c7333bdad41006a5c52d0fbdaf0aa4c21ca90bbb396695d6519695243e0548e0f5439f9bd11366c6a3359c013766deadaa6996e31bbbfb7c7a
+  metadata.gz: f7959c2eb8f54ee928a7841c2b8de8011c1e2a481c3c6aaf8e94b53a7ca186e8c28ad192a641c4c8ffac5bd8fd39a2c7c6afad324dfae77531b00e3089de3dc0
+  data.tar.gz: 05d07f6b1dffe39907c372ca0cb1c638cbc3898f39faf33f82ef5e042c9ea916a94d297963706e0010bc30dc14df2ebf2a1d89a342866630753af233f52934d1

data/.copier-answers.yml

@@ -3,7 +3,7 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.39.0
+_commit: v1.45.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false
@@ -11,6 +11,8 @@ helm: false
 initial_codeowners: '@reprazent @andrewn @mkaeppler @ayufan'
 jsonnet: false
 project_name: labkit-ruby
+release_platform: false
 ruby: true
 rubygem: true
 terraform: false
+truncated_tags: true

data/.gitlab/merge_request_templates/default.md

@@ -0,0 +1,9 @@
+## Description
+
+<!-- Briefly describe what this MR does and why -->
+
+## Related Issues
+
+<!-- Link to related issues using #issue_number -->
+
+/assign me

data/.gitlab-ci-asdf-versions.yml

@@ -1,5 +1,5 @@
 # DO NOT MANUALLY EDIT; Run ./scripts/update-asdf-version-variables.sh to update this
 variables:
-    GL_ASDF_RUBY_VERSION: "3.4.8"
+    GL_ASDF_RUBY_VERSION: "4.0.1"
     GL_ASDF_SHELLCHECK_VERSION: "0.11"
-    GL_ASDF_SHFMT_VERSION: "3.12"
+    GL_ASDF_SHFMT_VERSION: "3.13"

data/.gitlab-ci.yml

@@ -19,29 +19,28 @@ 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.5
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.12
 
   # 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.5
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.12
 
-  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.5
-
-.test_template: &test_definition
-  extends: .with_bundle
-  image: ruby:${RUBY_VERSION}
-  stage: validate
-  script:
-    - gem install bundler --no-document
-    - bundle config --local path vendor
-    - bundle install
-    - bundle exec rake verify build install
+  - component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.12
 
 ruby-versions:
-  <<: *test_definition
+  extends: rspec
+  image: ${CI_REGISTRY}/gitlab-com/gl-infra/common-ci-tasks-images/ruby:${RUBY_VERSION}
+  parallel:
+    matrix:
+      - RUBY_VERSION: ["3.4"]
+
+# These versions aren't built in common CI tasks, so use a public ruby image
+legacy-ruby-versions:
+  extends: rspec
+  image: ruby:${RUBY_VERSION}
   parallel:
     matrix:
-      - RUBY_VERSION: ["3.2", "3.3"]
+      - RUBY_VERSION: ["3.3"]
 
 deploy:
   rules:

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.5  # renovate:managed
+    rev: v3.12  # renovate:managed
 
     hooks:
       - id: shellcheck  # Run shellcheck for changed Shell files

data/.releaserc.json

@@ -1,5 +1,11 @@
 {
-  "branches": ["master"],
+  "branches": [
+    {
+      "name": "+([0-9])-+([0-9])-stable",
+      "range": "${name.replace(/^(\\d+)-(\\d+)-stable$/, '$1.$2.x')}"
+    },
+    "master"
+  ],
   "plugins": [
     [
       "@semantic-release/commit-analyzer",

data/.tool-versions

@@ -1,3 +1,3 @@
-ruby 3.4.8
-shfmt 3.12
+ruby 4.0.1
+shfmt 3.13
 shellcheck 0.11

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 @d.barrett @splattael
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez

data/doc/FIELD_STANDARDIZATION.md

@@ -2,134 +2,172 @@
 
 ## 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/).
+The LabKit Field Validator detects deprecated logging field names and helps
+migrate them to standardized fields.
+It 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.
+The validator intercepts logging calls in non-production environments, detects
+deprecated fields, and compares them against a frozen baseline stored in
+`.labkit_logging_todo.yml`.
+New offenses raise an error. Known offenses are allowed.
 
-**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).
 
-For the architectural decision and rationale, see [ADR: Dynamic Runtime Linting](./architecture/decisions/001_field_standardization_dynamic_runtime_linting.md).
+## Key concepts
 
-## Key Concepts
+Offense
+: A unique combination of file path, deprecated field, and logger class.
+  Multiple log calls in the same file using the same deprecated field count as
+  one offense.
+  An offense exists until the deprecated field is entirely removed from the
+  file.
 
-**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
+: The list of known offenses in `.labkit_logging_todo.yml`.
+  The baseline prevents regression while allowing incremental cleanup.
 
-**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
 
-## Quick Start
+1. Initialize the todo file:
 
-### First-Time Setup
-
-1. **Initialize the todo file:**
-
-   ```bash
+   ```shell
    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.
+   This creates `.labkit_logging_todo.yml` with `skip_ci_failure: true`, which
+   allows CI to pass while outputting found offenses.
+   These are later collected to create the baseline.
 
-2. **Commit and push:**
+1. Commit and push:
 
-   ```bash
+   ```shell
    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:
+1. Wait for CI to complete, then fetch the baseline:
 
-   ```bash
+   ```shell
    bundle exec labkit-logging fetch <project> <pipeline_id>
    ```
 
    For example:
-   ```bash
+
+   ```shell
    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.
+   This fetches detected offenses from CI pipeline logs and populates the todo
+   file.
+   The `skip_ci_failure` flag is automatically removed.
 
-4. **Commit the populated baseline:**
+1. Commit the populated baseline:
 
-   ```bash
+   ```shell
    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.
+Future CI runs enforce this baseline.
+New offenses fail the pipeline.
 
-## Developer Workflow
+## How to deprecate a field
 
-### Fixing Offenses (Recommended)
+1. In `lib/labkit/fields.rb`, confirm the standard field constant exists in
+   `Labkit::Fields`. Add it if it does not exist:
 
-Replace deprecated fields with standard constants:
+   ```ruby
+   GL_PROJECT_ID = "gl_project_id"
+   ```
 
-```ruby
-# Before
-logger.info(user_id: current_user.id)
+1. In the same file, add the deprecated names to
+   `Labkit::Fields::Deprecated::MAPPINGS`:
 
-# After
-logger.info(Labkit::Fields::GL_USER_ID => current_user.id)
-```
+   ```ruby
+   Fields::GL_PROJECT_ID => %w[project_id projectid],
+   ```
 
-When you fix an offense, it's automatically removed from the baseline on the next test run. Run your tests locally to verify:
+1. Create a Kibana field alias in the relevant index patterns to map the
+   deprecated field to the standard field.
+   This ensures log queries continue to work during the migration period.
 
-```bash
-LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
-```
+1. Release a new version of `labkit-ruby`.
 
-### Adding Offenses Temporarily
+1. In each consumer repository (for example, `gitlab-org/gitlab`), the MR to
+   update `labkit-ruby` fails with new offenses.
+   To add these offenses to the baseline, run `fetch` against the failed
+   pipeline and push the updated baseline to the branch:
 
-If you can't fix an offense immediately, add it to the baseline:
+   ```shell
+   bundle exec labkit-logging fetch <project> <pipeline_id>
+   git add .labkit_logging_todo.yml
+   git commit -m "Add new deprecated field offenses to baseline"
+   git push
+   ```
 
-```bash
-LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
-```
+## How to fix an offense
 
-This updates `.labkit_logging_todo.yml` with any new offenses found during the test run. Commit the updated file with your changes.
+The field validator runs during any non-production process that exercises
+logging code paths, including tests, local development, and CI pipelines.
+When a log call uses the standard field instead of the deprecated field, the
+validator detects the fix automatically and removes the offense from the
+baseline.
 
-**Note:** Justify in your MR why you can't fix immediately. Keep the baseline as small as possible.
+1. Replace the deprecated field with the standard field constant.
 
-### Regenerating the Baseline
+1. Remove the deprecated field entirely from each log call in the file.
+   Adding the new field is not enough. The old key must be deleted.
 
-To regenerate the entire baseline from scratch:
+1. Run any process that exercises the logging code path:
 
-```bash
-rm .labkit_logging_todo.yml
-bundle exec labkit-logging init
-# Run CI, then:
-bundle exec labkit-logging fetch <project> <pipeline_id>
+   ```shell
+   bundle exec rspec
+   ```
+
+   The offense is automatically removed from `.labkit_logging_todo.yml`.
+
+1. Commit the updated baseline to complete the cleanup.
+
+### Example
+
+```ruby
+# Before
+logger.info(user_id: current_user.id)
+
+# After
+logger.info(Labkit::Fields::GL_USER_ID => current_user.id)
 ```
 
-## CI Behavior
+### Add an offense to the baseline temporarily
 
-### Baseline Generation Mode
+If you cannot fix an offense immediately, add it to the baseline:
 
-When `skip_ci_failure: true` is set in the todo file:
+```shell
+LABKIT_LOGGING_TODO_UPDATE=true bundle exec rspec
+```
 
-- CI passes even when deprecated fields are detected
-- Offenses are logged for collection via `labkit-logging fetch`
-- Use this mode only during initial setup
+Commit the updated `.labkit_logging_todo.yml` with your changes.
+Justify in your MR why you cannot fix the offense immediately.
 
-### Enforcement Mode
+## CI behavior
+
+When `skip_ci_failure: true` is set in the todo file, CI passes even when
+deprecated fields are detected.
+Offenses are logged for collection with `labkit-logging fetch`.
+Use this mode only during initial setup or recreating the todo file.
 
 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
+- New offenses fail the pipeline.
+- Known offenses in the baseline are allowed.
+- Fixed offenses are detected automatically.
 
 Example CI failure output:
 
-```
+```plaintext
 ================================================================================
 LabKit Logging Field Standardization: New Offenses Detected
 ================================================================================
@@ -139,93 +177,75 @@ app/models/project.rb:15: 'project_id' is deprecated. Use 'Labkit::Fields::GL_PR
 
 ================================================================================
 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"
+See https://gitlab.com/gitlab-org/ruby/gems/labkit-ruby/-/blob/master/doc/FIELD_STANDARDIZATION.md#new-offenses-detected
+================================================================================
 ```
 
-## CLI Reference
-
-The `labkit-logging` command provides subcommands for managing the field validator.
+## CLI reference
 
-```bash
+```shell
 bundle exec labkit-logging <command> [options]
 ```
 
-### labkit-logging init
+### `labkit-logging init`
 
-Creates a new `.labkit_logging_todo.yml` file with `skip_ci_failure: true`.
+Creates `.labkit_logging_todo.yml` with `skip_ci_failure: true`.
 
-```bash
-bundle exec labkit-logging init
-```
-
-### labkit-logging fetch
+### `labkit-logging fetch`
 
 Fetches offense logs from a GitLab CI pipeline and updates the todo file.
 
-```bash
+```shell
 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
+- `project` - GitLab project ID or path (for example, `278964` or
+  `gitlab-org/gitlab`).
+- `pipeline_id` - CI pipeline ID number.
+
+### Environment variables
 
-**Environment Variables:**
-- `GITLAB_TOKEN` - GitLab API token (required)
-- `CI_API_V4_URL` - GitLab API URL (default: `https://gitlab.com/api/v4`)
+| Variable                          | Description                                               |
+|-----------------------------------|-----------------------------------------------------------|
+| `LABKIT_LOGGING_TODO_UPDATE=true` | Update the baseline with new offenses (local development) |
+| `GITLAB_TOKEN`                    | GitLab API token for `labkit-logging fetch` (required)    |
+| `CI_API_V4_URL`                   | GitLab API URL (default: `https://gitlab.com/api/v4`)     |
 
-**Examples:**
+## Troubleshooting
 
-```bash
-# Using project path
-bundle exec labkit-logging fetch gitlab-org/gitlab 12345
+### New offenses detected
 
-# Using project ID
-bundle exec labkit-logging fetch 278964 12345
-```
+The validator raises an error when code introduces a deprecated logging field
+that is not in the baseline.
+This can happen when you:
 
-## Environment Variables
+- Add a new log call that uses a deprecated field name.
+- Update `labkit-ruby` to a version that deprecates a field your code uses.
 
-| 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) |
+To resolve, either [fix the offense](#how-to-fix-an-offense) or
+[add it to the baseline temporarily](#add-an-offense-to-the-baseline-temporarily).
 
-## Troubleshooting
+### Offenses not detected
+
+- Ensure `.labkit_logging_todo.yml` exists in your project root.
+- Verify you are using `Labkit::Logging::JsonLogger`.
+- Check you are logging with a Hash (not String).
+- Verify the code path is executed during tests.
 
-**"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`
+### Pipeline not found when fetching
 
-**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
+- Verify the project path or ID is correct.
+- Ensure the pipeline has completed (not still running).
+- Check your `GITLAB_TOKEN` has read access to the project.
 
-**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
 
-**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
+- 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
+## TODO file format
 
 ```yaml
 # LabKit Logging Field Standardization TODO

data/gitlab-labkit.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = %w[labkit-logging]
   spec.require_paths = ["lib"]
-  spec.required_ruby_version = "~> 3.2"
+  spec.required_ruby_version = ">= 3.3", "< 5"
 
   # Please maintain alphabetical order for dependencies
   spec.add_runtime_dependency "actionpack", ">= 5.0.0", "< 8.1.0"
@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
 
   # Please maintain alphabetical order for dev dependencies
   spec.add_development_dependency "excon", "~> 0.78.1"
-  spec.add_development_dependency "faraday", "~> 1.10.3"
+  spec.add_development_dependency "faraday", "~> 2.13"
   spec.add_development_dependency "gitlab-dangerfiles", "~> 2.11.0"
   spec.add_development_dependency "gitlab-styles", "~> 13.1"
   spec.add_development_dependency "grpc-tools", ">= 1.75"

data/lib/labkit/context.rb

@@ -66,6 +66,10 @@ module Labkit
         contexts.last
       end
 
+      def clear
+        Thread.current[:labkit_contexts] = nil
+      end
+
       def log_key(key)
         key = key.to_s
         return key if RAW_KEYS.include?(key)