Skip to content

refactor(API): deprecate non-descriptor metric creation methods #154

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
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

refactor(API): deprecate non-descriptor metric creation methods #154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
51 changes: 41 additions & 10 deletions Sources/Prometheus/MetricDescriptor.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,27 +27,25 @@ public struct MetricNameDescriptor {
/// The required, descriptive base name of the metric.
public let metricName: String

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

/// 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
public let helpText: String?
/// 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.
public let helpText: String

/// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
///
/// - Parameter namespace: An optional top-level namespace for the metric.
/// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
/// - Parameter metricName: The required, descriptive base name of the metric.
/// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Parameter unitName: The required suffix describing the metric's unit (e.g., `total`).
/// - 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.
public init(
namespace: String? = nil,
subsystem: String? = nil,
metricName: String,
unitName: String? = nil,
helpText: String? = nil
unitName: String,
helpText: String
) {
precondition(!metricName.isEmpty, "metricName must not be empty")
self.namespace = namespace
Expand All @@ -64,3 +62,36 @@ public struct MetricNameDescriptor {
.joined(separator: "_")
}
}

// MARK: - Deprecated

extension MetricNameDescriptor {
/// Creates a new ``MetricNameDescriptor`` that defines the components of a fully qualified Prometheus metric name.
///
/// - Parameter namespace: An optional top-level namespace for the metric.
/// - Parameter subsystem: An optional subsystem to group related metrics within a namespace.
/// - Parameter metricName: The required, descriptive base name of the metric.
/// - Parameter unitName: An optional suffix describing the metric's unit (e.g., `total`).
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
@available(
*,
deprecated,
message: "This initializer is deprecated; 'unitName' and 'helpText' are now required parameters."
)
public init(
namespace: String? = nil,
subsystem: String? = nil,
metricName: String,
unitName: String? = nil,
helpText: String? = nil
) {
self.init(
namespace: namespace,
subsystem: subsystem,
metricName: metricName,
unitName: unitName ?? "",
helpText: helpText ?? ""
)
}
}
32 changes: 24 additions & 8 deletions Sources/Prometheus/PrometheusCollectorRegistry.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeCounter(descriptor:)` instead.")
public func makeCounter(name: String, help: String) -> Counter {
return self.makeCounter(name: name, labels: [], help: help)
}
Expand All @@ -224,6 +225,7 @@ public final class PrometheusCollectorRegistry: Sendable {
///
/// - Parameter name: A name to identify ``Counter``'s value.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeCounter(descriptor:)` instead.")
public func makeCounter(name: String) -> Counter {
return self.makeCounter(name: name, labels: [], help: "")
}
Expand All @@ -237,7 +239,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter descriptor: An ``MetricNameDescriptor`` that provides the fully qualified name for the metric.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
public func makeCounter(descriptor: MetricNameDescriptor) -> Counter {
return self.makeCounter(name: descriptor.name, labels: [], help: descriptor.helpText ?? "")
return self.makeCounter(name: descriptor.name, labels: [], help: descriptor.helpText)
}

/// Creates a new ``Counter`` collector or returns the already existing one with the same name.
Expand All @@ -251,6 +253,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeCounter(descriptor:labels:)` instead.")
public func makeCounter(name: String, labels: [(String, String)], help: String) -> Counter {
let name = name.ensureValidMetricName()
let labels = labels.ensureValidLabelNames()
Expand Down Expand Up @@ -322,6 +325,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter labels: Labels are sets of key-value pairs that allow us to characterize and organize
/// what’s actually being measured in a Prometheus metric.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeCounter(descriptor:labels:)` instead.")
public func makeCounter(name: String, labels: [(String, String)]) -> Counter {
return self.makeCounter(name: name, labels: labels, help: "")
}
Expand All @@ -337,7 +341,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// what’s actually being measured in a Prometheus metric.
/// - Returns: A ``Counter`` that is registered with this ``PrometheusCollectorRegistry``
public func makeCounter(descriptor: MetricNameDescriptor, labels: [(String, String)]) -> Counter {
return self.makeCounter(name: descriptor.name, labels: labels, help: descriptor.helpText ?? "")
return self.makeCounter(name: descriptor.name, labels: labels, help: descriptor.helpText)
}

/// Creates a new ``Gauge`` collector or returns the already existing one with the same name.
Expand All @@ -349,6 +353,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeGauge(descriptor:)` instead.")
public func makeGauge(name: String, help: String) -> Gauge {
return self.makeGauge(name: name, labels: [], help: help)
}
Expand All @@ -360,6 +365,7 @@ public final class PrometheusCollectorRegistry: Sendable {
///
/// - Parameter name: A name to identify ``Gauge``'s value.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeGauge(descriptor:)` instead.")
public func makeGauge(name: String) -> Gauge {
return self.makeGauge(name: name, labels: [], help: "")
}
Expand All @@ -373,7 +379,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter descriptor: An ``MetricNameDescriptor`` that provides the fully qualified name for the metric.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
public func makeGauge(descriptor: MetricNameDescriptor) -> Gauge {
return self.makeGauge(name: descriptor.name, labels: [], help: descriptor.helpText ?? "")
return self.makeGauge(name: descriptor.name, labels: [], help: descriptor.helpText)
}

/// Creates a new ``Gauge`` collector or returns the already existing one with the same name.
Expand All @@ -387,6 +393,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeGauge(descriptor:labels:)` instead.")
public func makeGauge(name: String, labels: [(String, String)], help: String) -> Gauge {
let name = name.ensureValidMetricName()
let labels = labels.ensureValidLabelNames()
Expand Down Expand Up @@ -458,6 +465,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter labels: Labels are sets of key-value pairs that allow us to characterize and organize
/// what’s actually being measured in a Prometheus metric.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeGauge(descriptor:labels:)` instead.")
public func makeGauge(name: String, labels: [(String, String)]) -> Gauge {
return self.makeGauge(name: name, labels: labels, help: "")
}
Expand All @@ -473,7 +481,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// what’s actually being measured in a Prometheus metric.
/// - Returns: A ``Gauge`` that is registered with this ``PrometheusCollectorRegistry``
public func makeGauge(descriptor: MetricNameDescriptor, labels: [(String, String)]) -> Gauge {
return self.makeGauge(name: descriptor.name, labels: labels, help: descriptor.helpText ?? "")
return self.makeGauge(name: descriptor.name, labels: labels, help: descriptor.helpText)
}

/// Creates a new ``DurationHistogram`` collector or returns the already existing one with the same name.
Expand All @@ -486,6 +494,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:buckets:)` instead.")
public func makeDurationHistogram(name: String, buckets: [Duration], help: String) -> DurationHistogram {
return self.makeDurationHistogram(name: name, labels: [], buckets: buckets, help: help)
}
Expand All @@ -498,6 +507,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter name: A name to identify ``DurationHistogram``'s value.
/// - Parameter buckets: Define the buckets that shall be used within the ``DurationHistogram``
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:buckets:)` instead.")
public func makeDurationHistogram(name: String, buckets: [Duration]) -> DurationHistogram {
return self.makeDurationHistogram(name: name, labels: [], buckets: buckets, help: "")
}
Expand All @@ -516,7 +526,7 @@ public final class PrometheusCollectorRegistry: Sendable {
name: descriptor.name,
labels: [],
buckets: buckets,
help: descriptor.helpText ?? ""
help: descriptor.helpText
)
}

Expand All @@ -532,6 +542,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:labels:buckets:)` instead.")
public func makeDurationHistogram(
name: String,
labels: [(String, String)],
Expand Down Expand Up @@ -624,6 +635,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// what’s actually being measured in a Prometheus metric.
/// - Parameter buckets: Define the buckets that shall be used within the ``DurationHistogram``
/// - Returns: A ``DurationHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeDurationHistogram(descriptor:labels:buckets:)` instead.")
public func makeDurationHistogram(
name: String,
labels: [(String, String)],
Expand Down Expand Up @@ -657,7 +669,7 @@ public final class PrometheusCollectorRegistry: Sendable {
name: descriptor.name,
labels: labels,
buckets: buckets,
help: descriptor.helpText ?? ""
help: descriptor.helpText
)
}

Expand All @@ -671,6 +683,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:buckets:)` instead.")
public func makeValueHistogram(name: String, buckets: [Double], help: String) -> ValueHistogram {
return self.makeValueHistogram(name: name, labels: [], buckets: buckets, help: help)
}
Expand All @@ -683,6 +696,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - Parameter name: A name to identify ``ValueHistogram``'s value.
/// - Parameter buckets: Define the buckets that shall be used within the ``ValueHistogram``
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:buckets:)` instead.")
public func makeValueHistogram(name: String, buckets: [Double]) -> ValueHistogram {
return self.makeValueHistogram(name: name, labels: [], buckets: buckets, help: "")
}
Expand All @@ -701,7 +715,7 @@ public final class PrometheusCollectorRegistry: Sendable {
name: descriptor.name,
labels: [],
buckets: buckets,
help: descriptor.helpText ?? ""
help: descriptor.helpText
)
}

Expand All @@ -717,6 +731,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// - 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.
/// If the parameter is omitted or an empty string is passed, the `# HELP` line will not be generated for this metric.
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:labels:buckets:)` instead.")
public func makeValueHistogram(
name: String,
labels: [(String, String)],
Expand Down Expand Up @@ -808,6 +823,7 @@ public final class PrometheusCollectorRegistry: Sendable {
/// what’s actually being measured in a Prometheus metric.
/// - Parameter buckets: Define the buckets that shall be used within the ``ValueHistogram``
/// - Returns: A ``ValueHistogram`` that is registered with this ``PrometheusCollectorRegistry``
@available(*, deprecated, message: "Use `makeValueHistogram(descriptor:labels:buckets:)` instead.")
public func makeValueHistogram(
name: String,
labels: [(String, String)],
Expand Down Expand Up @@ -841,7 +857,7 @@ public final class PrometheusCollectorRegistry: Sendable {
name: descriptor.name,
labels: labels,
buckets: buckets,
help: descriptor.helpText ?? ""
help: descriptor.helpText
)
}

Expand Down
Loading