prometheus-net

1
namespace Prometheus;
2

3
/// <summary>
4
/// Handle to a metric with a lease-extended lifetime, enabling the metric to be accessed and its lifetime to be controlled.
5
/// Each label combination is automatically deleted N seconds after the last lease on that label combination expires.
6
/// </summary>
7
/// <remarks>
8
/// When creating leases, prefer the overload that takes a ReadOnlySpan because it avoids
9
/// allocating a string array if the metric instance you are leasing is already alive.
10
/// </remarks>
11
public interface IManagedLifetimeMetricHandle<TMetricInterface>
12
    where TMetricInterface : ICollectorChild
13
{
14
    #region Lease(string[])
15
    /// <summary>
16
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
17
    /// 
18
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
19
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
20
    /// </summary>
21
    /// <remarks>
22
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
23
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
24
    /// </remarks>
25
    IDisposable AcquireLease(out TMetricInterface metric, params string[] labelValues);
26

27
    /// <summary>
28
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
29
    /// The lease is returned as a stack-only struct, which is faster than the IDisposable version.
30
    /// 
31
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
32
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
33
    /// </summary>
34
    /// <remarks>
35
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
36
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
37
    /// </remarks>
38
    RefLease AcquireRefLease(out TMetricInterface metric, params string[] labelValues);
39

40
    /// <summary>
41
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
42
    /// 
43
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
44
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
45
    /// </summary>
46
    /// <remarks>
47
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
48
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
49
    /// </remarks>
50
    void WithLease(Action<TMetricInterface> action, params string[] labelValues);
51

52
    /// <summary>
53
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
54
    /// Passes a given argument to the callback.
55
    /// 
56
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
57
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
58
    /// </summary>
59
    /// <remarks>
60
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
61
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
62
    /// </remarks>
63
    void WithLease<TArg>(Action<TArg, TMetricInterface> action, TArg arg, params string[] labelValues);
64

65
    /// <summary>
66
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
67
    /// 
68
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
69
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
70
    /// </summary>
71
    /// <remarks>
72
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
73
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
74
    /// </remarks>
75
    Task WithLeaseAsync(Func<TMetricInterface, Task> func, params string[] labelValues);
76

77
    /// <summary>
78
    /// While executing a function, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
79
    /// 
80
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
81
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
82
    /// </summary>
83
    /// <remarks>
84
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
85
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
86
    /// </remarks>
87
    TResult WithLease<TResult>(Func<TMetricInterface, TResult> func, params string[] labelValues);
88

89
    /// <summary>
90
    /// While executing a function, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
91
    /// 
92
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
93
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
94
    /// </summary>
95
    /// <remarks>
96
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
97
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
98
    /// </remarks>
99
    Task<TResult> WithLeaseAsync<TResult>(Func<TMetricInterface, Task<TResult>> action, params string[] labelValues);
100
    #endregion
101

102
    #region Lease(ReadOnlyMemory<string>)
103
    /// <summary>
104
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
105
    /// 
106
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
107
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
108
    /// </summary>
109
    /// <remarks>
110
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
111
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
112
    /// </remarks>
113
    IDisposable AcquireLease(out TMetricInterface metric, ReadOnlyMemory<string> labelValues);
114

115
    /// <summary>
116
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
117
    /// The lease is returned as a stack-only struct, which is faster than the IDisposable version.
118
    /// 
119
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
120
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
121
    /// </summary>
122
    /// <remarks>
123
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
124
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
125
    /// </remarks>
126
    RefLease AcquireRefLease(out TMetricInterface metric, ReadOnlyMemory<string> labelValues);
127

128
    /// <summary>
129
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
130
    /// 
131
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
132
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
133
    /// </summary>
134
    /// <remarks>
135
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
136
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
137
    /// </remarks>
138
    void WithLease(Action<TMetricInterface> action, ReadOnlyMemory<string> labelValues);
139

140
    /// <summary>
141
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
142
    /// Passes a given argument to the callback.
143
    /// 
144
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
145
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
146
    /// </summary>
147
    /// <remarks>
148
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
149
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
150
    /// </remarks>
151
    void WithLease<TArg>(Action<TArg, TMetricInterface> action, TArg arg, ReadOnlyMemory<string> labelValues);
152

153
    /// <summary>
154
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
155
    /// 
156
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
157
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
158
    /// </summary>
159
    /// <remarks>
160
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
161
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
162
    /// </remarks>
163
    Task WithLeaseAsync(Func<TMetricInterface, Task> func, ReadOnlyMemory<string> labelValues);
164

165

166
    /// <summary>
167
    /// While executing a function, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
168
    /// 
169
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
170
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
171
    /// </summary>
172
    /// <remarks>
173
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
174
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
175
    /// </remarks>
176
    TResult WithLease<TResult>(Func<TMetricInterface, TResult> func, ReadOnlyMemory<string> labelValues);
177

178
    /// <summary>
179
    /// While executing a function, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
180
    /// 
181
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
182
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
183
    /// </summary>
184
    /// <remarks>
185
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
186
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
187
    /// </remarks>
188
    Task<TResult> WithLeaseAsync<TResult>(Func<TMetricInterface, Task<TResult>> action, ReadOnlyMemory<string> labelValues);
189
    #endregion
190

191
    #region Lease(ReadOnlySpan<string>)
192
    /// <summary>
193
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
194
    /// 
195
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
196
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
197
    /// </summary>
198
    /// <remarks>
199
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
200
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
201
    /// </remarks>
202
    IDisposable AcquireLease(out TMetricInterface metric, ReadOnlySpan<string> labelValues);
203

204
    /// <summary>
205
    /// Takes a lifetime-extending lease on the metric, scoped to a specific combination of label values.
206
    /// The lease is returned as a stack-only struct, which is faster than the IDisposable version.
207
    /// 
208
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
209
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
210
    /// </summary>
211
    /// <remarks>
212
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
213
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
214
    /// </remarks>
215
    RefLease AcquireRefLease(out TMetricInterface metric, ReadOnlySpan<string> labelValues);
216

217
    /// <summary>
218
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
219
    /// 
220
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
221
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
222
    /// </summary>
223
    /// <remarks>
224
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
225
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
226
    /// </remarks>
227
    void WithLease(Action<TMetricInterface> action, ReadOnlySpan<string> labelValues);
228

229
    /// <summary>
230
    /// While executing an action, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
231
    /// Passes a given argument to the callback.
232
    /// 
233
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
234
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
235
    /// </summary>
236
    /// <remarks>
237
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
238
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
239
    /// </remarks>
240
    void WithLease<TArg>(Action<TArg, TMetricInterface> action, TArg arg, ReadOnlySpan<string> labelValues);
241

242
    /// <summary>
243
    /// While executing a function, holds a lifetime-extending lease on the metric, scoped to a specific combination of label values.
244
    /// 
245
    /// The typical pattern is that the metric value is only modified when the caller is holding a lease on the metric.
246
    /// Automatic removal of the metric will not occur until all leases on the metric are disposed and the expiration duration elapses.
247
    /// </summary>
248
    /// <remarks>
249
    /// Acquiring a new lease after the metric has been removed will re-publish the metric without preserving the old value.
250
    /// Re-publishing may return a new instance of the metric (data collected via expired instances will not be published).
251
    /// </remarks>
252
    TResult WithLease<TResult>(Func<TMetricInterface, TResult> func, ReadOnlySpan<string> labelValues);
253
    #endregion
254

255
    /// <summary>
256
    /// Returns a metric instance that automatically extends the lifetime of the timeseries whenever the value is changed.
257
    /// This is equivalent to taking a lease for every update to the value, and immediately releasing the lease.
258
    /// 
259
    /// This is useful if the caller is lifetime-management-agnostic code that is not aware of the possibility to extend metric lifetime via leases.
260
    /// Do not use this if you can use explicit leases instead, as this is considerably less efficient.
261
    /// </summary>
262
    ICollector<TMetricInterface> WithExtendLifetimeOnUse();
263
}
264