Skip to content

Add remove method to synchronous instruments #4702

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
atoulme wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add remove method to synchronous instruments #4702

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
70dab0d
Add remove method to synchronous gauges, counters, updowncounters and…
atoulme Oct 25, 2025
646e391
Add to changelog and add status
atoulme Oct 25, 2025
159610d
Update specification/metrics/api.md
atoulme Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -598,6 +602,36 @@ 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.
Copy link
Member

@pellared pellared Nov 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Assuming that I do not miss something) This is not true. This does not registers the whole counter, but a data point (if I correctly remember/understand the terminology). Maybe it would be better to rename the operation to RemoveDataPoint so that we can add Remove in future that would unregister the whole instrument (and not only a given data point)?

The same comment applies to other instruments.

EDIT: I see similar comments like #4702 (comment) 😉

Copy link
Contributor

@dashpole dashpole Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree we aren't unregistering the entire counter. I don't like RemoveDataPoint, as DataPoint is not really an API concept. I would suggest phrasing this as "Unregister the attribute set".

Copy link
Member

@cijothomas cijothomas Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering what are the downsides of this achieving the effect of removing/unregistering the entire Counter? If any attribute sets are still relevant, they get added back next time something is reported for them.

Copy link
Contributor

@dashpole dashpole Dec 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it depends a bit on the implementation. If they all get new start times when they are added back, that would produce a lot of unnecessary resets for other attribute sets. If we send a "missing data point flag" to signal the end of a series, that would be even more disruptive for consumers. Even if we don't do either of those, it will probably cause a lot of churn for the SDK when it deletes series and then immediately re-creates most of them.


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)
Expand Down Expand Up @@ -827,6 +861,34 @@ 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
Expand Down Expand Up @@ -916,6 +978,29 @@ backgroundNoiseLevel.record(4.3, roomA);
backgroundNoiseLevel.record(2.5, roomB);
```

##### 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)
Expand Down Expand Up @@ -1157,6 +1242,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
Expand Down
Loading