// Copyright 2018 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.

#ifndef COBALT_LOGGER_LOGGER_INTERFACE_H_
#define COBALT_LOGGER_LOGGER_INTERFACE_H_

#include <memory>
#include <string>
#include <utility>
#include <vector>

#include "logger/encoder.h"
#include "logger/status.h"

namespace cobalt {
namespace logger {

// Logger is the client-facing interface to Cobalt.
//
// LoggerInterface is an abstract interface to Logger that allows Logger to
// be mocked out in tests.
class LoggerInterface {
 public:
  virtual ~LoggerInterface() = default;

  // Logs the fact that an event has occurred.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type EVENT_OCCURRED.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  virtual Status LogEvent(uint32_t metric_id, uint32_t event_code) = 0;

  // Logs that an event has occurred a given number of times.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type EVENT_COUNT.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  // |component| Optionally, a component associated with the event may also be
  // logged. Use the empty string if there is no natural notion of component.
  //
  // |period_duration_micros| Optionally, the period of time over which
  // the |count| events occurred may be logged. If this is not relevant the
  // value may be set to 0. Otherwise specify the period duration as a number
  // of microseconds.
  //
  // |count| The number of times the event occurred. One may choose to
  // always set this value to 1 and always set |period_duration_micros| to 0
  // in order to achieve a semantics similar to the LogEventOccurred() method,
  // but with a |component|.
  virtual Status LogEventCount(uint32_t metric_id, uint32_t event_code,
                               const std::string& component,
                               int64_t period_duration_micros,
                               uint32_t count) = 0;

  // Logs that an event lasted a given amount of time.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type ELAPSED_TIME.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  // |component| Optionally, a component associated with the event may also be
  // logged. Use the empty string if there is no natural notion of component.
  //
  // |elapsed_micros| The elapsed time of the event, specified as a number
  // of microseconds.
  virtual Status LogElapsedTime(uint32_t metric_id, uint32_t event_code,
                                const std::string& component,
                                int64_t elapsed_micros) = 0;

  // Logs a measured average frame rate.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type FRAME_RATE.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  // |component| Optionally, a component associated with the event may also be
  // logged. Use the empty string if there is no natural notion of component.
  //
  // |fps| The average-frame rate in frames-per-second.
  virtual Status LogFrameRate(uint32_t metric_id, uint32_t event_code,
                              const std::string& component, float fps) = 0;
  // Logs a measured memory usage.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type MEMORY_USAGE.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  // |component| Optionally, a component associated with the event may also be
  // logged. Use the empty string if there is no natural notion of component.
  //
  // |bytes| The memory used, in bytes.
  virtual Status LogMemoryUsage(uint32_t metric_id, uint32_t event_code,
                                const std::string& component,
                                int64_t bytes) = 0;

  // Logs a histogram over a set of integer buckets. The meaning of the
  // Metric and the buckets is specified in the Metric definition.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type INT_HISTOGRAM.
  //
  // |event_code| The index of the event type that occurred. The indexed
  // set of all event types is specified in the Metric definition. Use 0
  // if there is no natural notion of event type.
  //
  // |component| Optionally, a component associated with the event may also be
  // logged. Use the empty string if there is no natural notion of component.
  //
  // |histogram| The histogram to log. Each HistogramBucket gives the count
  //  for one bucket of the histogram. The definitions of the buckets is
  //  given in the Metric definition.
  virtual Status LogIntHistogram(uint32_t metric_id, uint32_t event_code,
                                 const std::string& component,
                                 HistogramPtr histogram) = 0;

  // Logs the fact that a given string was used, in a specific context.
  // The semantics of the context and the string is specified in the
  // Metric definition.
  //
  //  This method is intended to be used in the following situation:
  //  * The string s being logged does not contain PII or passwords.
  //  * The set S of all possible strings that may be logged is large.
  //    If the set S is small consider using LogEvent() instead.
  //  * The ultimate data of interest is the statistical distribution of the
  //    most commonly used strings from S over the population of all Fuchsia
  //    devices.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type STRING_USED.
  //
  // |str| The human-readable string to log.
  virtual Status LogString(uint32_t metric_id, const std::string& str) = 0;

  // Logs a custom event. The structure of the event is defined in a proto file
  // in the project's config folder.
  //
  // |metric_id| ID of the Metric the logged Event will belong to. It must
  // be one of the Metrics from the ProjectContext passed to the constructor,
  // and it must be of type CUSTOM.
  //
  // |event_values| The event to log. EventValues represent the contents of the
  // proto file that will be collected. Each ValuePart represents a single
  // dimension of the logged event. The conversion to proto is done  serverside,
  // therefore it is the client's responsibility to make sure the EventValues
  // contents match the proto defined.
  virtual Status LogCustomEvent(uint32_t metric_id,
                                EventValuesPtr event_values) = 0;
};

}  // namespace logger
}  // namespace cobalt

#endif  // COBALT_LOGGER_LOGGER_INTERFACE_H_