SpringCloud/spring-cloud-stream
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

GH-1257 Updated Metrics documentation

Browse Source 
Resolves #1257
Resolves #1326
This commit is contained in:
Oleg Zhurakousky
2018-03-23 14:38:57 -04:00
parent 60fc252b1e
commit 7d5f7f9e8a
1 changed files with 67 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc
View File

@@ -2269,12 +2269,21 @@ It is registered under the name of `binders` and can be enabled or disabled by s
[[spring-cloud-stream-overview-metrics-emitter]]
== Metrics Emitter
Spring Cloud Stream provides a module called `spring-cloud-stream-metrics` that can be used to emit any available metric from the https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html[Spring Boot metrics endpoint] to a named channel.
This module lets operators collect metrics from stream applications without relying on polling their endpoints.
Spring Boot Actuator provides dependency management and auto-configuration for https://micrometer.io/[Micrometer], an application metrics
facade that supports numerous https://docs.spring.io/spring-boot/docs/2.0.0.RELEASE/reference/htmlsingle/#production-ready-metrics[monitoring systems].
The module is activated when you set the destination name for metrics binding -- for example, `spring.cloud.stream.bindings.applicationMetrics.destination=<DESTINATION_NAME>`.
`applicationMetrics` can be configured in a similar fashion to any other producer binding.
The default `contentType` setting of `applicationMetrics` is `application/json`.
Spring Cloud Stream provides support for emitting any available micrometer-based metrics to a binding destination, allowing for periodic
collection of metric data from stream applications without relying on polling individual endpoints.
Metrics Emitter is activated by defining the `spring.cloud.stream.bindings.applicationMetrics.destination` property,
which specifies the name of the binding destination used by the current binder to publish metric messages.
For example:
[source,java]
----
spring.cloud.stream.bindings.applicationMetrics.destination=myMetricDestination
----
The preceding example instructs the binder to bind to `myMetricDestination` (that is, Rabbit exchange, Kafka topic, and others).
The following properties can be used for customizing the emission of metrics:
@@ -2283,108 +2292,75 @@ The name of the metric being emitted. Should be a unique value per application.
+
Default: `${spring.application.name:${vcap.application.name:${spring.config.name:application}}}`
+
spring.cloud.stream.metrics.prefix::
Prefix string to be prepended to the metrics key.
+
Default: ``
+
spring.cloud.stream.metrics.properties::
As with the `includes` option, it allows white listing application properties that are added to the metrics payload
Allows white listing application properties that are added to the metrics payload
+
Default: null.
+
spring.cloud.stream.metrics.meter-filter::
Pattern to control the 'meters' one wants to capture.
For example, specifying `spring.integration.*` captures metric information for meters whose name starts with `spring.integration.`
+
Default: all 'meters' are captured.
+
spring.cloud.stream.metrics.schedule-interval::
Interval to control the rate of publishing metric data.
+
Default: 1 min
A detailed overview of the metrics export process can be found in the https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html#production-ready-metric-writers[Spring Boot reference documentation].
Spring Cloud Stream provides a metric exporter named `application` that can be configured through regular https://github.com/spring-projects/spring-boot/blob/1.5.x/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/TriggerProperties.java[Spring Boot metrics configuration properties].
The exporter can be configured either by using the global Spring Boot configuration settings for exporters or by using exporter-specific properties.
For using the global configuration settings, the properties should be prefixed by `spring.metric.export` (for example: `spring.metric.export.includes=integration+++**+++`).
These configuration options apply to all exporters (unless they have been configured differently).
Alternatively, if you intend to use configuration settings that differ from the other exporters (for example, for restricting the number of metrics published), the Spring Cloud Stream-provided metrics exporter can be configured by using the prefix `spring.metrics.export.triggers.application` (for example, `spring.metrics.export.triggers.application.includes=integration+++**+++`).
NOTE: Due to Spring Boot's https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-relaxed-binding[relaxed binding], the value of a included property can be slightly different than the original value.
As a rule of thumb, the metric exporter tries to normalize all the properties in a consistent format by using the dot notation (for example, `JAVA_HOME` becomes `java.home`).
The goal of normalization is to make downstream consumers of those metrics capable of receiving property names consistently, regardless of how they are set on the monitored application (for example, `--spring.application.name` or `SPRING_APPLICATION_NAME` always yields `spring.application.name`).
Consider the following command:
Consider the following:
[source,bash]
----
java -jar time-source.jar \
--spring.cloud.stream.bindings.applicationMetrics.destination=someMetrics \
--spring.cloud.stream.metrics.properties=spring.application** \
--spring.metrics.export.includes=integration.channel.input**,integration.channel.output**
--spring.cloud.stream.metrics.meter-filter=spring.integration.*
----
The following example shows data published to the channel in JSON format by the preceding command:
The following example shows data published to the binding destination as a result of the preceding command:
[source,javascript]
----
{
"name":"time-source",
"metrics":[
{
"name":"integration.channel.output.errorRate.mean",
"value":0.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.errorRate.max",
"value":0.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.errorRate.min",
"value":0.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.errorRate.stdev",
"value":0.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.errorRate.count",
"value":0.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendCount",
"value":6.0,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendRate.mean",
"value":0.994885872292989,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendRate.max",
"value":1.006247080013156,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendRate.min",
"value":1.0012035220116378,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendRate.stdev",
"value":6.505181111084848E-4,
"timestamp":"2017-04-11T16:56:35.790Z"
},
{
"name":"integration.channel.output.sendRate.count",
"value":6.0,
"timestamp":"2017-04-11T16:56:35.790Z"
}
],
"createdTime":"2017-04-11T20:56:35.790Z",
"properties":{
"spring.application.name":"time-source",
"spring.application.index":"0"
}
"name": "application",
"createdTime": "2018-03-23T14:48:12.700Z",
"properties": {
},
"metrics": [
{
"id": {
"name": "spring.integration.send",
"tags": [
{
"key": "exception",
"value": "none"
},
{
"key": "name",
"value": "input"
},
{
"key": "result",
"value": "success"
},
{
"key": "type",
"value": "channel"
}
],
"type": "TIMER",
"description": "Send processing time",
"baseUnit": "milliseconds"
},
"timestamp": "2018-03-23T14:48:12.697Z",
"sum": 130.340546,
"count": 6,
"mean": 21.72342433333333,
"upper": 116.176299,
"total": 130.340546
}
]
}
----