Table of Contents

Metrics Configuration

Metrics in this application can be configured by adjusting values in the boot.json file. This is an example of what can be configured:

Default configuration

A default configuration for the metrics is applied out of the box, but it is possible to override it in boot.json.

This is what the default configuration for the metrics looks like:

{
    "commonTags": {
        "applicationName": "PAS",
        "applicationVersion": "{{SYS:APPLICATION_VERSION}}"
    },
    "elasticSearch": {
        "autoCreateIndex": false,
        "enabled": false,
        "host": "http://localhost:9200",
        "password": null,
        "step": "PT10S",
        "username": null
    },
    "enableClassLoaderMetrics": true,
    "enableJvmGcMetrics": true,
    "enableJvmMemoryMetrics": true,
    "enableJvmThreadMetrics": true,
    "enableProcessorMetrics": true,
    "enableVertxMetrics": true,
    "enabled": true,
    "prometheus": {
        "enabled": false,
        "publishQuantiles": true,
        "endpoints": [
            {
                "httpConfigurationId": null,
                "path": "/metrics",
                "authentication": {
                    "type": "basic",
                    "username": "read",
                    "password": "public"
                }
            }
        ]
    }
}

Metrics Configuration Options

  • commonTags: Dictionary of tags that will be set for all metrics.
  • elasticSearch: Configuration for Elasticsearch metrics.
    • autoCreateIndex: Whether to automatically create an index for metrics.
    • enabled: Enable or disable Elasticsearch metrics.
    • host: Elasticsearch host URL.
    • password: Password for Elasticsearch (if applicable).
    • step: Time interval for pushing metrics.
    • username: Username for Elasticsearch (if applicable).
  • enableClassLoaderMetrics: Enable or disable class loader metrics.
  • enableJvmGcMetrics: Enable or disable JVM garbage collection metrics.
  • enableJvmMemoryMetrics: Enable or disable JVM memory metrics.
  • enableJvmThreadMetrics: Enable or disable JVM thread metrics.
  • enableProcessorMetrics: Enable or disable processor metrics.
  • enableVertxMetrics: Enable or disable Vert.x metrics.
  • enabled: Global enable or disable for all metrics.
  • periodicMetricsSchedule: Set the periodic retrieval schedule for metrics from the database.
  • prometheus: Configuration for Prometheus metrics.
    • enabled: Enable or disable Prometheus metrics.
    • publishQuantiles: Set whether to publish quantiles.
    • endpoints: Array with endpoints to expose the Prometheus metrics on
      • httpConfigurationId: Id of entry in HTTP_CONFIGURATIONS - if not set (or null), the endpoint is exposed on all configured servers
      • path: The path to expose the metrics on (if not set, the default is /metrics)
      • authentication: If set, controls the authentication requirements for the endpoint (if not set, no authentication is enforced)
        • type: The type of authentication. Only basic is allowed.
        • username: The required username (plaintext, must not contain the character :)
        • password: The required password (plaintext, must not contain the character :)

boot.json

The configuration should be placed within the file boot.json, example (this is not the full configuration file, only the relevant sections are included):

{
    "metrics": {
        "commonTags": {
            "foo.bar": "bar foo",
            "applicationVersion": null
        },
        "elasticSearch": {
            "enabled": true
        },
        "prometheus": {
            "enabled": true
        }
    }
}

In the example above:

  • a new custom tag is added
  • the default application tag applicationVersion is removed
  • Elastic search is enabled using the default configuration
  • Prometheus is enabled using the default configuration

String replacement

Certain strings in the configuration can be expanded when the server starts:

  • {{SYS:APPLICATION_VERSION}} - The server version will be injected

Usage Notes

  • Both Elasticsearch and Prometheus can be used simultaneously to send metrics.
  • Prometheus endpoint is available at https://yourhost/metrics.
  • periodicMetricsSchedule should be synchronized with step time/scrape-interval for different systems.
  • Setting publishQuantiles to true will enable the publishing of quantiles
    • Note: publishQuantiles affects the method io.vertx.micrometer.VertxPrometheusOptions.setPublishQuantiles(boolean).
  • Different implementations (ex. Prometheus or Elasticsearch) have different naming conventions
    • In the documentation for PAS, a normalized naming convention is being used - it may need to be translated to the target implementation
    • For time-based metrics (ex. Timer, LongTaskTimer or TimeGauge), the internal accuracy is documented, however, the actual implementation may reformat it as suitable
Operations & Monitoring