Skip to content

Add finish 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 7 commits into
base: main
Choose a base branch
from
+148 −0
Open

Add finish method to synchronous instruments #4702

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0ebd7a5
Add remove method to synchronous gauges, counters, updowncounters and…
atoulme Oct 25, 2025
23239af
Add to changelog and add status
atoulme Oct 25, 2025
d0c0299
Update specification/metrics/api.md
atoulme Dec 5, 2025
6fa9f8c
code review
atoulme Dec 13, 2025
35fefda
start adding to sdk
atoulme Dec 15, 2025
bb7741b
Merge branch 'main' into add_remove
atoulme Mar 17, 2026
6690172
fixup
atoulme Mar 17, 2026
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
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ release.

### Metrics

- Development: Define `finish` operations for synchronous metric instruments.
([#4702](https://github.com/open-telemetry/opentelemetry-specification/pulls/4702))

### Logs

### Baggage
Expand Down
137 changes: 137 additions & 0 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,28 +31,33 @@ weight: 1
- [Asynchronous Instrument API](#asynchronous-instrument-api)
* [General operations](#general-operations)
+ [Enabled](#enabled)
+ [Finish](#finish)
* [Counter](#counter)
+ [Counter creation](#counter-creation)
+ [Counter operations](#counter-operations)
- [Add](#add)
- [Finish](#finish-1)
* [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)
- [Finish](#finish-2)
* [Gauge](#gauge)
+ [Gauge creation](#gauge-creation)
+ [Gauge operations](#gauge-operations)
- [Record](#record-1)
- [Finish](#finish-3)
* [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)
- [Finish](#finish-4)
* [Asynchronous UpDownCounter](#asynchronous-updowncounter)
+ [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
+ [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
Expand Down Expand Up @@ -475,6 +480,7 @@ or something else).
All [synchronous instruments](#synchronous-instrument-api) SHOULD provide functions to:

* [Report if instrument is `Enabled`](#enabled)
* [Finish the reporting of a set of attributes](#finish)

#### Enabled

Expand All @@ -494,6 +500,22 @@ The returned value is not always static, it can change over time. The API
SHOULD be documented that instrumentation authors needs to call this API each
time they record a measurement to ensure they have the most up-to-date response.

#### Finish

**Status**: [Development](../document-status.md)

To stop reporting attribute sets which are no longer used, [synchronous Instruments](#synchronous-instrument-api) SHOULD provide this `Finish` API.

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 Instrument.
Copy link
Copy Markdown
Contributor

@dashpole dashpole Mar 17, 2026

Choose a reason for hiding this comment

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

The instrument isn't identified by the attributes. I would consider "time series" or something similar. You also say this below. This also applies to other Finish function definition.

Copy link
Copy Markdown
Contributor

@dashpole dashpole Mar 17, 2026

Choose a reason for hiding this comment

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

I think we should change this to be able to delete one or more timeseries by treating attributes that are not provided to this as matching. There are a few reasons:

  • I can easily delete all timeseries on an instrument by providing no attributes
  • As a user, I don't have to keep track of every attribute that i've ever provided to the API. For example, if my HTTP server dynamically creates and deletes routes over time, I would like to be able to Finish all timeseries associated with a particular http.route without needing to enumerate all of the status codes it has ever served.
  • This would interact much better with filtering. If, for example, I was filtering out all attributes except for http.route on my server metrics, it isn't clear if the SDK should Finish the aggregation with http.route=foo if I call Finish(http.route=foo, http.response.status_code=200, ...). Was my intent to delete the entire route? Was it to only delete the portion that has status code 200? If, instead, users of the API pass attributes where they want all aggregations containing those attributes to be deleted, the previous example would not delete anything. If I instead called Finish(http.route=foo), only then would the entire route be deleted.

Copy link
Copy Markdown
Member

@jack-berg jack-berg Mar 30, 2026

Choose a reason for hiding this comment

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

Yes. Why not the proposed predicate solution?

I can't find any comments which indicate there are problems / critiques with it.

Copy link
Copy Markdown
Contributor

@dashpole dashpole Mar 31, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Ah, sorry. Missed it. I like your approach better, and support allowing users to provide a predicate or filter function.

I think the only downside is possibly performance, but I don't expect that to be a big concern for Finish.

Copy link
Copy Markdown
Contributor Author

@atoulme atoulme Apr 7, 2026

Choose a reason for hiding this comment

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

Simply out of bandwidth. I will work on it for java.


Users can provide attributes to identify the Instrument.
This API MUST be structured to accept a variable number of attributes, including none.

### Counter

`Counter` is a [synchronous Instrument](#synchronous-instrument-api) which supports
Expand Down Expand Up @@ -596,6 +618,38 @@ counterPowerUsed.Add(13.5, new PowerConsumption { customer = "Tom" });
counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true));
```

##### Finish

**Status**: [Development](../document-status.md)

Unregister the attribute set. It will no longer be reported.
Copy link
Copy Markdown
Member

@reyang reyang Mar 17, 2026

Choose a reason for hiding this comment

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

"It will no longer be reported." - forever or until another API call trying to add the attribute set back?

Copy link
Copy Markdown
Contributor Author

@atoulme atoulme Mar 17, 2026

Choose a reason for hiding this comment

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

Registering again will create a new attribute set with a new start time.


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.finish({"exception_type": "IOError", "handled_by_user": True})
exception_counter.finish(exception_type="IOError", handled_by_user=True)
```

```csharp
// C#

counterExceptions.Finish(("exception_type", "FileLoadException"), ("handled_by_user", true));

counterPowerUsed.Finish(new PowerConsumption { customer = "Tom" });
counterPowerUsed.Finish(new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true));
```

### Asynchronous Counter

Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument-api)
Expand Down Expand Up @@ -825,6 +879,36 @@ httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "h
httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" });
```

##### Finish

**Status**: [Development](../document-status.md)

Unregister the attribute set. 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.Finish({"http.request.method": "POST", "url.scheme": "https"})
http_server_duration.Finish(http_method="GET", http_scheme="http")
```

```csharp
// C#

httpServerDuration.Finish(("http.request.method", "POST"), ("url.scheme", "https"));
httpServerDuration.Finish(new HttpRequestAttributes { method = "GET", scheme = "http" });
```

### Gauge

`Gauge` is a [synchronous Instrument](#synchronous-instrument-api) which can be
Expand Down Expand Up @@ -914,6 +998,31 @@ backgroundNoiseLevel.record(4.3, roomA);
backgroundNoiseLevel.record(2.5, roomB);
```

##### Finish

**Status**: [Development](../document-status.md)

Unregister the attribute set. 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.finish(roomA);
backgroundNoiseLevel.finish(roomB);
```

### Asynchronous Gauge

Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument-api)
Expand Down Expand Up @@ -1155,6 +1264,34 @@ customersInStore.Add(1, ("account.type", "commercial"));
customersInStore.Add(-1, new Account { Type = "residential" });
```

##### Finish

**Status**: [Development](../document-status.md)

Unregister the attribute set. 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.finish({"account.type": "commercial"})
customers_in_store.finish(account_type="residential")
```

```csharp
// C#
customersInStore.Finish(("account.type", "commercial"));
customersInStore.Finish(new Account { Type = "residential" });
```

### Asynchronous UpDownCounter

Asynchronous UpDownCounter is an [asynchronous
Expand Down
8 changes: 8 additions & 0 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ weight: 3
+ [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries)
+ [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes)
* [Instrument enabled](#instrument-enabled)
* [Finish](#finish)
- [Attribute limits](#attribute-limits)
- [Exemplar](#exemplar)
* [ExemplarFilter](#exemplarfilter)
Expand Down Expand Up @@ -1041,6 +1042,13 @@ Note: If a user makes no configuration changes, `Enabled` returns `true` since b
default `MeterConfig.enabled=true` and instruments use the default
aggregation when no matching views match the instrument.

Copy link
Copy Markdown
Contributor

@dashpole dashpole Mar 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Some things I would like to see specified in the SDK section:

  • Specify how this interacts with export and storage. Something like "The SDK MUST preserve previously-aggregated metric data for the timeseries until it has been Collected, and then MUST clear all internal storage associated with the timeseries."
  • Specify how this interacts with timestamps: Something like "When a an aggregation that has been Finished is Collected, its timestamp MUST be the time at which it was Finished". This may require changes elsewhere in the specification.
  • Specify what happens if a timeseries has been finished, but a new measurement is made to it. This is a bit tricky. Options are:
    • [Preferred] Un-finish the timeseries. This is a new observation, so rather than stop + start again, we can just continue the existing aggregation.
    • Move the timestamp back to the current measurement time, but still Finish the timeseries. This might help if there is a race where a measurement is made just after it is Finished.
    • Keep the existing timeseries finished, but start a new one with a new start timestamp. This might be complex to implement, as they would both have the same attribute set.

Copy link
Copy Markdown
Member

@jack-berg jack-berg Mar 30, 2026

Choose a reason for hiding this comment

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

[Preferred[ Un-finish the timeseries. This is a new observation, so rather than stop + start again, we can just continue the existing aggregation.

👍

### Finish

**Status**: [Development](../document-status.md)

The synchronous instrument [Finish](./api.md#finish) SHOULD NOT return a value (it MAY return a dummy value if required by
certain programming languages or systems, for example `null`, `undefined`).

## Attribute limits

**Status**: [Stable](../document-status.md)
Expand Down
Loading