Add remove method to synchronous gauges, counters, updowncounters and histograms

Author: atoulme

specification/metrics/api.md

@@ -35,24 +35,28 @@ weight: 1
     + [Counter creation](#counter-creation)
     + [Counter operations](#counter-operations)
       - [Add](#add)
+      - [Remove](#remove)
   * [Asynchronous Counter](#asynchronous-counter)
     + [Asynchronous Counter creation](#asynchronous-counter-creation)
     + [Asynchronous Counter operations](#asynchronous-counter-operations)
   * [Histogram](#histogram)
     + [Histogram creation](#histogram-creation)
     + [Histogram operations](#histogram-operations)
       - [Record](#record)
+      - [Remove](#remove-1)
   * [Gauge](#gauge)
     + [Gauge creation](#gauge-creation)
     + [Gauge operations](#gauge-operations)
       - [Record](#record-1)
+      - [Remove](#remove-2)
   * [Asynchronous Gauge](#asynchronous-gauge)
     + [Asynchronous Gauge creation](#asynchronous-gauge-creation)
     + [Asynchronous Gauge operations](#asynchronous-gauge-operations)
   * [UpDownCounter](#updowncounter)
     + [UpDownCounter creation](#updowncounter-creation)
     + [UpDownCounter operations](#updowncounter-operations)
       - [Add](#add-1)
+      - [Remove](#remove-3)
   * [Asynchronous UpDownCounter](#asynchronous-updowncounter)
     + [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
     + [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
@@ -598,6 +602,37 @@ counterPowerUsed.Add(13.5, new PowerConsumption { customer = "Tom" });
 counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true));
 ```
 
+##### Remove
+
+Unregister the Counter. It will no longer be reported.
+
+This API SHOULD NOT return a value (it MAY return a dummy value if required by
+certain programming languages or systems, for example `null`, `undefined`).
+
+This API MUST accept the following parameter:
+
+* [Attributes](../common/README.md#attribute) to identify the Counter.
+
+  Users can provide attributes to identify the Counter. 
+  This API MUST be structured to accept a variable number of attributes, including none.
+
+
+```python
+# Python
+
+exception_counter.remove({"exception_type": "IOError", "handled_by_user": True})
+exception_counter.remove(exception_type="IOError", handled_by_user=True)
+```
+
+```csharp
+// C#
+
+counterExceptions.Remove(("exception_type", "FileLoadException"), ("handled_by_user", true));
+
+counterPowerUsed.Remove(new PowerConsumption { customer = "Tom" });
+counterPowerUsed.Remove(new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true));
+```
+
 ### Asynchronous Counter
 
 Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument-api)
@@ -827,6 +862,35 @@ httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "h
 httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" });
 ```
 
+##### Remove
+
+Unregister the Histogram. It will no longer be reported.
+
+This API SHOULD NOT return a value (it MAY return a dummy value if required by
+certain programming languages or systems, for example `null`, `undefined`).
+
+This API MUST accept the following parameter:
+
+* [Attributes](../common/README.md#attribute) to identify the Histogram.
+
+  Users can provide attributes to identify the Histogram.
+  This API MUST be structured to accept a variable number of attributes, including none.
+
+
+```python
+# Python
+
+http_server_duration.Remove({"http.request.method": "POST", "url.scheme": "https"})
+http_server_duration.Remove(http_method="GET", http_scheme="http")
+```
+
+```csharp
+// C#
+
+httpServerDuration.Remove(("http.request.method", "POST"), ("url.scheme", "https"));
+httpServerDuration.Remove(new HttpRequestAttributes { method = "GET", scheme = "http" });
+```
+
 ### Gauge
 
 `Gauge` is a [synchronous Instrument](#synchronous-instrument-api) which can be
@@ -916,6 +980,29 @@ backgroundNoiseLevel.record(4.3, roomA);
 backgroundNoiseLevel.record(2.5, roomB);
 ```
 
+##### <a name="remove_gauge"></a>Remove
+
+Unregister the Gauge. It will no longer be reported.
+
+This API SHOULD NOT return a value (it MAY return a dummy value if required by
+certain programming languages or systems, for example `null`, `undefined`).
+
+This API MUST accept the following parameter:
+
+* [Attributes](../common/README.md#attribute) to identify the Gauge.
+
+  Users can provide attributes to identify the Gauge.
+  This API MUST be structured to accept a variable number of attributes, including none.
+
+```java
+// Java
+Attributes roomA = Attributes.builder().put("room.id", "Rack A");
+Attributes roomB = Attributes.builder().put("room.id", "Rack B");
+
+backgroundNoiseLevel.remove(roomA);
+backgroundNoiseLevel.remove(roomB);
+```
+
 ### Asynchronous Gauge
 
 Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument-api)
@@ -1157,6 +1244,32 @@ customersInStore.Add(1, ("account.type", "commercial"));
 customersInStore.Add(-1, new Account { Type = "residential" });
 ```
 
+##### Remove
+
+Unregister the UpDownCounter. It will no longer be reported.
+
+This API SHOULD NOT return a value (it MAY return a dummy value if required by
+certain programming languages or systems, for example `null`, `undefined`).
+
+This API MUST accept the following parameter:
+
+* [Attributes](../common/README.md#attribute) to identify the UpDownCounter.
+
+  Users can provide attributes to identify the UpDownCounter.
+  This API MUST be structured to accept a variable number of attributes, including none.
+
+```python
+# Python
+customers_in_store.remove({"account.type": "commercial"})
+customers_in_store.remove(account_type="residential")
+```
+
+```csharp
+// C#
+customersInStore.Remove(("account.type", "commercial"));
+customersInStore.Remove(new Account { Type = "residential" });
+```
+
 ### Asynchronous UpDownCounter
 
 Asynchronous UpDownCounter is an [asynchronous