Advanced Configuration
In this section you can find detailed information about how metrics are collected and pushed to the dashboard.
Architecture¶
The Metrics service is a simple JVM application that is automatically spawned when compiling with Hydra.
During compilation, Hydra collects useful compile-time metrics and stores the data in a binary format inside the metrics directory folder, i.e., ${user.home}/.triplequote/metrics. The Metrics service constantly watches the metrics folder and when it detects a new file with the expected format, the Metric service tries to push it to the configured dashboard server.
Therefore, the metrics folder effectively acts as a communication channel between Hydra and the Metrics service.
This decoupling ensures that data is not lost even if the metrics service has crashed or the server endpoint is not available. On restart, or when the server becomes available, all accumulated data will be published to the server.
The Metrics service detects and processes metrics binary data file one after the other. Binary metric files are deleted only after the dashboard server has acknowledged that the file's data was successfully persisted. This entails that if the dashboard server cannot be reached, all the metrics binary data files are kept until a connection with the dashboard server can be established. At which point, all pending metrics are going to be pushed to the dashboard server. In short, no compile metric data is ever lost.
Lifecycle¶
The metrics service is started automatically by Hydra when you start a build (sbt / maven / gradle). With sbt you can also use the hydraMetricsServiceStart task. Note that the Hydra CLI does not ship the Metrics service.
By default there is only one Metrics service process running independently of the number of projects you may be actively working on. When the Metrics service starts, a .metrics.runid file is created in the metrics directory (i.e., ${user.home}/.triplequote/metrics). This file is used to guarantee that at most one Metrics service process is ever running. It is in fact expected that when the Metrics service stops, the .metrics.runid will be automatically removed.
If you want to use multiple metrics directories, there will be a Metrics service service process for each directory, with a corresponding .metrics.runid file. You can differentiate the running Metrics services by setting up each service configuration file according to your needs.
Manual restart¶
To list running Metrics services you can use jps (a tool included with every Oracle JDK installation):
$ jps -v | grep MetricsService <pid> MetricsService -Xmx256M -Dtriplequote.dashboard.client.metricsDirectory=/Users/john/.triplequote/metrics -Dconfig.file=/Users/john/.triplequote/metrics/config/metrics-service.conf
Therefore, if you would like to push data to a shared remote server, make sure to kill the ongoing process using the <pid> displayed in the jps output:
$ kill <pid>
Calling jps -v | grep MetricsService again should return no output, confirming the Metrics service process was stopped. The Metrics service will be respawned when you fire a new build. Check that the server is running as expected by executing again jps -v | grep MetricsService.
As stated in the Lifecycle section, the service will be started when you fire up the next build (or with the hydraMetricsServiceStart task within sbt).
The metrics directory folder¶
Each metrics folder contains at its root compilation metrics files, dropped here by Hydra during builds. The same folder can be used for multiple projects if they can share the same Metrics service configuration. By default both hydra and the metrics service use ${user.home}/.triplequote/metrics.
See Hydra settings for how to customize the metrics directory location, depending on your build environment.
Other files and directories within the root metrics folder are:
- the
configfolder: stores the service configuration file - the
logfolder: stores metric service logs. See the logging section for details - the
quarantinedirectory: this folder is created to store invalid metric files - the
.metrics.runidprocess lock file: See this discussion for details
Configuration¶
Configuration options:
| Property | Default value | Description |
|---|---|---|
| triplequote.dashboard.client.metricsUserId | ${user.name} | User ID attached to metrics uploaded by the metrics service |
| triplequote.dashboard.client.metricsHostId | Host ID attached to metrics uploaded by the metrics service | |
| triplequote.dashboard.client.serverUrl | http://localhost:3333/metrics | Dashboard server URL |
| triplequote.dashboard.client.clientUsername | Username for authenticating with the dashboard server | |
| triplequote.dashboard.client.clientPassword | Password for authenticating with the dashboard server |
See the Remote section for more details about configuration.
Logging¶
When the Metric service is started you should notice an additional log directory under ${user.home}/.triplequote/metrics. Inside you should see a metrics.log (possibly together with some additional compressed files for older logs).
By default, the log level is set "INFO". If needed, you can increase the log level by adding -Dhydra.logLevel=DEBUG to the hydraMetricsServiceJvmOptions setting in your build.