chore: update metrics example with UpDownCounter (open-telemetry#1239)

* chore: update metrics example with UpDownCounter

* chore: update getting-started

* chore: update README

* fix: lint

* Update packages/opentelemetry-metrics/README.md

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>

* Update packages/opentelemetry-metrics/README.md

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>

Co-authored-by: Daniel Dyla <dyladan@users.noreply.github.com>

examples/prometheus/README.md

@@ -48,7 +48,8 @@ prometheus --config.file=prometheus.yml
 
 If you are using the default configurations, the prometheus client will be available at <http://localhost:9090>
 
-<p align="center"><img src="images/prom-ui.png?raw=true"/></p>
+<p align="center"><img src="images/prom-counter.png?raw=true"/></p>
+<p align="center"><img src="images/prom-updowncounter.png?raw=true"/></p>
 
 ## Useful links
 

examples/prometheus/index.js

@@ -19,21 +19,17 @@ const meter = new MeterProvider({
   interval: 1000,
 }).getMeter('example-prometheus');
 
-// Monotonic counters can only be increased.
-const monotonicCounter = meter.createCounter('monotonic_counter', {
-  monotonic: true,
-  description: 'Example of a monotonic counter',
+const requestCounter = meter.createCounter('requests', {
+  description: 'Example of a Counter',
 });
 
-// Non-monotonic counters can be increased or decreased.
-const nonMonotonicCounter = meter.createCounter('non_monotonic_counter', {
-  monotonic: false,
-  description: 'Example of a non-monotonic counter',
+const upDownCounter = meter.createUpDownCounter('test_up_down_counter', {
+  description: 'Example of a UpDownCounter',
 });
 
-const labels = { pid: process.pid };
+const labels = { pid: process.pid, environment: 'staging' };
 
 setInterval(() => {
-  monotonicCounter.bind(labels).add(1);
-  nonMonotonicCounter.bind(labels).add(Math.random() > 0.5 ? 1 : -1);
+  requestCounter.bind(labels).add(1);
+  upDownCounter.bind(labels).add(Math.random() > 0.5 ? 1 : -1);
 }, 1000);

getting-started/README.md

@@ -253,7 +253,6 @@ const { MeterProvider } = require('@opentelemetry/metrics');
 const meter = new MeterProvider().getMeter('your-meter-name');
 
 const requestCount = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 
@@ -323,7 +322,6 @@ const meter = new MeterProvider({
 }).getMeter('your-meter-name');
 
 const requestCount = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 

getting-started/monitored-example/monitoring.js

@@ -20,7 +20,6 @@ const meter = new MeterProvider({
 }).getMeter('example-monitored');
 
 const requestCount = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 

getting-started/ts-example/README.md

@@ -252,7 +252,6 @@ import { Metric, BoundCounter } from '@opentelemetry/api';
 const meter = new MeterProvider().getMeter('your-meter-name');
 
 const requestCount: Metric<BoundCounter> = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 
@@ -321,7 +320,6 @@ const meter = new MeterProvider({
 }).getMeter('your-meter-name');
 
 const requestCount: Metric<BoundCounter> = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 

getting-started/ts-example/monitoring.ts

@@ -19,7 +19,6 @@ const meter = new MeterProvider({
 }).getMeter('example-ts');
 
 const requestCount: Metric<BoundCounter> = meter.createCounter("requests", {
-  monotonic: true,
   description: "Count all incoming requests"
 });
 

packages/opentelemetry-metrics/README.md

@@ -18,7 +18,14 @@ npm install --save @opentelemetry/metrics
 
 ### Counter
 
-Choose this kind of metric when the value is a quantity, the sum is of primary interest, and the event count and value distribution are not of primary interest. Counters are defined as `Monotonic = true` by default, meaning that positive values are expected.
+Choose this kind of metric when the value is a quantity, the sum is of primary interest, and the event count and value distribution are not of primary interest. It is restricted to non-negative increments.
+Example uses for Counter:
+
+- count the number of bytes received
+- count the number of requests completed
+- count the number of accounts created
+- count the number of checkpoints run
+- count the number of 5xx errors.
 
 ```js
 const { MeterProvider } = require('@opentelemetry/metrics');
@@ -38,6 +45,35 @@ boundCounter.add(10);
 
 ```
 
+### UpDownCounter
+
+`UpDownCounter` is similar to `Counter` except that it supports negative increments. It is generally useful for capturing changes in an amount of resources used, or any quantity that rises and falls during a request.
+
+Example uses for UpDownCounter:
+
+- count the number of active requests
+- count memory in use by instrumenting new and delete
+- count queue size by instrumenting enqueue and dequeue
+- count semaphore up and down operations
+
+```js
+const { MeterProvider } = require('@opentelemetry/metrics');
+
+// Initialize the Meter to capture measurements in various ways.
+const meter = new MeterProvider().getMeter('your-meter-name');
+
+const counter = meter.createUpDownCounter('metric_name', {
+  description: 'Example of a UpDownCounter'
+});
+
+const labels = { pid: process.pid };
+
+// Create a BoundInstrument associated with specified label values.
+const boundCounter = counter.bind(labels);
+boundCounter.add(Math.random() > 0.5 ? 1 : -1);
+
+```
+
 ### Observable
 
 Choose this kind of metric when only last value is important without worry about aggregation