sample-apps

What is a Grafana Cloud Integration, and what are sample-apps supporting them?

A Grafana Cloud Integration is a prebuilt package of dashboards, recording rules, alerts, metadata, and scrape configurations intended to make it quick to add monitoring to a number of systems. See here for more information on Grafana Cloud Integrations and the Integrations reference for a list of supported systems.

Sample-apps are pre-configured applications and load-testing that allows us to spin up a system for a given integration and quickly validate the metrics emitted match what we expect for our Cloud Integrations.

Adding CI support to a Multipass based sample-app

Please note, this is not a full tutorial in creating sample-apps from scratch.

Sample-apps are run in CI using Multipass on ubuntu-latest-8-core, with both Loki and Mimir spun up outside the sample-app. Nested virtualisation is available, and multiple VMs can be created as desired.

Workflow timeout is currently set at 30 minutes, and will fail if exceeded

The CI workflow expects a few things from a CI enabled sample app. For a working example, please check out the openldap sample-app:

1. Ensure the sample-app is built using Multipass
   • Sample should be stand-alone and not contain any databases
2. Ensure sample-app has load-generation scripts or capabilities to accurately produce metrics for the majority of use-cases
3. Ensure sample-app name matches integration slug
4. Add an expected_metrics file to the sample-app dir, containing a newline separated list of Prometheus metrics expected by the integration, e.g:

   up
   metric_name_1
   metric_name_2
   

5. Add a .config file to the sample-app dir
   • Set the JOB_LABEL variable to match the integration's job label
   • [Optional] Set SAMPLE_APP_SETUP_TIME to define how long the CI workflow should wait before checking metrics. (Default: 180s)
   • [Optional] Set METRICS_SUCCESS_RATE_REQUIRED to define the required percentage of metrics that has to be generated by the sample app, as compared to the metrics contained within expected_metrics. E.g. if 100% of expected metrics must be generated by the sample app, with no deviation allowed, set this value to 1.0. (Default: 0.8 for 80% match)
6. Makefile
   1. Should be present in sample-app dir
   2. Variables should be created for logs and metrics database hosts, e.g:

      LOKI_INSTANCE := your-loki-instance:3100
      PROMETHEUS_INSTANCE := your-prometheus-instance:9090
      

   3. make run-ci must be a valid make option, making use of the variables defined in 2., such that a clean cloud-init or similar configuration is generated and applied, load-testing is run, and so forth depending on sample-app requirements

Excluding your sample-app from CI runs

In some cases, such as sample-apps relying on cloud providers, externally hosted services, or other such edge-cases it may be impossible to automatically spin up and test them with Github Actions.

Should this be the case, you must add a blank .CI_BYPASS file to your sample-apps directory. If this file is not present, the Github Actions workflow will run and fail your changes.