gitlab-labkit 1.1.0 → 1.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.copier-answers.yml +1 -1
- data/.gitlab-ci-asdf-versions.yml +1 -1
- data/.gitlab-ci.yml +3 -3
- data/.pre-commit-config.yaml +1 -1
- data/.tool-versions +1 -1
- data/doc/architecture/decisions/001_field_standardization_dynamic_runtime_linting.md +124 -0
- data/gitlab-labkit.gemspec +2 -2
- data/lib/labkit/logging/json_logger.rb +8 -12
- data/lib/labkit/user_experience_sli/experience.rb +3 -3
- data/scripts/prepare-dev-env.sh +4 -1
- metadata +22 -10
- data/scripts/install-asdf-plugins.sh +0 -13
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1bbb89ac1275f06d828f9d9fa4a24e20e33f4a01d201956d4dd8d30e87dd8f5a
|
|
4
|
+
data.tar.gz: 1d6b24a17f8b2096e34303fba306ea1271146b3245cb5edcb3fabbccd26f1e45
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4950f9c1615b432b5d53ab54a51cca84a10cbf548b434665fdda93a2204f912f172540652df7b634907c61fa88f03f50a1ad9de96e04d2795a59393fe3fdcf93
|
|
7
|
+
data.tar.gz: a67c2262dd119373431f271779baf8311c5eb47a794a2970e1b4b9dcd28c59a4253ff844654f20a99026f95aabe6538f8fbdc864da29f007cd6c94a99eb427ad
|
data/.copier-answers.yml
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
# See the project for instructions on how to update the project
|
|
4
4
|
#
|
|
5
5
|
# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
|
|
6
|
-
_commit: v1.
|
|
6
|
+
_commit: v1.38.0
|
|
7
7
|
_src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
|
|
8
8
|
ee_licensed: false
|
|
9
9
|
golang: false
|
data/.gitlab-ci.yml
CHANGED
|
@@ -19,13 +19,13 @@ include:
|
|
|
19
19
|
# It includes standard checks, gitlab-scanners, validations and release processes
|
|
20
20
|
# common to all projects using this template library.
|
|
21
21
|
# see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/standard.md
|
|
22
|
-
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@
|
|
22
|
+
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/standard-build@v3.4
|
|
23
23
|
|
|
24
24
|
# Runs rspec tests and rubocop on the project
|
|
25
25
|
# see https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/templates/ruby.md
|
|
26
|
-
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@
|
|
26
|
+
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/ruby-build@v3.4
|
|
27
27
|
|
|
28
|
-
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@
|
|
28
|
+
- component: $CI_SERVER_FQDN/gitlab-com/gl-infra/common-ci-tasks/danger@v3.4
|
|
29
29
|
|
|
30
30
|
.test_template: &test_definition
|
|
31
31
|
extends: .with_bundle
|
data/.pre-commit-config.yaml
CHANGED
|
@@ -25,7 +25,7 @@ repos:
|
|
|
25
25
|
# Documentation available at
|
|
26
26
|
# https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/pre-commit.md
|
|
27
27
|
- repo: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks
|
|
28
|
-
rev: v3.
|
|
28
|
+
rev: v3.4 # renovate:managed
|
|
29
29
|
|
|
30
30
|
hooks:
|
|
31
31
|
- id: shellcheck # Run shellcheck for changed Shell files
|
data/.tool-versions
CHANGED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
owning-stage: '~devops::developer experience'
|
|
3
|
+
description: 'Logging Field Standardization: Dynamic Runtime Linting'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Logging Field Standardization ADR: Dynamic Runtime Linting
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
GitLab is implementing a [logging field standardization initiative](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/) to ensure logs are queryable and actionable across all systems. We need a mechanism to identify and track deprecated or non-standard logging fields across multiple codebases.
|
|
11
|
+
|
|
12
|
+
### Requirements
|
|
13
|
+
|
|
14
|
+
The solution must:
|
|
15
|
+
|
|
16
|
+
1. Detect deprecated fields at the point of emission (runtime).
|
|
17
|
+
1. Provide immediate feedback to developers (shift-left).
|
|
18
|
+
1. Prevent new violations without blocking existing work.
|
|
19
|
+
1. Support gradual migration from deprecated to standard fields.
|
|
20
|
+
1. Never affect production performance.
|
|
21
|
+
1. Provide clear guidance on standard field replacements.
|
|
22
|
+
|
|
23
|
+
### The problem with static analysis
|
|
24
|
+
|
|
25
|
+
We initially considered RuboCop (static linting), but this approach is inadequate due to Ruby's [dynamic and complex field construction](https://gitlab.com/gitlab-org/gitlab/-/blob/cfd4fb97968d1f7d30f39f89740e414e9437063a/lib/bulk_imports/logger.rb#L46).
|
|
26
|
+
|
|
27
|
+
Static analysis can't reliably detect:
|
|
28
|
+
|
|
29
|
+
- Fields merged from hash arguments.
|
|
30
|
+
- Dynamically constructed field names.
|
|
31
|
+
- Fields passed through multiple abstraction layers.
|
|
32
|
+
- Conditional field inclusion based on runtime state.
|
|
33
|
+
|
|
34
|
+
## Decision
|
|
35
|
+
|
|
36
|
+
Implement dynamic runtime linting to validate logging fields as they're emitted during development and testing, rather than using static analysis.
|
|
37
|
+
|
|
38
|
+
The validator will:
|
|
39
|
+
|
|
40
|
+
- Intercept logging calls at runtime to detect deprecated fields.
|
|
41
|
+
- Compare detected violations against a frozen baseline of known violations.
|
|
42
|
+
- Raise an error on new violations while ignoring tracked existing tracked violations.
|
|
43
|
+
- Provide immediate feedback to developers during local development.
|
|
44
|
+
- Never affect production performance.
|
|
45
|
+
|
|
46
|
+
## Consequences
|
|
47
|
+
|
|
48
|
+
### Benefits
|
|
49
|
+
|
|
50
|
+
- **Shift-left feedback**: Developers discover violations during local development, not in code review.
|
|
51
|
+
- **Comprehensive detection**: Captures violations from all code execution paths (tests, Rake tasks, console, development environments).
|
|
52
|
+
- **Accurate detection**: Runtime interception catches dynamically constructed fields that static analysis misses.
|
|
53
|
+
- **Non-blocking**: Existing violations don't prevent development. They're tracked explicitly in baseline.
|
|
54
|
+
- **Regression prevention**: CI fails on new violations, preventing deprecated fields from reappearing.
|
|
55
|
+
- **Clear guidance**: Exact replacement field suggested for each violation.
|
|
56
|
+
- **Zero production impact**: Validation only runs in development and test environments.
|
|
57
|
+
|
|
58
|
+
### Trade-offs
|
|
59
|
+
|
|
60
|
+
- **Execution path dependency**: Only detects violations in code paths that execute during the process.
|
|
61
|
+
- **Runtime overhead**: Adds interception to all non-production processes.
|
|
62
|
+
- **At-exit reporting**: Violations not visible until process completes.
|
|
63
|
+
- **Baseline maintenance**: YAML files require updates when violations are fixed or added.
|
|
64
|
+
- **Learning curve**: Developers must understand baseline management.
|
|
65
|
+
- **File-level scoping**: Multiple violations in the same file are tracked together, making partial fixes during test runs challenging.
|
|
66
|
+
|
|
67
|
+
### Risks and mitigations
|
|
68
|
+
|
|
69
|
+
| Risk | Mitigation |
|
|
70
|
+
|------|------------|
|
|
71
|
+
| Limited code path coverage misses violations | Use Kibana to identify fields in production logs, run comprehensive test suites, use development server testing |
|
|
72
|
+
| Baseline drift across branches | Clear documentation, automated baseline regeneration support |
|
|
73
|
+
| At-exit reporting missed if process crashes | Violations still prevented in CI where processes complete successfully |
|
|
74
|
+
|
|
75
|
+
## Alternatives
|
|
76
|
+
|
|
77
|
+
### Alternative 1: Static analysis with RuboCop
|
|
78
|
+
|
|
79
|
+
Use custom RuboCop cops to detect deprecated field usage.
|
|
80
|
+
|
|
81
|
+
Rejected because:
|
|
82
|
+
|
|
83
|
+
- Can't handle fields merged from hash variables.
|
|
84
|
+
- Would produce many false negatives.
|
|
85
|
+
- Complex pattern matching still misses dynamic cases.
|
|
86
|
+
- Poor developer experience with unclear violations.
|
|
87
|
+
|
|
88
|
+
### Alternative 2: Manual tracking
|
|
89
|
+
|
|
90
|
+
Track violations in spreadsheets or GitLab issues.
|
|
91
|
+
|
|
92
|
+
Rejected because:
|
|
93
|
+
|
|
94
|
+
- No automated enforcement or detection.
|
|
95
|
+
- Manual process becomes stale quickly.
|
|
96
|
+
- No shift-left feedback to developers.
|
|
97
|
+
- Can't prevent regressions.
|
|
98
|
+
|
|
99
|
+
### Alternative 3: Grep-based CI checks
|
|
100
|
+
|
|
101
|
+
Search source code for deprecated field strings in CI.
|
|
102
|
+
|
|
103
|
+
Rejected because:
|
|
104
|
+
|
|
105
|
+
- High false positive rate (matches in comments, strings, tests).
|
|
106
|
+
- Can't distinguish field usage from definitions.
|
|
107
|
+
- No stable tracking across refactoring.
|
|
108
|
+
- Poor user experience with unclear error messages.
|
|
109
|
+
|
|
110
|
+
### Alternative 4: Production log analysis only
|
|
111
|
+
|
|
112
|
+
Rely solely on Kibana analysis to find deprecated fields.
|
|
113
|
+
|
|
114
|
+
Rejected because:
|
|
115
|
+
|
|
116
|
+
- No prevention, only reactive detection.
|
|
117
|
+
- Violations already in production when discovered.
|
|
118
|
+
- No developer feedback during development.
|
|
119
|
+
- Difficult to trace back to specific code locations.
|
|
120
|
+
|
|
121
|
+
## References
|
|
122
|
+
|
|
123
|
+
- [Parent Epic](https://gitlab.com/groups/gitlab-org/quality/-/work_items/235)
|
|
124
|
+
- [Observability Field Standardisation](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/observability_field_standardisation/)
|
data/gitlab-labkit.gemspec
CHANGED
|
@@ -25,11 +25,11 @@ Gem::Specification.new do |spec|
|
|
|
25
25
|
spec.add_runtime_dependency "grpc", ">= 1.75" # Be sure to update the "grpc-tools" dev_dependency too
|
|
26
26
|
spec.add_runtime_dependency "google-protobuf", ">= 3.25", "< 5.0"
|
|
27
27
|
spec.add_runtime_dependency "jaeger-client", "~> 1.1.0"
|
|
28
|
-
spec.add_runtime_dependency 'json_schemer', '
|
|
28
|
+
spec.add_runtime_dependency 'json_schemer', '>= 2.3.0', '< 3.0'
|
|
29
29
|
spec.add_runtime_dependency "openssl", "~> 3.3.2"
|
|
30
30
|
spec.add_runtime_dependency "opentracing", "~> 0.4"
|
|
31
31
|
spec.add_runtime_dependency "pg_query", ">= 6.1.0", "< 7.0"
|
|
32
|
-
spec.add_runtime_dependency "prometheus-client-mmap", "
|
|
32
|
+
spec.add_runtime_dependency "prometheus-client-mmap", ">= 1.2", "< 2.0"
|
|
33
33
|
spec.add_runtime_dependency "redis", "> 3.0.0", "< 6.0.0"
|
|
34
34
|
|
|
35
35
|
# Please maintain alphabetical order for dev dependencies
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
require "time"
|
|
3
|
+
require "date"
|
|
3
4
|
require "logger"
|
|
4
5
|
require "json"
|
|
5
6
|
|
|
@@ -37,6 +38,12 @@ module Labkit
|
|
|
37
38
|
end
|
|
38
39
|
|
|
39
40
|
def format_message(severity, timestamp, progname, message)
|
|
41
|
+
data = format_data(severity, timestamp, progname, message)
|
|
42
|
+
|
|
43
|
+
dump_json(data) << "\n"
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def format_data(severity, timestamp, progname, message)
|
|
40
47
|
data = default_attributes
|
|
41
48
|
data[:severity] = severity
|
|
42
49
|
data[:time] = timestamp.utc.iso8601(3)
|
|
@@ -52,11 +59,10 @@ module Labkit
|
|
|
52
59
|
data[:message] = message
|
|
53
60
|
when Hash
|
|
54
61
|
reject_reserved_log_keys!(message)
|
|
55
|
-
format_time!(data)
|
|
56
62
|
data.merge!(message)
|
|
57
63
|
end
|
|
58
64
|
|
|
59
|
-
|
|
65
|
+
data
|
|
60
66
|
end
|
|
61
67
|
|
|
62
68
|
private
|
|
@@ -78,16 +84,6 @@ module Labkit
|
|
|
78
84
|
"\n\nUse key names that are descriptive e.g. by using a prefix."
|
|
79
85
|
end
|
|
80
86
|
end
|
|
81
|
-
|
|
82
|
-
def format_time!(hash)
|
|
83
|
-
hash.each do |key, value|
|
|
84
|
-
if value.is_a?(Time)
|
|
85
|
-
hash[key] = value.utc.iso8601(3)
|
|
86
|
-
elsif value.is_a?(Hash)
|
|
87
|
-
format_time!(value)
|
|
88
|
-
end
|
|
89
|
-
end
|
|
90
|
-
end
|
|
91
87
|
end
|
|
92
88
|
end
|
|
93
89
|
end
|
|
@@ -236,9 +236,9 @@ module Labkit
|
|
|
236
236
|
user_experience_id: id,
|
|
237
237
|
feature_category: @definition.feature_category,
|
|
238
238
|
urgency: @definition.urgency,
|
|
239
|
-
start_time: @start_time,
|
|
240
|
-
checkpoint_time: @checkpoint_time,
|
|
241
|
-
end_time: @end_time,
|
|
239
|
+
start_time: @start_time&.iso8601(3),
|
|
240
|
+
checkpoint_time: @checkpoint_time&.iso8601(3),
|
|
241
|
+
end_time: @end_time&.iso8601(3),
|
|
242
242
|
elapsed_time_s: elapsed_time,
|
|
243
243
|
urgency_threshold_s: urgency_threshold
|
|
244
244
|
)
|
data/scripts/prepare-dev-env.sh
CHANGED
|
@@ -53,8 +53,11 @@ fi
|
|
|
53
53
|
|
|
54
54
|
# install mise/asdf dependencies
|
|
55
55
|
echo "installing required plugins with mise install.."
|
|
56
|
-
mise plugins update
|
|
56
|
+
mise plugins update -q
|
|
57
57
|
mise install
|
|
58
|
+
|
|
59
|
+
# set PROMPT_COMMAND to empty value for mise if unset
|
|
60
|
+
: "${PROMPT_COMMAND:=}"
|
|
58
61
|
eval "$(mise activate bash)"
|
|
59
62
|
|
|
60
63
|
# pre-commit is optional
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: gitlab-labkit
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.1.
|
|
4
|
+
version: 1.1.3
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Andrew Newdigate
|
|
@@ -101,16 +101,22 @@ dependencies:
|
|
|
101
101
|
name: json_schemer
|
|
102
102
|
requirement: !ruby/object:Gem::Requirement
|
|
103
103
|
requirements:
|
|
104
|
-
- - "
|
|
104
|
+
- - ">="
|
|
105
105
|
- !ruby/object:Gem::Version
|
|
106
|
-
version: 2.
|
|
106
|
+
version: 2.3.0
|
|
107
|
+
- - "<"
|
|
108
|
+
- !ruby/object:Gem::Version
|
|
109
|
+
version: '3.0'
|
|
107
110
|
type: :runtime
|
|
108
111
|
prerelease: false
|
|
109
112
|
version_requirements: !ruby/object:Gem::Requirement
|
|
110
113
|
requirements:
|
|
111
|
-
- - "
|
|
114
|
+
- - ">="
|
|
115
|
+
- !ruby/object:Gem::Version
|
|
116
|
+
version: 2.3.0
|
|
117
|
+
- - "<"
|
|
112
118
|
- !ruby/object:Gem::Version
|
|
113
|
-
version:
|
|
119
|
+
version: '3.0'
|
|
114
120
|
- !ruby/object:Gem::Dependency
|
|
115
121
|
name: openssl
|
|
116
122
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -163,16 +169,22 @@ dependencies:
|
|
|
163
169
|
name: prometheus-client-mmap
|
|
164
170
|
requirement: !ruby/object:Gem::Requirement
|
|
165
171
|
requirements:
|
|
166
|
-
- - "
|
|
172
|
+
- - ">="
|
|
173
|
+
- !ruby/object:Gem::Version
|
|
174
|
+
version: '1.2'
|
|
175
|
+
- - "<"
|
|
167
176
|
- !ruby/object:Gem::Version
|
|
168
|
-
version:
|
|
177
|
+
version: '2.0'
|
|
169
178
|
type: :runtime
|
|
170
179
|
prerelease: false
|
|
171
180
|
version_requirements: !ruby/object:Gem::Requirement
|
|
172
181
|
requirements:
|
|
173
|
-
- - "
|
|
182
|
+
- - ">="
|
|
183
|
+
- !ruby/object:Gem::Version
|
|
184
|
+
version: '1.2'
|
|
185
|
+
- - "<"
|
|
174
186
|
- !ruby/object:Gem::Version
|
|
175
|
-
version:
|
|
187
|
+
version: '2.0'
|
|
176
188
|
- !ruby/object:Gem::Dependency
|
|
177
189
|
name: redis
|
|
178
190
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -469,6 +481,7 @@ files:
|
|
|
469
481
|
- Rakefile
|
|
470
482
|
- config/user_experience_slis/schema.json
|
|
471
483
|
- config/user_experience_slis/testing_sample.yml
|
|
484
|
+
- doc/architecture/decisions/001_field_standardization_dynamic_runtime_linting.md
|
|
472
485
|
- gitlab-labkit.gemspec
|
|
473
486
|
- lib/gitlab-labkit.rb
|
|
474
487
|
- lib/labkit/context.rb
|
|
@@ -555,7 +568,6 @@ files:
|
|
|
555
568
|
- lib/labkit/user_experience_sli/null.rb
|
|
556
569
|
- lib/labkit/user_experience_sli/registry.rb
|
|
557
570
|
- renovate.json
|
|
558
|
-
- scripts/install-asdf-plugins.sh
|
|
559
571
|
- scripts/prepare-dev-env.sh
|
|
560
572
|
- scripts/update-asdf-version-variables.sh
|
|
561
573
|
homepage: https://gitlab.com/gitlab-org/labkit-ruby
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env bash
|
|
2
|
-
# Vendored from https://gitlab.com/gitlab-com/gl-infra/common-template-copier
|
|
3
|
-
# Consider contributing upstream when updating this file
|
|
4
|
-
|
|
5
|
-
# This file is deprecated: going forward running `mise install` should be sufficient.
|
|
6
|
-
|
|
7
|
-
set -euo pipefail
|
|
8
|
-
IFS=$'\n\t'
|
|
9
|
-
|
|
10
|
-
echo >&2 -e "2024-08-07: this file is deprecated: going forward, simply run 'mise install' to install plugins."
|
|
11
|
-
echo >&2 -e "Recommended reading: https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/main/docs/developer-setup.md"
|
|
12
|
-
|
|
13
|
-
mise install
|