// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.systemmetrics.test;

/// Errors associated with SystemMetricsLogger methods.
type SystemMetricsLoggerError = strict enum : uint32 {
    /// Indicates that an invalid argument was provided.
    INVALID_ARGUMENT = 1;
    /// Requests to start logging will fail if logging is already active.
    ALREADY_LOGGING = 2;
};

/// A protocol for managing on-demand system metrics logging.
@discoverable
protocol SystemMetricsLogger {
    /// Initiates logging at the specified interval, for the provided duration. Logging may be
    /// terminated early with a call to `StopLogging`.
    ///
    /// This call will fail if logging is already active. For this reason, a client may wish to
    /// precede a `StartLogging` call with a `StopLogging` call, after which the only reason for the
    /// logger to be active would be a conflict with another client.
    ///
    /// + request `interval_ms` Length of the polling interval in milliseconds; must be positive.
    /// + request `duration_ms` Duration of logging in milliseconds; must be positive and larger
    ///     than `interval_ms`. After this duration, polling and logging will cease.
    /// + error a [fuchsia.systemmetrics.test/SystemMeticsLoggerError] value indicating why the
    ///     request failed.
    StartLogging(struct {
        interval_ms uint32;
        duration_ms uint32;
    }) -> (struct {}) error SystemMetricsLoggerError;

    /// Initiates logging at the specifed interval. Logging will only end upon a `StopLogging` call.
    ///
    /// `StartLogging` should be preferred for usage in automated tests to ensure that logging
    /// terminates even if the test crashes.
    ///
    /// + request `interval_ms` Length of the polling interval in milliseconds; must be positive.
    /// + error a [fuchsia.systemmetrics.test/SystemMetricsLoggerError] value indicating why the
    ///     request failed.
    StartLoggingForever(struct {
        interval_ms uint32;
    }) -> (struct {}) error SystemMetricsLoggerError;

    /// Terminates logging if active. It is valid to call this method when logging is inactive.
    StopLogging() -> ();
};