The ccache software maintains a cache to store compilation artefacts, so the next time you compile the same source file, you can get the compiled code from the cache. That speeds up a lot recompilation.

At Nasqueron, ccache is useful to speed up Poudriere builds to test FreeBSD ports. To be able to follow if the cache is useful, we devised a Grafana dashboard to expose metrics from ccache.

If you run ccache -s, it prints statistics. For example with ccache 3:

$ ccache -V | head -n1
ccache version 3.7.12

$ ccache -s
cache directory                     /var/cache/ccache
primary config                      /var/cache/ccache/ccache.conf
secondary config      (readonly)    /usr/local/etc/ccache.conf
stats updated                       Sun Oct  6 13:56:59 2024
cache hit (direct)                   571
cache hit (preprocessed)             309
cache miss                         10089
cache hit rate                      8.02 %
called for link                     1577
called for preprocessing             265
multiple source files                  3
compiler produced no output            3
compiler produced empty output         4
compile failed                       612
preprocessor error                   292
bad compiler arguments                68
unsupported source language           14
autoconf compile/link               2829
no input file                        426
cleanups performed                     0
files in cache                     24590
cache size                         167.9 kB
max cache size                       5.0 GB

Converted into OpenMetrics format, that gives:

$ ccache-metrics
# TYPE ccache_cache_directory info
ccache_cache_directory_info{path="/var/cache/ccache"} 1
# TYPE ccache_primary_config info
ccache_primary_config_info{path="/var/cache/ccache/ccache.conf"} 1
# TYPE ccache_secondary_config info
ccache_secondary_config_info{path="/usr/local/etc/ccache.conf"} 1
# TYPE ccache_stats_updated counter
ccache_stats_updated_total 1728223019
# TYPE ccache_cache_hit_direct counter
ccache_cache_hit_direct_total 571
# TYPE ccache_cache_hit_preprocessed counter
ccache_cache_hit_preprocessed_total 309
# TYPE ccache_cache_miss counter
ccache_cache_miss_total 10089
# TYPE ccache_cache_hit_rate gauge
ccache_cache_hit_rate 0.0802
# TYPE ccache_called_for_link counter
ccache_called_for_link_total 1577
# TYPE ccache_called_for_preprocessing counter
ccache_called_for_preprocessing_total 265
# TYPE ccache_multiple_source_files counter
ccache_multiple_source_files_total 3
# TYPE ccache_compiler_produced_no_output counter
ccache_compiler_produced_no_output_total 3
# TYPE ccache_compiler_produced_empty_output counter
ccache_compiler_produced_empty_output_total 4
# TYPE ccache_compile_failed counter
ccache_compile_failed_total 612
# TYPE ccache_preprocessor_error counter
ccache_preprocessor_error_total 292
# TYPE ccache_bad_compiler_arguments counter
ccache_bad_compiler_arguments_total 68
# TYPE ccache_unsupported_source_language counter
ccache_unsupported_source_language_total 14
# TYPE ccache_autoconf_compile_link counter
ccache_autoconf_compile_link_total 2829
# TYPE ccache_no_input_file counter
ccache_no_input_file_total 426
# TYPE ccache_cleanups_performed counter
ccache_cleanups_performed_total 0
# TYPE ccache_files_in_cache gauge
ccache_files_in_cache 24590
# TYPE ccache_cache_size gauge
ccache_cache_size 171929.6
# TYPE ccache_max_cache_size gauge
ccache_max_cache_size 5368709120.0
# EOF

Those metrics can then be published to a timeseries database like Prometheus.

The Python code to perform this conversion is available in our operations repository. It doesn’t have any dependency.

Important note about ccache versions. As we target FreeBSD and Poudriere, the code handles ccache 3. The parsing code need to be updated for ccache 4, as their statistics output format changed. Run ccache -svv to get the same kind of output under ccache 4, but we need to ignore section headers.