Custom Metrics Reports on GitLab

---

What Metrics Reports are

I have recently discovered a useful feature of GitLab's premium tier: custom Metrics Reports.

In GitLab's words:

You can configure your job to use custom Metrics Reports, and GitLab displays a report on the merge request so that it’s easier and faster to identify changes without having to check the entire log.

In the same way GitLab's shows unit test reports, you can make it show any kind of metrics collected in your pipeline.

Why you may want to use Metrics Reports

The first thing I did when I discovered this feature was creating a command to log the size of each individual component in our shared library of web components at RIPE NCC.

As a web developer, having this step in your pipelines allows you to catch unexpected bundle increases before they even make it to your main branch. You could also set up a more complex pipeline to measure web vitals and log them as metrics to keep track of your app's behavior as the source code changes.

However, metrics are not only useful on the web: as an embedded developer you'll be interested in tracking the size of your firmware for example.

How to set up Metrics Reports in your pipeline

Adding metrics to your pipeline is extremely easy. You only need to generate a metrics.txt file that contains your metrics following the OpenMetrics format.

The simplest form of metrics is a key-value pair separated by a space or you can log more complex metrics following the syntax popularized by Prometheus. For example:

# metrics.txt
dialog.js 13KB
file_size{component="dialog.js"} 13KB

Then in your pipeline, you'll want to generate this file on every commit and save it as a Metrics Reports.

# .gitlab-ci.yml
build:
  stage: build
  script:
    - yarn install
    - yarn build
    # in this case I wrote a node script to generate metrics
    - node ./src/scripts/openMetrics.js > metrics.txt
  artifacts:
    reports:
      metrics: metrics.txt

Conclusion

That's it! Now every merge request will immediately show you if your metrics have changed.

Appendix A - Troubleshooting

When setting up metrics I had one minor hiccup involving manual jobs in the pipeline.

I thought it was a bug, and raised an issue to which I got a very rapid reply.

When you have a manual job you'll want to set allow_failure: true so the pipeline is marked as completed. If you don't, metrics won't appear in the UI until you run the manual job.

e.g. a clean step to be performed before merging into main:

# .gitlab-ci.yml
stop-review:
  stage: clean
  script:
    - ...
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual
  allow_failure: true # <- important