Metrics

1 Introduction

Mendix supports reporting metrics through Micrometer.

The Metrics can be configured in the following ways:

• Metrics registries configuration – to configure the metrics supported by Mendix
• Application tags – to include tags in all the metrics in application level
• Microflow activities – to handle metrics in microflow activities
• Java API – to handle metrics using a Java API in a Java action
• Logging – to log metrics to a log node

2 Metrics Registries Configuration

Micrometer can send metrics to multiple registries. To configure micrometer for a specific registry, use the following syntax in runtime settings with the custom runtime setting name Metrics.Registries. See Runtime Customization for more information. The setting is in JSON format.

• Custom Runtime Setting – Name: Metrics.Registries

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[
  {
    "type": "<registry1>",
    "settings": { <settings> },
    "filters": [ <list-of-filters> ]
  },
  {
    "type": "<registry2>",
    "settings": { <settings> },
    "filters": [ <list-of-filters> ]
  },
  …
]

The details of each settings are listed below.

• type (mandatory) – the type of registry to use. Currently supported types are prometheus, jmx, influx, and statsd. Depending on the type of the registry the settings may vary.
• settings (conditional mandatory) – settings for the registry. Each registry has different settings depending upon the type specified. Follow the links below to see the settings for each type:
  • Prometheus
  • jmx
  • influx
  • statsd
• filters (optional) – instructions on which metrics to accept or deny. See the Filters section, below, for more information.

2.1 Settings

The following settings can be used, depending on the type of metrics being generated:

2.1.1 Prometheus

We do not support multiple Prometheus. When the Prometheus registry is set, it can be accessed through the /prometheus context path over the admin endpoint.

• step – the step size or reporting frequency to use.

Example 1

1
2
3
4
5
6
7
8

[
  {
    "type": "prometheus",
    "settings": {
      "step": "3m"
    }
  }
]

Example 2

1
2
3
4
5
6
7
8

[
  {
    "type": "prometheus",
    "settings": {
      "step": "P3Y6M4DT12H30M5S"
    }
  }
]

2.1.2 Jmx

• step – The step size or reporting frequency to use.
• domain – The Jmx domain to which to publish the metrics.

Example 1

1
2
3
4
5
6
7
8
9

[
  {
    "type": "jmx",
    "settings": {
      "step": "3m",
      "domain": "Mendix"
    }
  }
]

Example 2

1
2
3
4
5
6
7
8

[
  {
    "type": "jmx",
    "settings": {
      "step": "P3Y6M4DT12H30M5S"
    }
  }
]

2.1.3 Influx

• uri – the URI for the Influx back end.
• db – the database name to which to send the metrics.
• userName – the userName for authentication.
• password – the password for authentication.
• step – the step size or reporting frequency to use.
• enabled – set to true to enable the registry. This means you can switch the meter on and off while keeping the settings in the configuration.

Example 1

1
2
3
4
5
6
7
8
9

[
  {
    "type": "influx",
    "settings": {
      "userName": "mendix",
      "password": "MayBeThis**"
    }
  }
]

Example 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[
  {
    "type": "influx",
    "settings": {
      "uri": "http://mendix.influx.com",
      "db": "mx.metrics",
      "userName": "mendix",
      "password": "MayBeThis**",
      "step": "P2Y6M4DT12H21M5S"
    }
  }
]

2.1.4 StatsD

• flavor – specifies the variant of the StatsD protocol to use.
• host – the host name of the StatsD agent.
• port – the port used by the StatsD agent.
• step – the step size or reporting frequency to use.
• protocol – the protocol of the connection.
• enabled – set to true to enable the registry. This means you can switch the meter on and off while keeping the settings in the configuration.

Example 1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[
  {
    "type": "statsd",
    "settings": {
      "host": "mx.datadog.com",
      "port": "8181",
      "protocol": "TCP",
      "flavor": "TELEGRAF"
    }
  }
]

Example 2

1
2
3
4
5
6
7
8
9

[
  {
    "type": "statsd",
    "settings": {
      "flavor": "SYSDIG",
      "step": "3m"
    }
  }
]

2.2 Filters

Filters are optional, but can help in filtering metrics based on given criteria. Below is the syntax:

1
2
3

"filters" : [
  {"type" : "<filter-type>", "result" : "filter-result", "values": [ "<list-of-filter-values>"] }
]

• filter-type – the type of filter to apply. Currently we support the following:
  • nameStartsWith – matches the metric if its name begins with the given list-of-filter-values.
• filter-result – the desired result of applying the filter-type to the list-of-filter-values. Supported values are:
  • accept – metrics matching the criteria are passed to the registry
  • deny – metrics matching the criteria are not passed to the registry
• list-of-filter-values – a list of values used in the given filter type

Example 1

1
2
3
4
5
6
7
8
9

[
  {
    "type": "statsd",
    "settings": { "protocol": "TCP" },
    "filters": [
      { "type" : "nameStartsWith", "result" : "accept", "values" : ["app.", "employee.", "myapp."] }
    ]
  }
]

The above filter accepts metrics which starts with app., employee., or myapp..

Example 2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

[
  {
    "type": "influx",
    "settings": {
      "userName": "mendix",
      "password": "MayBeThis**"
    },
    "filters": [
      { "type" : "nameStartsWith", "result" : "deny", "values" : ["Unnamed.", "Invalid.", "Internal."] }
    ]
  }
]

The above filter discards metrics which start with Unnamed., Invalid., or Internal..

2.3 Notes

1. Filters also affect internal metrics used by Mendix. For example, metrics emitted by Mendix which start with mx..

2. If you have two metrics with the same name but one has additional tags, these are considered as different metrics. For example, metrics app.counter1 with tag "version" -> "1" and app.counter1 with no tag are different.

3. Filters are executed on a first come, first served basis. In other words, the first matching filter gets the priority. For example, take the filters defined below:

   1 2 3 4 5 6 7 8 9 10

   [ { "type": "statsd", "settings": { "protocol": "TCP" }, "filters": [ { "type" : "nameStartsWith", "result" : "accept", "values" : ["app."] }, { "type" : "nameStartsWith", "result" : "deny", "values" : ["app.others."] } ] } ]

   This example allows metrics like app.others.counter as they pass the first accept filter, nameStartsWith "app.". However, if you reverse the filters, app.others.counter would be denied, while app.somethingelse. would still be accepted.

   Ensure that more specific filters are defined before less specific ones so that they are applied correctly.

4. To accept only specific filters and deny all others, add a deny filter with the value "" as the last filter. For example, to accept only metrics starting with app.

   1 2 3 4 5 6 7 8 9 10

   [ { "type": "statsd", "settings": { "protocol": "TCP" }, "filters": [ { "type" : "nameStartsWith", "result" : "accept", "values" : ["app."] }, { "type" : "nameStartsWith", "result" : "deny", "values" : [""] } ] } ]

3 Application Tags

Common tags which should be reported by every metric can be specified using the Metrics.ApplicationTags setting. This setting should be in JSON format.

• Custom Runtime Setting – Name: Metrics.ApplicationTags

1
2
3
4

{
  "hostId": "7a3c0356-4dab-42ab-a139-87efb497f3e9",
  "environment": "prod"
}

4 Microflow Activities

You can use activities to provide custom metrics from your app. See Metrics Activities for information about these activities .

5 Java API

Micrometer metrics can be accessed through Mendix Runtime Java API as well inside Mendix. This can be achieved by using the custom runtime setting com.mendix.metrics.Type. This setting defaults to micrometer.

• Custom Runtime Setting – Name: com.mendix.metrics.Type
• Value: micrometer

5.1 Current Metrics and Usage

Currently supported metrics are counter, gauge, and timer. We support Bloch’s builder pattern to create the metrics and support Tag and Description which can be added to each metric.

To create the metrics,

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import com.mendix.metrics.Counter;
import com.mendix.core.Core;
…

// Create a counter
Counter counter1 = Core.metrics().createCounter("app.strikes")
                                .withTag("app", "myapp")
                                .withDescription("Metrics to count the strike outs")
                                .build();
Counter counter2 = Core.metrics().createCounter("app.count").build();

In the same way, we can also create a gauge and a timer using the createGauge and createTimer methods respectively.

The name must adhere to the following rules:

• The name can only contain alpha-numeric characters, dots or underscores.
• The name must start with a letter.
• The name cannot start with mx, because this prefix is reserved for Mendix internal metrics.
• The name is case-insensitive.

5.2 Deprecated usages

The following deprecated usages will be removed in the future releases,

1. Setting com.mendix.metrics.Type to logger and statsd is deprecated. You will get a warning message to advise you to start using the micrometer metric type.
2. The Core.metrics() Mendix Runtime Java API methods counter(), timer(), gauges(), and sets() are deprecated.

6 Logging

Metering-related log messages are sent to the Metering log node. If a registry is enabled, they will be reported with severity debug.

7 List of Metrics

The Runtime Server produces various metrics. Some of these metrics are controlled by Mendix: these are prefixed with mx.

Other metrics are produced by Micrometer, the library that is used for metrics. This library outputs metrics for other libraries that it recognizes, such as the Jetty server that is embedded in the Runtime Server. These additional Micrometer metrics are not under our control and might change.

7.1 Runtime Server Metrics

The Runtime Server produces the following metrics out-of-the-box:

7.2 Additional Metrics

7.2.1 System and Process Metrics

7.2.2 Java Virtual Machine Metrics

Refer to the Java Virtual Machine documentation for more details.

7.2.3 Jetty HTTP Server Metrics

7.2.4 Database Connection Pool Metrics

8 Read More

• Meter Concepts