Skip to content

Commit ac36981

Browse files
incertumincertum
committed
refactor(API): deprecate non-descriptor metric creation methods
Deprecates all metric creation methods that accept loose string parameters for name and help text. This standardizes metric creation on the MetricNameDescriptor type, which requires a metricName, unitName and helpText for all metrics. This improves compliance with official Prometheus client library guidelines ("A MetricFamily MUST have a name, HELP, TYPE, and UNIT metadata."). The deprecated methods will be removed in a future major version (see #145). Signed-off-by: Melissa Kilby <[email protected]>
1 parent 7bb0c9e commit ac36981

File tree

2 files changed

+61
-18
lines changed

2 files changed

+61
-18
lines changed

‎Sources/Prometheus/MetricDescriptor.swift‎

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,27 +27,25 @@ public struct MetricNameDescriptor {
2727
/// The required, descriptive base name of the metric.
2828
public let metricName: String
2929

30-
/// An optional suffix describing the metric's unit (e.g., `total`).
31-
public let unitName: String?
30+
/// The required suffix describing the metric's unit (e.g., `total`).
31+
public let unitName: String
3232

33-
/// Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
34-
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
35-
public let helpText: String?
33+
/// The required help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
34+
public let helpText: String
3635

3736
/// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
3837
///
3938
/// - Parameter namespace: An optional top-level namespace for the metric.
4039
/// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
4140
/// - Parameter metricName: The required, descriptive base name of the metric.
42-
/// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
43-
/// - Parameter helpText: Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
44-
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
41+
/// - Parameter unitName: The required suffix describing the metric's unit (e.g., `total`).
42+
/// - Parameter helpText: The required help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
4543
public init(
4644
namespace: String? = nil,
4745
subsystem: String? = nil,
4846
metricName: String,
49-
unitName: String? = nil,
50-
helpText: String? = nil
47+
unitName: String,
48+
helpText: String
5149
) {
5250
precondition(!metricName.isEmpty, "metricName must not be empty")
5351
self.namespace = namespace
@@ -64,3 +62,32 @@ public struct MetricNameDescriptor {
6462
.joined(separator: "_")
6563
}
6664
}
65+
66+
// MARK: - Deprecated
67+
68+
extension MetricNameDescriptor {
69+
/// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
70+
///
71+
/// - Parameter namespace: An optional top-level namespace for the metric.
72+
/// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
73+
/// - Parameter metricName: The required, descriptive base name of the metric.
74+
/// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
75+
/// - Parameter helpText: Optional help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
76+
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
77+
@available(*, deprecated, message: "This initializer is deprecated; 'unitName' and 'helpText' are now required parameters.")
78+
public init(
79+
namespace: String? = nil,
80+
subsystem: String? = nil,
81+
metricName: String,
82+
unitName: String? = nil,
83+
helpText: String? = nil
84+
) {
85+
self.init(
86+
namespace: namespace,
87+
subsystem: subsystem,
88+
metricName: metricName,
89+
unitName: unitName ?? "",
90+
helpText: helpText ?? ""
91+
)
92+
}
93+
}

‎Sources/Prometheus/PrometheusCollectorRegistry.swift‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,7 @@ public final class PrometheusCollectorRegistry: Sendable {
213213
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
214214
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
215215
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
216+
@available(*, deprecated, message: "Use `makeCounter(descriptor:)` instead.")
216217
public func makeCounter(name: String, help: String) -> Counter {
217218
return self.makeCounter(name: name, labels: [], help: help)
218219
}
@@ -224,6 +225,7 @@ public final class PrometheusCollectorRegistry: Sendable {
224225
///
225226
/// - Parameter name: A name to identify ``Counter``'s value.
226227
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
228+
@available(*, deprecated, message: "Use `makeCounter(descriptor:)` instead.")
227229
public func makeCounter(name: String) -> Counter {
228230
return self.makeCounter(name: name, labels: [], help: "")
229231
}
@@ -237,7 +239,7 @@ public final class PrometheusCollectorRegistry: Sendable {
237239
/// - Parameter descriptor: An ``MetricNameDescriptor`` that provides the fully qualified name for the metric.
238240
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
239241
public func makeCounter(descriptor: MetricNameDescriptor) -> Counter {
240-
return self.makeCounter(name: descriptor.name, labels: [], help: descriptor.helpText ?? "")
242+
return self.makeCounter(name: descriptor.name, labels: [], help: descriptor.helpText)
241243
}
242244

243245
/// Creates a new ``Counter`` collector or returns the already existing one with the same name.
@@ -251,6 +253,7 @@ public final class PrometheusCollectorRegistry: Sendable {
251253
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
252254
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
253255
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
256+
@available(*, deprecated, message: "Use `makeCounter(descriptor:labels:)` instead.")
254257
public func makeCounter(name: String, labels: [(String, String)], help: String) -> Counter {
255258
let name = name.ensureValidMetricName()
256259
let labels = labels.ensureValidLabelNames()
@@ -322,6 +325,7 @@ public final class PrometheusCollectorRegistry: Sendable {
322325
/// - Parameter labels: Labels are sets of key-value pairs that allow us to characterize and organize
323326
/// what’s actually being measured in a Prometheus metric.
324327
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
328+
@available(*, deprecated, message: "Use `makeCounter(descriptor:labels:)` instead.")
325329
public func makeCounter(name: String, labels: [(String, String)]) -> Counter {
326330
return self.makeCounter(name: name, labels: labels, help: "")
327331
}
@@ -337,7 +341,7 @@ public final class PrometheusCollectorRegistry: Sendable {
337341
/// what’s actually being measured in a Prometheus metric.
338342
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
339343
public func makeCounter(descriptor: MetricNameDescriptor, labels: [(String, String)]) -> Counter {
340-
return self.makeCounter(name: descriptor.name, labels: labels, help: descriptor.helpText ?? "")
344+
return self.makeCounter(name: descriptor.name, labels: labels, help: descriptor.helpText)
341345
}
342346

343347
/// Creates a new ``Gauge`` collector or returns the already existing one with the same name.
@@ -349,6 +353,7 @@ public final class PrometheusCollectorRegistry: Sendable {
349353
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
350354
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
351355
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
356+
@available(*, deprecated, message: "Use `makeGauge(descriptor:)` instead.")
352357
public func makeGauge(name: String, help: String) -> Gauge {
353358
return self.makeGauge(name: name, labels: [], help: help)
354359
}
@@ -360,6 +365,7 @@ public final class PrometheusCollectorRegistry: Sendable {
360365
///
361366
/// - Parameter name: A name to identify ``Gauge``'s value.
362367
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
368+
@available(*, deprecated, message: "Use `makeGauge(descriptor:)` instead.")
363369
public func makeGauge(name: String) -> Gauge {
364370
return self.makeGauge(name: name, labels: [], help: "")
365371
}
@@ -373,7 +379,7 @@ public final class PrometheusCollectorRegistry: Sendable {
373379
/// - Parameter descriptor: An ``MetricNameDescriptor`` that provides the fully qualified name for the metric.
374380
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
375381
public func makeGauge(descriptor: MetricNameDescriptor) -> Gauge {
376-
return self.makeGauge(name: descriptor.name, labels: [], help: descriptor.helpText ?? "")
382+
return self.makeGauge(name: descriptor.name, labels: [], help: descriptor.helpText)
377383
}
378384

379385
/// Creates a new ``Gauge`` collector or returns the already existing one with the same name.
@@ -387,6 +393,7 @@ public final class PrometheusCollectorRegistry: Sendable {
387393
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
388394
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
389395
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
396+
@available(*, deprecated, message: "Use `makeGauge(descriptor:labels:)` instead.")
390397
public func makeGauge(name: String, labels: [(String, String)], help: String) -> Gauge {
391398
let name = name.ensureValidMetricName()
392399
let labels = labels.ensureValidLabelNames()
@@ -458,6 +465,7 @@ public final class PrometheusCollectorRegistry: Sendable {
458465
/// - Parameter labels: Labels are sets of key-value pairs that allow us to characterize and organize
459466
/// what’s actually being measured in a Prometheus metric.
460467
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
468+
@available(*, deprecated, message: "Use `makeGauge(descriptor:labels:)` instead.")
461469
public func makeGauge(name: String, labels: [(String, String)]) -> Gauge {
462470
return self.makeGauge(name: name, labels: labels, help: "")
463471
}
@@ -473,7 +481,7 @@ public final class PrometheusCollectorRegistry: Sendable {
473481
/// what’s actually being measured in a Prometheus metric.
474482
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
475483
public func makeGauge(descriptor: MetricNameDescriptor, labels: [(String, String)]) -> Gauge {
476-
return self.makeGauge(name: descriptor.name, labels: labels, help: descriptor.helpText ?? "")
484+
return self.makeGauge(name: descriptor.name, labels: labels, help: descriptor.helpText)
477485
}
478486

479487
/// Creates a new ``DurationHistogram`` collector or returns the already existing one with the same name.
@@ -486,6 +494,7 @@ public final class PrometheusCollectorRegistry: Sendable {
486494
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
487495
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
488496
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
497+
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:buckets:)` instead.")
489498
public func makeDurationHistogram(name: String, buckets: [Duration], help: String) -> DurationHistogram {
490499
return self.makeDurationHistogram(name: name, labels: [], buckets: buckets, help: help)
491500
}
@@ -498,6 +507,7 @@ public final class PrometheusCollectorRegistry: Sendable {
498507
/// - Parameter name: A name to identify ``DurationHistogram``'s value.
499508
/// - Parameter buckets: Define the buckets that shall be used within the ``DurationHistogram``
500509
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
510+
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:buckets:)` instead.")
501511
public func makeDurationHistogram(name: String, buckets: [Duration]) -> DurationHistogram {
502512
return self.makeDurationHistogram(name: name, labels: [], buckets: buckets, help: "")
503513
}
@@ -516,7 +526,7 @@ public final class PrometheusCollectorRegistry: Sendable {
516526
name: descriptor.name,
517527
labels: [],
518528
buckets: buckets,
519-
help: descriptor.helpText ?? ""
529+
help: descriptor.helpText
520530
)
521531
}
522532

@@ -532,6 +542,7 @@ public final class PrometheusCollectorRegistry: Sendable {
532542
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
533543
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
534544
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
545+
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:labels:buckets:)` instead.")
535546
public func makeDurationHistogram(
536547
name: String,
537548
labels: [(String, String)],
@@ -624,6 +635,7 @@ public final class PrometheusCollectorRegistry: Sendable {
624635
/// what’s actually being measured in a Prometheus metric.
625636
/// - Parameter buckets: Define the buckets that shall be used within the ``DurationHistogram``
626637
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
638+
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:labels:buckets:)` instead.")
627639
public func makeDurationHistogram(
628640
name: String,
629641
labels: [(String, String)],
@@ -657,7 +669,7 @@ public final class PrometheusCollectorRegistry: Sendable {
657669
name: descriptor.name,
658670
labels: labels,
659671
buckets: buckets,
660-
help: descriptor.helpText ?? ""
672+
help: descriptor.helpText
661673
)
662674
}
663675

@@ -671,6 +683,7 @@ public final class PrometheusCollectorRegistry: Sendable {
671683
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
672684
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
673685
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
686+
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:buckets:)` instead.")
674687
public func makeValueHistogram(name: String, buckets: [Double], help: String) -> ValueHistogram {
675688
return self.makeValueHistogram(name: name, labels: [], buckets: buckets, help: help)
676689
}
@@ -683,6 +696,7 @@ public final class PrometheusCollectorRegistry: Sendable {
683696
/// - Parameter name: A name to identify ``ValueHistogram``'s value.
684697
/// - Parameter buckets: Define the buckets that shall be used within the ``ValueHistogram``
685698
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
699+
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:buckets:)` instead.")
686700
public func makeValueHistogram(name: String, buckets: [Double]) -> ValueHistogram {
687701
return self.makeValueHistogram(name: name, labels: [], buckets: buckets, help: "")
688702
}
@@ -701,7 +715,7 @@ public final class PrometheusCollectorRegistry: Sendable {
701715
name: descriptor.name,
702716
labels: [],
703717
buckets: buckets,
704-
help: descriptor.helpText ?? ""
718+
help: descriptor.helpText
705719
)
706720
}
707721

@@ -717,6 +731,7 @@ public final class PrometheusCollectorRegistry: Sendable {
717731
/// - Parameter help: Help text for the metric. If a non-empty string is provided, it will be emitted as a `# HELP` line in the exposition format.
718732
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
719733
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
734+
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:labels:buckets:)` instead.")
720735
public func makeValueHistogram(
721736
name: String,
722737
labels: [(String, String)],
@@ -808,6 +823,7 @@ public final class PrometheusCollectorRegistry: Sendable {
808823
/// what’s actually being measured in a Prometheus metric.
809824
/// - Parameter buckets: Define the buckets that shall be used within the ``ValueHistogram``
810825
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
826+
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:labels:buckets:)` instead.")
811827
public func makeValueHistogram(
812828
name: String,
813829
labels: [(String, String)],
@@ -841,7 +857,7 @@ public final class PrometheusCollectorRegistry: Sendable {
841857
name: descriptor.name,
842858
labels: labels,
843859
buckets: buckets,
844-
help: descriptor.helpText ?? ""
860+
help: descriptor.helpText
845861
)
846862
}
847863

0 commit comments

Comments
 (0)