LabKit-Ruby 🔬🔬🔬🔬🔬

LabKit-Ruby is minimalist library to provide functionality for Ruby services at GitLab.

LabKit-Ruby is the Ruby companion for LabKit, a minimalist library to provide functionality for Go services at GitLab.

LabKit-Ruby and LabKit are intended to provide similar functionality, but use the semantics of their respective languages, so are not intended to provide identical APIS.

Documentation

API Documentation is available at the Rubydoc site.

Changelog

The changelog is available via tagged release notes

Functionality

LabKit-Ruby provides functionality in a number of areas:

  1. Labkit::Context used for providing context information to log messages.
  2. Labkit::Correlation for accessing the correlation id. (Generated and propagated by Labkit::Context)
  3. Labkit::UserExperienceSli for tracking User Experience SLIs. More on the README.
  4. Labkit::ApplicationSli for tracking Application SLIs (Apdex and error-rate). More on the README.
  5. Labkit::FIPS for checking for FIPS mode and using FIPS-compliant algorithms.
  6. Labkit::Logging for sanitizing log messages.
  7. Labkit::Metrics for metrics. More on the README.
  8. Labkit::RateLimit for rules-based, Redis-backed rate limiting. More on the README.
  9. Labkit::RSpec for RSpec matchers to test Labkit functionality (requires selective loading). More on the README.
  10. Labkit::Tracing for handling and propagating distributed traces.

Developing

Anyone can contribute!

$ git clone [email protected]:gitlab-org/labkit-ruby.git
$ cd labkit-ruby
$ bundle install

$ # Autoformat code and auto-correct linters
$ bundle exec rake fix

$ # Run tests, linters
$ bundle exec rake verify

Some specs require a real Redis instance. When you run the suite locally, it will automatically start one via docker compose up -d redis (see docker-compose.yml) and tear it down again when the test process exits. Redis is exposed on localhost:6390 so it does not collide with a local GDK/Caproni Redis on the default port.

To opt out of autostart (e.g. you've started Redis some other way), set LABKIT_TEST_REDIS_URL to a reachable instance, or LABKIT_TEST_REDIS_NO_AUTOSTART=1 to fail loudly instead of spawning.

The conformance CI job runs the labkit-spec conformance harness against the spec's Ruby server, with the gitlab-labkit gem installed from your branch instead of the released version. A change to logging, lifecycle, or rate limiting is therefore checked against the cross-SDK scenarios before it merges. To run it locally, clone labkit-spec and replace the gitlab-labkit line in conformance/servers/ruby/Gemfile with

gem "gitlab-labkit", path: "/path/to/labkit-ruby"

then run mise run conformance:ruby from the spec checkout (the rate-limit aspect needs Docker or CONFORMANCE_REDIS_ADDR).

If your change also needs a labkit-spec change (a new scenario, or an update to its Ruby server), open that MR first and point LABKIT_SPEC_REF in .gitlab-ci.yml at its branch so this job validates both together. Set it back to main once the spec MR merges; a non-main ref must not reach master.

Please also review the development section of the LabKit (go) README for details of the LabKit architectural philosophy.

To work on some of the scripts we use for releasing a new version, make sure to add a new .env.sh.

cp .env.example.sh .env.sh`

Inside .env.sh, add a personal acccess token for the CHANGELOG_GITLAB_TOKEN environment variable. Next source the file:

. .env.sh

Releasing a new version

Releasing a new version can be done by pushing a new tag, or creating it from the interface.

A new changelog will automatically be added to the release on Gitlab.

The new version will automatically be published to gitlab-labkit on rubygems when the pipeline for the tag completes. It might take a few minutes before the update is available.

A gem called labkit-ruby is also published to RubyGems.org as a placeholder. The same bot that pushes this gem has access.