TOMEE-2405 - created examples/mp-metrics-histogram/README.adoc and added index-group MicroProfile
Project: http://git-wip-us.apache.org/repos/asf/tomee/repo Commit: http://git-wip-us.apache.org/repos/asf/tomee/commit/4d07c10f Tree: http://git-wip-us.apache.org/repos/asf/tomee/tree/4d07c10f Diff: http://git-wip-us.apache.org/repos/asf/tomee/diff/4d07c10f Branch: refs/heads/master Commit: 4d07c10fc431317acf6de25345a51d683524ce7a Parents: 81f7062 Author: CesarHernandezGt <[email protected]> Authored: Wed Dec 19 20:57:24 2018 -0600 Committer: CesarHernandezGt <[email protected]> Committed: Wed Dec 19 20:57:24 2018 -0600 ---------------------------------------------------------------------- examples/mp-metrics-histogram/README.adoc | 212 +++++++++++++++++++++++++ examples/mp-metrics-histogram/README.md | 182 --------------------- 2 files changed, 212 insertions(+), 182 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tomee/blob/4d07c10f/examples/mp-metrics-histogram/README.adoc ---------------------------------------------------------------------- diff --git a/examples/mp-metrics-histogram/README.adoc b/examples/mp-metrics-histogram/README.adoc new file mode 100644 index 0000000..f8b1ee3 --- /dev/null +++ b/examples/mp-metrics-histogram/README.adoc @@ -0,0 +1,212 @@ +:index-group: MicroProfile +:jbake-type: page +:jbake-status: published + +# Microprofile Metrics Histogram +This is an example on how to use microprofile metrics in TomEE. + +== Run the application: + +.... +mvn clean install tomee:run +.... + +Within the application, there is an enpoint that will give you a weather +histogram of the most recent New York City temperatures. + +== Request: + +.... +curl -X GET http://localhost:8080/mp-metrics-histogram/weather/histogram +.... + +== Response: + +.... +{ + "count":15, + "max":55, + "mean":44.4, + "min":27, + "p50":45.0, + "p75":46.0, + "p95":54.0, + "p98":54.0, + "p99":54.0, + "p999":54.0, + "stddev":7.0710678118654755, + "unit":"degrees F" +} +.... + +== Histogram Feature + +Microprofile metrics has a feature create a histogram of data. + +To use this feature, inject a MetricRegistry, register the Histogram, +and add data to the histogram as shown below. + +.... +@Inject +private MetricRegistry registry; + +@Inject +@Metric(name = "temperatures", description = "A histogram metrics example.", + displayName = "Histogram of Recent New York Temperatures") +private Histogram histogram; + +@Path("/histogram") +@GET +@Produces(MediaType.APPLICATION_JSON) +public Histogram getTemperatures() { + Metadata metadata = new Metadata("temperatures", MetricType.HISTOGRAM, "degrees F"); + metadata.setDescription("A histogram of recent New York temperatures."); + final int[] RECENT_NEW_YORK_TEMPS = { 46, 45, 50, 46, 45, 27, 30, 48, 55, 54, 45, 41, 45, 43, 46 }; + histogram = registry.histogram(metadata); + for(int temp : RECENT_NEW_YORK_TEMPS) { + histogram.update(temp); + } + return histogram; +} +.... + +There are some Histogram configurations defined in the @Metric +annotation: + +*String name* Optional. The name of the metric. If not explicitly given +the name of the annotated object is used. + +*String displayName* Optional. A human readable display name for +metadata. + +*String description* Optional. A description of the metric. + +*String[] tags* Optional. An array of Strings in the = format to supply +special tags to a metric. + +*boolean reusable* Denotes if a metric with a certain name can be +registered in more than one place. Does not apply to gauges or +histograms. + +=== For the histogram status: + +.... +GET http://localhost:8080/mp-metrics-histogram/weather/histogram/status +.... + +=== Reponse: + +.... + Here are the most recent New York City temperatures. +.... + +=== Expected Prometheus format: + +.... + # TYPE application:temperatures_degrees F summary histogram + # TYPE application:temperatures_degrees F_count histogram + application:temperatures_degrees F_count 15.0 + # TYPE application:temperatures_min_degrees F histogram + application:temperatures_min_degrees F 27.0 + # TYPE application:temperatures_max_degrees F histogram + application:temperatures_max_degrees F 55.0 + # TYPE application:temperatures_mean_degrees F histogram + application:temperatures_mean_degrees F 44.4 + # TYPE application:temperatures_stddev_degrees F histogram + application:temperatures_stddev_degrees F 7.0710678118654755 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.5"} 45.0 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.75"} 46.0 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.95"} 54.0 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.98"} 54.0 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.99"} 54.0 + # TYPE application:temperatures_degrees F histogram + application:temperatures_degrees F{quantile="0.999"} 54.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures summary histogram + # TYPE application:org_superbiz_histogram_weather_service_temperatures_count histogram + application:org_superbiz_histogram_weather_service_temperatures_count 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures_min histogram + application:org_superbiz_histogram_weather_service_temperatures_min 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures_max histogram + application:org_superbiz_histogram_weather_service_temperatures_max 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures_mean histogram + application:org_superbiz_histogram_weather_service_temperatures_mean NaN + # TYPE application:org_superbiz_histogram_weather_service_temperatures_stddev histogram + application:org_superbiz_histogram_weather_service_temperatures_stddev 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.5"} 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.75"} 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.95"} 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.98"} 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.99"} 0.0 + # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram + application:org_superbiz_histogram_weather_service_temperatures{quantile="0.999"} 0.0 +.... + +=== Request: + +.... +curl -X GET http://localhost:8080/mp-metrics-histogram/metrics/application +.... + +=== Response: + +.... +{ + "org.superbiz.histogram.WeatherService.temperatures": { + "count":0, + "max":0, + "min":0, + "p50":0.0, + "p75":0.0, + "p95":0.0, + "p98":0.0, + "p99":0.0, + "p999":0.0, + "stddev":0.0, + "unit":"none" + } +} +.... + +== Metric Metadata: + +A metric will have a metadata to provide information about it such as +displayName, description, tags, etc. + +=== Request: + +.... +curl -X OPTIONS http://localhost:8080/mp-metrics-histogram/metrics/application +.... + +=== Response: + +.... +{ + "org.superbiz.histogram.WeatherService.temperatures": { + "description": "A histogram metrics example.", + "displayName":"Histogram of Recent New York Temperatures", + "name":"org.superbiz.histogram.WeatherService.temperatures", + "reusable":false, + "tags":"", + "type":"histogram", + "typeRaw":"HISTOGRAM", + "unit":"none" + } +} +.... + +=== Test the application: + +.... +mvn test +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/4d07c10f/examples/mp-metrics-histogram/README.md ---------------------------------------------------------------------- diff --git a/examples/mp-metrics-histogram/README.md b/examples/mp-metrics-histogram/README.md deleted file mode 100644 index c948cd5..0000000 --- a/examples/mp-metrics-histogram/README.md +++ /dev/null @@ -1,182 +0,0 @@ -index-group=Histogram -type=page -status=published -~~~~~~ -# Microprofile Metrics -This is an example on how to use microprofile metrics in TomEE. - -##### Run the application: - - mvn clean install tomee:run - -Within the application, there is an enpoint that will give you a weather histogram of the most recent New York City temperatures. - -##### Request: - - curl -X GET http://localhost:8080/mp-metrics-histogram/weather/histogram - -##### Response: - - { - "count":15, - "max":55, - "mean":44.4, - "min":27, - "p50":45.0, - "p75":46.0, - "p95":54.0, - "p98":54.0, - "p99":54.0, - "p999":54.0, - "stddev":7.0710678118654755, - "unit":"degrees F" - } - -#### Histogram Feature -Microprofile metrics has a feature create a histogram of data. - -To use this feature, inject a MetricRegistry, register the Histogram, and add data to the histogram as shown below. - - @Inject - private MetricRegistry registry; - - @Inject - @Metric(name = "temperatures", description = "A histogram metrics example.", - displayName = "Histogram of Recent New York Temperatures") - private Histogram histogram; - - @Path("/histogram") - @GET - @Produces(MediaType.APPLICATION_JSON) - public Histogram getTemperatures() { - Metadata metadata = new Metadata("temperatures", MetricType.HISTOGRAM, "degrees F"); - metadata.setDescription("A histogram of recent New York temperatures."); - final int[] RECENT_NEW_YORK_TEMPS = { 46, 45, 50, 46, 45, 27, 30, 48, 55, 54, 45, 41, 45, 43, 46 }; - histogram = registry.histogram(metadata); - for(int temp : RECENT_NEW_YORK_TEMPS) { - histogram.update(temp); - } - return histogram; - } - -There are some Histogram configurations defined in the @Metric annotation: - -**String name** -Optional. The name of the metric. If not explicitly given the name of the annotated object is used. - -**String displayName** -Optional. A human readable display name for metadata. - -**String description** -Optional. A description of the metric. - -**String[] tags** -Optional. An array of Strings in the <key>=<value> format to supply special tags to a metric. - -**boolean reusable** -Denotes if a metric with a certain name can be registered in more than one place. Does not apply to gauges or histograms. - -##### For the histogram status: - - GET http://localhost:8080/mp-metrics-histogram/weather/histogram/status - -##### Reponse: - - Here are the most recent New York City temperatures. - -##### Expected Prometheus format: - - # TYPE application:temperatures_degrees F summary histogram - # TYPE application:temperatures_degrees F_count histogram - application:temperatures_degrees F_count 15.0 - # TYPE application:temperatures_min_degrees F histogram - application:temperatures_min_degrees F 27.0 - # TYPE application:temperatures_max_degrees F histogram - application:temperatures_max_degrees F 55.0 - # TYPE application:temperatures_mean_degrees F histogram - application:temperatures_mean_degrees F 44.4 - # TYPE application:temperatures_stddev_degrees F histogram - application:temperatures_stddev_degrees F 7.0710678118654755 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.5"} 45.0 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.75"} 46.0 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.95"} 54.0 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.98"} 54.0 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.99"} 54.0 - # TYPE application:temperatures_degrees F histogram - application:temperatures_degrees F{quantile="0.999"} 54.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures summary histogram - # TYPE application:org_superbiz_histogram_weather_service_temperatures_count histogram - application:org_superbiz_histogram_weather_service_temperatures_count 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures_min histogram - application:org_superbiz_histogram_weather_service_temperatures_min 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures_max histogram - application:org_superbiz_histogram_weather_service_temperatures_max 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures_mean histogram - application:org_superbiz_histogram_weather_service_temperatures_mean NaN - # TYPE application:org_superbiz_histogram_weather_service_temperatures_stddev histogram - application:org_superbiz_histogram_weather_service_temperatures_stddev 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.5"} 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.75"} 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.95"} 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.98"} 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.99"} 0.0 - # TYPE application:org_superbiz_histogram_weather_service_temperatures histogram - application:org_superbiz_histogram_weather_service_temperatures{quantile="0.999"} 0.0 - -##### Request: - - curl -X GET http://localhost:8080/mp-metrics-histogram/metrics/application - -##### Response: - - { - "org.superbiz.histogram.WeatherService.temperatures": { - "count":0, - "max":0, - "min":0, - "p50":0.0, - "p75":0.0, - "p95":0.0, - "p98":0.0, - "p99":0.0, - "p999":0.0, - "stddev":0.0, - "unit":"none" - } - } - -#### Metric Metadata: -A metric will have a metadata to provide information about it such as displayName, description, tags, etc. - -##### Request: - - curl -X OPTIONS http://localhost:8080/mp-metrics-histogram/metrics/application - -##### Response: - - { - "org.superbiz.histogram.WeatherService.temperatures": { - "description": "A histogram metrics example.", - "displayName":"Histogram of Recent New York Temperatures", - "name":"org.superbiz.histogram.WeatherService.temperatures", - "reusable":false, - "tags":"", - "type":"histogram", - "typeRaw":"HISTOGRAM", - "unit":"none" - } - } - -##### Test the application: - - mvn test
