diff --git a/CHANGELOG.md b/CHANGELOG.md index bc7e1c7853e..996e96da701 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. ### Metrics +- Development: Define `remove` operations for synchronous metric instruments. [#4702](https://github.com/open-telemetry/opentelemetry-specification/pulls/4702) + ### Logs ### Baggage diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 4b1d9b00a64..fae3086202c 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -35,6 +35,7 @@ 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) @@ -42,10 +43,12 @@ weight: 1 + [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) @@ -53,6 +56,7 @@ weight: 1 + [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,38 @@ counterPowerUsed.Add(13.5, new PowerConsumption { customer = "Tom" }); counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true)); ``` +##### Remove + +Status: Development + +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 +863,36 @@ httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "h httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" }); ``` +##### Remove + +Status: Development + +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 +982,31 @@ backgroundNoiseLevel.record(4.3, roomA); backgroundNoiseLevel.record(2.5, roomB); ``` +##### Remove + +Status: Development + +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 +1248,34 @@ customersInStore.Add(1, ("account.type", "commercial")); customersInStore.Add(-1, new Account { Type = "residential" }); ``` +##### Remove + +Status: Development + +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