README
¶
LabKit 🧪 🔬 🥼 🥽 🦠 🧫 🧬 💉
LabKit is minimalist library to provide functionality for Go services at GitLab.
Packages
Correlation
import (
"gitlab.com/gitlab-org/labkit/correlation"
)
Logging
import (
logkit "gitlab.com/gitlab-org/labkit/log"
)
Masking
import (
"gitlab.com/gitlab-org/labkit/mask"
)
Metrics
import (
"gitlab.com/gitlab-org/labkit/metrics"
)
Monitoring
import (
"gitlab.com/gitlab-org/labkit/monitoring"
)
Federal Information Processing Standards (FIPS)
This package is used for checking whether a binary has been properly compiled with FIPS support.
import (
"gitlab.com/gitlab-org/labkit/fips"
)
Developing LabKit
Anyone can contribute!
Architectural guidelines
Please be aware of the following architectural guidelines.
Public APIs in LabKit should be stable
- LabKit is a library, not an application, and as such, we value compatibility highly.
- Public APIs in LabKit should be backward compatible. This should be done by making APIs forward extensible.
- Add methods, but do not add (non-optional) parameters to existing methods.
- Use Functional Options where possible.
APIs should be intuitive and friendly
- APIs should have an intuitive interface.
- Spend time ensuring thinking about what the best interface is.
- Include excellent godocs, including package documentation in
doc.go.
Dependency Management
- Be extremely careful about the dependencies your packages include. Be prepared to justify any dependencies you bring into a package.
- If not users will require a dependency, consider including it in a subpackage (e.g.
gitlab.com/gitlab-org/labkit/correlation/grpc), especially if the dependency is large or has a deep dependency tree of it's own.
- If not users will require a dependency, consider including it in a subpackage (e.g.
- Be even more careful about the dependencies that you expose through the API of a package.
- Follow this rule: packages can depend on their parent packages, but not their siblings or children.
- If required, declare common models in the root package.
Architectural Philosophy
Taken from A Philosophy of Software Design, by John Ousterhout. This book is recommended reading.
- Modules should be deep.
- Interfaces should be designed to make the most common usage as simple as possible.
- Separate general-purpose and special-purpose code.
- Design it twice.
- Comments should describe things that are not obvious from the code.
Review Process
Please assign your MR to a reviewer for a first review, followed by a maintainer review.
Currently, the reviewers are:
The maintainers are:
Release Process
LabKit uses semantic releases. Please use the Conventional Commits commit format.
When to release a new version
A new release should only be created when there is a new user-facing feature or a bug fix. CI, docs, and refactoring shouldn't result in a new release unless it's a big change.
Downstream Vendoring
While not strictly neccessary, it is preferred for the author of changes to also send downstream MRs to the applications that use LabKit. Since the library has a strict backwards compatibility policy, these upgrades should be fairly straightforward.
Use the ./downstream-vendor.sh to update the LabKit library in all known GitLab applications. You will need to have git+ssh credentials setup to push directly to the repositories. The script currently does not work on forked projects unfortunately. Once completed, the script will output a list of MRs, for your review.
$ ./downstream-vendor.sh
# .....
####################################
# completed successfully
# https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/657
# https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2816
# https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/396
# https://gitlab.com/gitlab-org/container-registry/-/merge_requests/427
# https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/173
Documentation
¶
Overview ¶
Package labkit is a minimalist library to provide functionality for Go services at GitLab.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package correlation is the primary entrypoint into LabKit's correlation utilities.
|
Package correlation is the primary entrypoint into LabKit's correlation utilities. |
|
raven
Package raven is allows correlation information to be added to raven requests.
|
Package raven is allows correlation information to be added to raven requests. |
|
Package errortracking abstracts all error reporting features away from services like workhorse or pages
|
Package errortracking abstracts all error reporting features away from services like workhorse or pages |
|
Package log provides sensible logging defaults for Labkit.
|
Package log provides sensible logging defaults for Labkit. |
|
Package mask offers the functionality for non-reversible masking of sensitive data in the GitLab application.
|
Package mask offers the functionality for non-reversible masking of sensitive data in the GitLab application. |
|
Package metrics is the primary entrypoint into LabKit's metrics utilities.
|
Package metrics is the primary entrypoint into LabKit's metrics utilities. |
|
Package monitoring provides a monitoring endpoint and Continuous Profiling for Go service processes.
|
Package monitoring provides a monitoring endpoint and Continuous Profiling for Go service processes. |
|
Package tracing is the primary entrypoint into LabKit's distributed tracing functionality.
|
Package tracing is the primary entrypoint into LabKit's distributed tracing functionality. |