mirror
/
swift-metrics
mirror of https://github.com/apple/swift-metrics.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc: #26 clarify which init to use, reformat docs for easier noticing this (#27) 

* doc: #26 clarify which init to use, reformat docs for easier noticing this

* Mark all "we do not expect this API to be used in normal..." as warnings
This commit is contained in:
Konrad `ktoso` Malawski 2019-05-25 14:33:16 +09:00 committed by GitHub
parent 4c24199dea
commit 4a9e0de637
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Sources/CoreMetrics/Metrics.swift
View File

@ -36,17 +36,22 @@ public protocol CounterHandler: AnyObject {
/// A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero. /// A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero.
/// For example, you can use a counter to represent the number of requests served, tasks completed, or errors. /// For example, you can use a counter to represent the number of requests served, tasks completed, or errors.
/// This is the user facing Counter API. Its behavior depends on the `CounterHandler` implementation. ///
/// This is the user-facing Counter API.
///
/// Its behavior depends on the `CounterHandler` implementation.
public class Counter { public class Counter {
@usableFromInline @usableFromInline
var handler: CounterHandler var handler: CounterHandler
public let label: String public let label: String
public let dimensions: [(String, String)] public let dimensions: [(String, String)]
/// Create a new `Counter`. /// Alternative way to create a new `Counter`, while providing an explicit `CounterHandler`.
/// ///
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one. /// - warning: This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason. /// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Counter` instances using the configured metrics backend.
/// ///
/// - parameters: /// - parameters:
/// - label: The label for the `Counter`. /// - label: The label for the `Counter`.
@ -124,7 +129,10 @@ public protocol RecorderHandler: AnyObject {
} }
/// A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example, count, sum, min, max and various quantiles. /// A recorder collects observations within a time window (usually things like response sizes) and *can* provide aggregated information about the data sample, for example, count, sum, min, max and various quantiles.
/// This is the user facing Recorder API. Its behavior depends on the `RecorderHandler` implementation. ///
/// This is the user-facing Recorder API.
///
/// Its behavior depends on the `RecorderHandler` implementation.
public class Recorder { public class Recorder {
@usableFromInline @usableFromInline
var handler: RecorderHandler var handler: RecorderHandler
@ -132,10 +140,12 @@ public class Recorder {
public let dimensions: [(String, String)] public let dimensions: [(String, String)]
public let aggregate: Bool public let aggregate: Bool
/// Create a new `Recorder`. /// Alternative way to create a new `Recorder`, while providing an explicit `RecorderHandler`.
/// ///
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one. /// - warning: This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason. /// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Recorder` instances using the configured metrics backend.
/// ///
/// - parameters: /// - parameters:
/// - label: The label for the `Recorder`. /// - label: The label for the `Recorder`.
@ -221,17 +231,22 @@ public protocol TimerHandler: AnyObject {
/// A timer collects observations within a time window (usually things like request durations) and provides aggregated information about the data sample, /// A timer collects observations within a time window (usually things like request durations) and provides aggregated information about the data sample,
/// for example, min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations. /// for example, min, max and various quantiles. It is similar to a `Recorder` but specialized for values that represent durations.
/// This is the user facing Timer API. Its behavior depends on the `TimerHandler` implementation. ///
/// This is the user-facing Timer API.
///
/// Its behavior depends on the `TimerHandler` implementation.
public class Timer { public class Timer {
@usableFromInline @usableFromInline
var handler: TimerHandler var handler: TimerHandler
public let label: String public let label: String
public let dimensions: [(String, String)] public let dimensions: [(String, String)]
/// Create a new `Timer`. /// Alternative way to create a new `Timer`, while providing an explicit `TimerHandler`.
/// ///
/// This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one. /// - warning: This initializer provides an escape hatch for situations where one must use a custom factory instead of the global one.
/// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason. /// We do not expect this API to be used in normal circumstances, so if you find yourself using it make sure it's for a good reason.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Recorder` instances using the configured metrics backend.
/// ///
/// - parameters: /// - parameters:
/// - label: The label for the `Timer`. /// - label: The label for the `Timer`.
@ -347,8 +362,8 @@ public extension Timer {
/// * `Recorder` -> `RecorderHandler` /// * `Recorder` -> `RecorderHandler`
/// * `Timer` -> `TimerHandler` /// * `Timer` -> `TimerHandler`
/// ///
/// This type is an implementation detail and should not be used directly, unless implementing your own metrics backend. /// - warning: This type is an implementation detail and should not be used directly, unless implementing your own metrics backend.
/// To use the SwiftMetrics API, please refer to the documentation of `MetricsSystem`. /// To use the SwiftMetrics API, please refer to the documentation of `MetricsSystem`.
/// ///
/// # Destroying metrics /// # Destroying metrics
/// ///