From f7185ab43a98da1e31e50b4bfe9fd9d1aa3bddb5 Mon Sep 17 00:00:00 2001
From: Mayur Kale <mayurkale@google.com>
Date: Wed, 27 Nov 2019 08:50:17 -0800
Subject: [PATCH] chore: update metrics README (#490)

* chore: update metrics README

* chore: add npm badge

* chore: add todo

* chore: add WIP measures

* chore: minor

* chore: update metrics README

* fix: review comment

* fix: review comment
---
 packages/opentelemetry-metrics/README.md | 65 +++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/packages/opentelemetry-metrics/README.md b/packages/opentelemetry-metrics/README.md
index 7e5d8349245..4e3747eba75 100644
--- a/packages/opentelemetry-metrics/README.md
+++ b/packages/opentelemetry-metrics/README.md
@@ -1,10 +1,71 @@
 # OpenTelemetry Metrics SDK
 [![Gitter chat][gitter-image]][gitter-url]
+[![NPM Published Version][npm-img]][npm-url]
 [![dependencies][dependencies-image]][dependencies-url]
 [![devDependencies][devDependencies-image]][devDependencies-url]
 [![Apache License][license-image]][license-image]
 
-**Work in progress**
+OpenTelemetry metrics allow a user to collect data and export it to a metrics backend like [Prometheus](https://prometheus.io/).
+
+## Installation
+
+```bash
+npm install --save @opentelemetry/metrics
+```
+
+## Usage
+
+### 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.
+
+```js
+const { Meter } = require('@opentelemetry/metrics');
+
+// Initialize the Meter to capture measurements in various ways.
+const meter = new Meter();
+
+const counter = meter.createCounter('metric_name', {
+  labelKeys: ["pid"],
+  description: "Example of a counter"
+});
+
+const labels = meter.labels({ pid: process.pid });
+
+// Create a Handle associated with specified label values.
+const handle = counter.getHandle(labels);
+handle.add(10);
+```
+
+### Gauge
+Gauge metrics express a pre-calculated value. Generally, this kind of metric should be used when the metric cannot be expressed as a sum or because the measurement interval is arbitrary. Use this kind of metric when the measurement is not a quantity, and the sum and event count are not of interest. Gauges are defined as `Monotonic = false` by default, meaning that new values are permitted to make positive or negative changes to the gauge. There is no restriction on the sign of the input for gauges.
+
+```js
+const { Meter } = require('@opentelemetry/metrics');
+
+// Initialize the Meter to capture measurements in various ways.
+const meter = new Meter();
+
+const gauge = meter.createGauge('metric_name', {
+  labelKeys: ["pid"],
+  description: "Example of a gauge"
+});
+
+const labels = meter.labels({ pid: process.pid });
+
+// Create a Handle associated with specified label values.
+const handle = gauge.getHandle(labels);
+handle.set(10); // Set to 10
+```
+
+See [examples/prometheus](https://github.com/open-telemetry/opentelemetry-js/tree/master/examples/prometheus) for a short example.
+
+### Measure
+***Work in progress***
+
+## Useful links
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
+- For help or feedback on this project, join us on [gitter][gitter-url]
 
 ## License
 
@@ -18,3 +79,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-metrics
 [devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg?path=packages/opentelemetry-metrics
 [devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-metrics&type=dev
+[npm-url]: https://www.npmjs.com/package/@opentelemetry/metrics
+[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fmetrics.svg