From 7d5f7f9e8acab045b19f722c59fee86cdd7b79de Mon Sep 17 00:00:00 2001 From: Oleg Zhurakousky Date: Fri, 23 Mar 2018 14:38:57 -0400 Subject: [PATCH] GH-1257 Updated Metrics documentation Resolves #1257 Resolves #1326 --- .../spring-cloud-stream-overview.adoc | 158 ++++++++---------- 1 file changed, 67 insertions(+), 91 deletions(-) diff --git a/spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc b/spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc index f7913b870..7e3a58a54 100644 --- a/spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc +++ b/spring-cloud-stream-core-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc @@ -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=`. -`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 + } + ] } ----