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

35
Sources/CoreMetrics/Metrics.swift
View File

@ -36,18 +36,23 @@ 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.
/// 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 {
@usableFromInline
var handler: CounterHandler
public let label: 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.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Counter` instances using the configured metrics backend.
///
/// - parameters:
/// - label: The label for the `Counter`.
/// - dimensions: The dimensions 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.
/// 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 {
@usableFromInline
var handler: RecorderHandler
@ -132,11 +140,13 @@ public class Recorder {
public let dimensions: [(String, String)]
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.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Recorder` instances using the configured metrics backend.
///
/// - parameters:
/// - label: The label for the `Recorder`.
/// - dimensions: The dimensions for the `Recorder`.
@ -221,18 +231,23 @@ 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,
/// 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 {
@usableFromInline
var handler: TimerHandler
public let label: 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.
///
/// - SeeAlso: Use `init(label:dimensions:)` to create `Recorder` instances using the configured metrics backend.
///
/// - parameters:
/// - label: The label for the `Timer`.
/// - dimensions: The dimensions for the `Timer`.
@ -347,7 +362,7 @@ public extension Timer {
/// * `Recorder` -> `RecorderHandler`
/// * `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`.
///
/// # Destroying metrics