Configuring Metrics Reporting
The ThingWorx Azure IoT Hub Connector uses
dropwizard/codahale to collect metrics. By default, collection of metrics is enabled.
This topic explains how to configure metrics to report to various output streams. You can output to the following destinations:
• SLF4J — The SLF4J reporter outputs a plain text version of the metrics. The output file and the format of the data is controlled by a Logback configuration that coincides with the logger named in the reporter section.
• Graphite API-based endpoint (like InfluxDB) — The group name of this metrics reporter section is called graphite. Define the frequency of collecting metrics and the endpoints to send the data to. This group can be enabled or disabled in isolation.
• The Console — The data is output to the console of the machine that is running the connection server/adapter. When configuring this option, you also have the option to write to a file at the same time.
• *.csv File — Each metric is written to a separate file. Potentially, 70 files may be generated.
Metrics configuration defines a set of one or more reporters that will receive metrics data, at a defined interval. The system outputs metrics data at every interval to all defined reporters. Each reporter can have its own interval defined (period_in_seconds property).
To change the default settings, you need to add the metrics group to your configuration file for the Azure IoT Hub Connector, define the reporters (where to send metrics), and make the necessary changes to the properties.
For each metrics reporting feature that you want to use, you need to add the appropriate group, enable it, and set properties.
1. In your configuration file (azure-iot.conf), if you do not have the cx-server.metrics group, add it as shown here:
cx-server
metrics {
enabled = true
Make sure that the enabled property is set to true.
2. To define where you want to output metrics, configure the reporters groups:
◦ To configure metrics to be sent to SLF4J, locate the reporters.slf4j group, shown here:
cx_server
metrics {
enabled = true
reporters {
slf4j {
enabled = false
logger = "metrics"
period_in_seconds = 20
}
}
}
To configure the SLF4J destination, set the properties:
1. enabled — Change the value to true.
2. logger — Set the value to be the named logger that you have specified in your SLF4J logback.xml file.
3. period_in_seconds — Set the number of seconds between each report of metrics. The default interval is 20 seconds.
◦ To configure all metrics to be sent to a Graphite API-based endpoint (InfluxDB), locate the reporters.graphite group, which is just below the slf4j group, as shown here:
cx-server
metrics {
enabled = true
reporters {
slf4j {
enabled = false
logger = "metrics"
period_in_seconds = 20
}
graphite {
enabled = false
period_in_seconds = 5
endpoints = [{
host = "localhost"
port = 2003
}
]
}
}
}
To configure the Graphite API-based endpoint (InfluxDB) option, set the properties of the graphite group and the graphite.endpoints sub-group:
1. enabled — Change the value to true.
2. period_in_seconds — Change the number of seconds between each report of metrics, if desired. The default interval is 5 seconds.
3. endpoints.host — Specify the host name or IP address of the Graphite collector host machine (the InfluxDB host).
4. endpoints.port — Specify the number of the port that the collector is listening on for metric data. The default port is 2003.
◦ You can also configure metrics to be sent to the console of the machine where the Azure IoT Hub Connector is running by adding the console group and properties to your configuration file (under the reporters group). It should be at the same level as the slf4j and graphite groups. The example below shows the level without the other two groups:
cx-server
metrics {
enabled = true
reporters {
console {
enabled = true
period_in_seconds = 20
#Defaults to STDOUT
outfile = "./connection-server_metrics.out"
}
}
}
To configure the console option (and optionally write to a file), set these properties:
1. enabled — Change the value to true.
2. period_in_seconds — Specify the number of seconds between each report of metrics. The default interval is 20 seconds.
3. Optionally, uncomment the outfile line and specify the location where you want to write the output. Note that relative paths are relative to the current working directory.
If this group is last in the reporters, metrics, and cx-server groups, be sure to add the closing curly braces (if not already present).
◦ To configure all metrics to be sent to a *.csv file, add the csv group to your configuration file (under the reporters group, at the same level as the slf4j and graphite groups). The following example shows this group without the other groups:
metrics {
enabled = true
reporters {
csv {
enabled = false
period_in_seconds = 20
outdir = "./connection-server_metrics_csvs"
}
}
}
To configure the csv option, set these properties:
1. enabled — Change the value to true.
2. period_in_seconds — Specify the number of seconds between each report of metrics. The default interval is 20 seconds. Keep in mind that the csv reporter creates one file per metric (approximately 70 files).
3. outdir — Specify the directory where you want to save the csv files.
You can use relative or absolute paths for the location. Relative paths are relative to the current working directory. The Connector will create this directory if it can. If not, a warning is written to the log and this reporter is disabled.
Be sure that all the groups are closed properly.
3. Save the configuration file.
4. As long as you have saved the configuration file, close it.
7. This step depends on whether you have previously started the Azure IoT Connector:
◦ Previously started: Restart it for these configuration changes to take effect.