From be2cd5e0ed1c30cbb6c52f15b06335897f5406a3 Mon Sep 17 00:00:00 2001 From: Mayur Kale Date: Fri, 15 Mar 2019 12:37:01 -0700 Subject: [PATCH] Add Resource, constantLabels and builder for java example --- metrics/Gauge.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/metrics/Gauge.md b/metrics/Gauge.md index 26deb2f..df07256 100644 --- a/metrics/Gauge.md +++ b/metrics/Gauge.md @@ -8,13 +8,14 @@ The `Gauge` values can be negative. This document describes the key types and th The value that is published for gauges is an instantaneous measurement of an `int64` or `double` value. This API is useful when you want to manually increase and decrease values as per service requirements. The following general operations MUST be provided by the API: -* Defining a `name`, `description`, `unit`, `labelKeys` and `constantLabels` which are fixed labels that always apply to a gauge. This should give back the gauge object to get or create time series, remove time series and clear all time series. +* Defining a `name`, `description`, `unit`, `labelKeys`, `resource` and `constantLabels` which are fixed labels that always apply to a gauge. This should give back the gauge object to get or create time series, remove time series and clear all time series. * `name`: a string describing the name of the metric, e.g. "vm_cpu_cycles" or "queue_size". Names MUST be unique within the library. It is recommended to use names compatible with the intended end usage. * `description`: a string describing the metric, e.g."Virtual cycles executed on VM". - * `unit`: a string describing the unit used for the metric. Follows the format described by + * `unit`: a string describing the unit used for the metric (default set to "1"). Follows the format described by [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html). * `labelKeys`: the list of the label keys to track different types of metric. - * `constantLabels`: the map of label keys and label values. + * `constantLabels`: the map of label keys and label values. The keys in `labelKeys` must not be present in this map. + * `resource`: the optional associated monitored resource information. * Add a new time series with label values, which returns a `Point` (which is part of the `TimeSeries`). Each point represents an instantaneous measurement of a varying gauge value. Each Gauge Metric has one or more time series for a single metric. * `labelValues`: the list of label values. The number of label values must be the same to that of the label keys. * The `Point` class should provide functionalities to manually increment/decrement values. Example: `add(long amt)`, `set(long value)`. @@ -29,8 +30,14 @@ private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry() List labelKeys = Arrays.asList(LabelKey.create("key1", "description")); List labelValues = Arrays.asList(LabelValue.create("queue1")); +LabelKey constantLabelKey = LabelKey.create("hostname", "hostname"); +LabelValue constantLabelValue = LabelValue.create("localhost"); -LongGauge gauge = metricRegistry.addLongGauge("queue_size", "The number of jobs", "1", labelKeys); +Map constantLabels = Collections.singletonMap(constantLabelKey, constantLabelValue); + +LongGauge gauge = metricRegistry.addLongGauge().toBuilder() + .setName("queue_size").setDescription("The number of jobs") + .setLabelKeys(labelKeys).setConstantLabels(constantLabels).build(); LongPoint point = gauge.getOrCreateTimeSeries(labelValues); void doSomeWork() { @@ -44,16 +51,17 @@ It is recommended to keep a reference of a point for manual operations instead o The value that is published for gauges is an instantaneous measurement of an `int64` or `double` value. This gauge is self sufficient once created, so users should never need to interact with it. The value of the gauge is observed from the `object` and a `callback function`. The callback function is invoked whenever metrics are collected, meaning the reported value is up-to-date. The implementation should keep a `WeakReference` to the object and it is the user's responsibility to manage the lifetime of the object. The following general operations MUST be provided by the API: -* Defining a `name`, `description`, `unit`, `labelKeys` and `constantLabels` which are fixed labels that always apply to a gauge. This should give back gauge object to add new time series, remove time series and clear all time series. +* Defining a `name`, `description`, `unit`, `labelKeys`, `resource` and `constantLabels` which are fixed labels that always apply to a gauge. This should give back gauge object to add new time series, remove time series and clear all time series. * `name`: a string describing the name of the metric, e.g. "vm_cpu_cycles". Names MUST be unique within the library. It is recommended to use names compatible with the intended end usage. * `description`: a string describing the metric, e.g."Virtual cycles executed on VM". - * `unit`: a string describing the unit used for the metric. Follows the format described by + * `unit`: a string describing the unit used for the metric (default set to "1"). Follows the format described by [Unified Code for Units of Measure](http://unitsofmeasure.org/ucum.html). * `labelKeys`: the list of the label keys to track different types of metric. - * `constantLabels`: the map of label keys and label values. + * `constantLabels`: the map of label keys and label values. The keys in `labelKeys` must not be present in this map. + * `resource`: the optional associated monitored resource information. * Add a new time series with label values, an `object` and a `callback function`. The number of label values must be the same to that of the label keys. * `labelValues`: the list of label values. The number of label values must be the same to that of the label keys. - * `obj`: the state object from which the function derives a measurement. + * `object`: the state object from which the function derives a measurement. * `function`: the callback function to be called. * Remove a single time series from the gauge metric, if it is present. * `labelValues`: the list of label values. @@ -65,10 +73,14 @@ private static final MetricRegistry metricRegistry = Metrics.getMetricRegistry() List labelKeys = Arrays.asList(LabelKey.create("key1", "description")); List labelValues = Arrays.asList(LabelValue.create("value1")); +LabelKey constantLabelKey = LabelKey.create("hostname", "hostname"); +LabelValue constantLabelValue = LabelValue.create("localhost"); + +Map constantLabels = Collections.singletonMap(constantLabelKey, constantLabelValue); -DerivedDoubleGauge gauge = metricRegistry.addDerivedDoubleGauge( - "vm_cpu_cycles", "Virtual cycles executed on VM", "1", labelKeys); -CpuInfo cpuInfo = new CpuInfo(); +DerivedDoubleGauge gauge = metricRegistry.addDerivedDoubleGauge().toBuilder() + .setName("vm_cpu_cycles").setDescription("Virtual cycles executed on VM") + .setLabelKeys(labelKeys).setConstantLabels(constantLabels).build(); gauge.createTimeSeries(labelValues, cpuInfo, new ToDoubleFunction() {