TimingDistributionMetricType

public class TimingDistributionMetricType

This implements the developer facing API for recording timing distribution metrics.

Instances of this class type are automatically generated by the parsers at build time, allowing developers to record values that were previously registered in the metrics.yaml file.

The timing distribution API only exposes the TimingDistributionMetricType.start(), TimingDistributionMetricType.stopAndAccumulate(_:) and TimingDistributionMetricType.cancel(_:) methods.

  • The public constructor used by automatically generated metrics.

    Declaration

    Swift

    public init(category: String,
                name: String,
                sendInPings: [String],
                lifetime: Lifetime,
                disabled: Bool,
                timeUnit: TimeUnit = .minute)
  • Start tracking time for the provided metric and GleanTimerId. This records an error if it’s already tracking time (i.e. start was already called with no corresponding stopAndAccumulate(_:)): in that case the original start time will be preserved.

    Declaration

    Swift

    public func start() -> GleanTimerId?
  • Stop tracking time for the provided metric and associated timer id. Add a count to the corresponding bucket in the timing distribution. This will record an error if no start() was called.

    Declaration

    Swift

    public func stopAndAccumulate(_ timerId: GleanTimerId?)

    Parameters

    timerId

    The GleanTimerId to associate with this timing. This allows for concurrent timing of events associated with different ids to the same timespan metric.

  • Abort a previous start() call. No error is recorded if no start() was called.

    Declaration

    Swift

    public func cancel(_ timerId: GleanTimerId?)

    Parameters

    timerId

    The GleanTimerId to associate with this timing. This allows for concurrent timing of events associated with different ids to the same timing distribution metric.

  • Convenience method to simplify measuring a function or block of code

    Declaration

    Swift

    public func measure<U>(funcToMeasure: () -> U) -> U

    Parameters

    funcToMeasure

    Accepts a function or closure to measure that can return a value

  • Convenience method to simplify measuring a function or block of code

    If the measured function throws, the measurement is canceled and the exception rethrown.

    Declaration

    Swift

    public func measure<U>(funcToMeasure: () throws -> U) throws -> U

    Parameters

    funcToMeasure

    Accepts a function or closure to measure that can return a value

  • Tests whether a value is stored for the metric for testing purposes only. This function will attempt to await the last task (if any) writing to the the metric’s storage engine before returning a value.

    Declaration

    Swift

    public func testHasValue(_ pingName: String? = nil) -> Bool

    Parameters

    pingName

    represents the name of the ping to retrieve the metric for. Defaults to the first value in sendInPings.

    Return Value

    true if metric value exists, otherwise false.

  • Returns the stored value for testing purposes only. This function will attempt to await the last task (if any) writing to the the metric’s storage engine before returning a value.

    Throws a “Missing value” exception if no value is stored

    -parameters:

    • pingName: represents the name of the ping to retrieve the metric for. Defaults to the first value in sendInPings.

    Declaration

    Swift

    public func testGetValue(_ pingName: String? = nil) throws -> DistributionData

    Return Value

    value of the stored metric

  • Returns the number of errors recorded for the given metric.

    Declaration

    Swift

    public func testGetNumRecordedErrors(_ errorType: ErrorType, pingName: String? = nil) -> Int32

    Parameters

    errorType

    The type of error recorded.

    pingName

    represents the name of the ping to retrieve the metric for. Defaults to the first value in sendInPings.

    Return Value

    The number of errors recorded for the metric for the given error type.