public/lib/cobalt/cpp/cobalt_logger.h

// 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 LIB_COBALT_CPP_COBALT_LOGGER_H_
#define LIB_COBALT_CPP_COBALT_LOGGER_H_

#include <fuchsia/cobalt/cpp/fidl.h>
#include <lib/component/cpp/startup_context.h>
#include <zx/time.h>

namespace cobalt {

// If this class is used through multiple threads, it is the caller's
// responsibility to ensure that no task posted on the main thread will outlive
// this class.
class CobaltLogger {
 public:
  virtual ~CobaltLogger() = default;

  // Logs the fact that an event has occurred.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, 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.
  virtual void 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 to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, 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.
  //
  // |component| Optionally, a component associated with the event may
  //     also be logged. Any notion of component that makes sense may be
  //     used or use the empty string if there is no natural notion of
  //     component.
  //
  // |period_duration| 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.
  //
  //  |count| The number of times the event occurred. One may choose to
  //      always set this value to 1 and always set
  //     |period_duration| to 0 in order to achieve a semantics
  //     similar to the LogEvent() method, but with a |component|.
  virtual void LogEventCount(uint32_t metric_id, uint32_t event_code,
                             const std::string& component,
                             zx::duration period_duration, int64_t count) = 0;

  // Logs that an event lasted a given amount of time.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, 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.
  //
  // |component| Optionally, a component associated with the event may
  //     also be logged. Any notion of component that makes sense may be
  //     used or use the empty string if there is no natural notion of
  //     component.
  //
  // |elapsed_time| The elapsed time of the event.
  virtual void LogElapsedTime(uint32_t metric_id, uint32_t event_code,
                              const std::string& component,
                              zx::duration elapsed_time) = 0;

  // Logs a measured average frame rate.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type FRAME_RATE.
  //
  // |event_code| The index of the event type that associated with the
  //     frame-rate measurement. The indexed set of all event types is
  //     specified in the metric definition.
  //
  // |component| Optionally, a component associated with the frame-rate
  //     measurement may also be logged. Any notion of component that makes
  //     sense may be used or use the empty string if there is no natural
  //     notion of component.
  //
  // |fps| The average-frame rate in frames-per-second.
  virtual void 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 to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type MEMORY_USAGE.
  //
  // |event_code| The index of the event type associated with the memory
  //     usage. The indexed set of all event types is specified in the metric
  //     definition.
  //
  // |component| Optionally, a component associated with the memory usage
  //     may also be logged. Any notion of component that makes sense may be
  //     used or use the empty string if there is no natural notion of
  //     component.
  //
  // |bytes| The memory used, in bytes.
  virtual void LogMemoryUsage(uint32_t metric_id, uint32_t event_code,
                              const std::string& component, int64_t bytes) = 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 to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type STRING_USED.
  //
  // |s| The string to log. This should be a human-readable string of
  //      size no more than 256 bytes.
  virtual void LogString(uint32_t metric_id, const std::string& s) = 0;

  // This method is part of Cobalt's helper service for measuring the time
  // delta between two events that occur in different processes. This starts
  // the timer. A corresponding invocation of EndTimer() with the same
  // |timer_id| ends the timer. After both StartTimer() and EnvdTimer() have
  // been invoked, LogElapsedTime() will be invoked with the difference
  // between the end timestamp and the start timestamp as the value of
  // |duration_microseconds|. It is OK if Cobalt receives the EndTimer()
  // call before the StartTimer() call.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type ELAPSED_TIME.
  //
  // |event_code| The index of the event type to associate with the
  // elapsed time. This is passed to LogElapsedTime()
  //
  // |component| Optionally, a component associated with the event may
  //     also be logged. See the description at LogElapsedTime().
  //
  // |timer_id| The ID of the timer being started. This is an arbitrary
  //     non-empty string provided by the caller and it is the caller's
  //     responsibility to ensure that Cobalt receives a pair of
  //     StartTimer(), EndTimer() calls with this id before the timeout
  //     and without any intervening additional calls to StartTimer()
  //     or EndTimer() using the same id. Once such a pair is received
  //     Cobalt will delete the timer with this ID and after that the
  //     ID may be re-used.
  //
  // |timestamp| The timestamp to set as the start of the timer. The absolute
  // value does not matter, only the
  //     difference between the end and start timestamps will be used.
  //
  // |timeout| The duration Cobalt should wait to receive the
  //     corresponding EndTimer() call with the same |timer_id|. If
  //     Cobalt has already received the corresponding EndTimer() call
  //     before receiving this StartTimer() call then this value is
  //     ignored as the timeout has already been set by the EndTimer()
  //     call. If Cobalt does not receive the corresponding EndTimer()
  //     call before the timeout then the timer will be deleted and
  //     this invocation of StartTimer() will be forgotten. Must be a
  //     positive value less than 300 seconds.
  //
  // |status| Returns OK on success. There are two success cases:
  //     (i) Cobalt does not currently have any timers with the given
  //         timer_id. In that case this call creates a new timer with
  //         the given ID and start timestamp.
  //     (ii) Cobalt currently has a timer with the given timer_id for
  //         which it has received exactly one EndTimer() call and no
  //         StartTimer() calls. In this case Cobalt will delete the
  //         timer and invoke LogElapsedTime() using the difference
  //         between the end timestamp and the start timestamp as the
  //         value of |duration_micors|. It is ok if this value is
  //         negative.
  //     Returns INVALID_ARGUMENTS if |timer_id| is empty or the timeout
  //        is not positive and less than 5 minutes.
  //     Returns FAILED_PRECONDITION if Cobalt currently has a timer
  //        with the given timer_ID and it already has a start
  //        timestamp. In this case Cobalt will delete the timer with
  //        the given |timer_id| and this invocation of StartTimer()
  //        will be forgotten.
  //     Any error returned by LogElapsedTime() may also be returned by this
  //     method.
  virtual void StartTimer(uint32_t metric_id, uint32_t event_code,
                          const std::string& component,
                          const std::string& timer_id, zx::time timestamp,
                          zx::duration timeout) = 0;

  // This method is part of Cobalt's helper service for measuring the time
  // delta between two events that occur in different processes. This ends
  // the timer. A corresponding invocation of StartTimer() with the same
  // |timer_id| starts the timer. After both StartTimer() and EndTimer() have
  // been invoked, LogElapsedTime() will be invoked with the difference
  // between the end timestamp and the start timestamp as the value of
  // |duration_microseconds|. It is OK if Cobalt receives the EndTimer()
  // call before the StartTimer() call.
  //
  // |timer_id| The ID of the timer being ended. This is an arbitrary
  //     non-empty string provided by the caller and it is the caller's
  //     responsibility to ensure that Cobalt receives a pair of
  //     StartTimer(), EndTimer() calls with this id before the timeout
  //     and without any intervening additional calls to StartTimer()
  //     or EndTimer() using the same id. Once such a pair is received
  //     Cobalt will delete the timer with this ID and after that the
  //     ID may be re-used.
  //
  // |timestamp| The timestamp to set as the end of the timer. The absolute
  // value does not matter, only the
  //     difference between the end and start timestamps will be used.
  //
  // |timeout| The duration Cobalt should wait to receive the
  //     corresponding EndTimer() call with the same |timer_id|. If
  //     Cobalt has already received the corresponding EndTimer() call
  //     before receiving this StartTimer() call then this value is
  //     ignored as the timeout has already been set by the EndTimer()
  //     call. If Cobalt does not receive the corresponding EndTimer()
  //     call before the timeout then the timer will be deleted and
  //     this invocation of StartTimer() will be forgotten.
  //
  // |status| Returns OK on success. There are two success cases:
  //     (i) Cobalt does not currently have any timers with the given
  //         timer_id. In that case this call creates a new timer with
  //         the given ID and end timestamp.
  //     (ii) Cobalt currently has a timer with the given timer_id for
  //         which it has received exactly one StartTimer() call and no
  //         EndTimer() calls. In this case Cobalt will delete the
  //         timer and invoke LogElapsedTime() using the difference
  //         between the end timestamp and the start timestamp as the
  //         value of |duration_micors|. It is ok if this value is
  //         negative.
  //     Returns INVALID_ARGUMENTS if |timer_id| is empty or the timeout
  //        is not positive and less than 5 minutes.
  //     Returns FAILED_PRECONDITION if Cobalt currently has a timer
  //        with the given timer_ID and it already has an end
  //        timestamp. In this case Cobalt will delete the timer with
  //        the given |timer_id| and this invocation of EndTimer()
  //        will be forgotten.
  //     Any error returned by LogElapsedTime() may also be returned by this
  //     method.
  virtual void EndTimer(const std::string& timer_id, zx::time timestamp,
                        zx::duration timeout) = 0;

  // Logs a histogram over a set of integer buckets. The meaning of the
  // Metric and the buckets is specified in the Metric definition.
  //
  // This method is intended to be used in situations where the client
  // wishes to aggregate a large number of integer-valued measurements
  // *in-process*, prior to submitting the data to Cobalt.
  // One reason a client may wish to do this is that the measurements occur
  // with very high frequency and it is not practical to make a FIDL call
  // for each individual measurement.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type INT_HISTOGRAM.
  //
  // |event_code| The index of the event type associated with the
  // integer-valued measurement. The indexed set of all event types is
  // specified in the metric definition.
  //
  // |component| Optionally, a component associated with integer-valued
  //     measurements may also be logged. Any notion of component that makes
  //     sense may be used or 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 void LogIntHistogram(
      uint32_t metric_id, uint32_t event_code, const std::string& component,
      std::vector<fuchsia::cobalt::HistogramBucket> histogram) = 0;

  // Logs a custom Event. The semantics of the Metric are specified in the
  // Metric defintion.
  //
  // |metric_id| ID of the metric to use. It must be one of the Metrics
  // from the ProjectProfile used to create this CobaltLogger, and it must be of
  // type CUSTOM.
  //
  // |event_values| The values for the custom Event. There is one value for
  // each dimension of the Metric. The number and types of the values must
  // be consistent with the dimensions declared in the Metric definition.
  virtual void LogCustomEvent(
      uint32_t metric_id,
      std::vector<fuchsia::cobalt::CustomEventValue> event_values) = 0;
};

// Returns a CobaltLogger initialized with the provided parameters.
//
// |dispatcher| A pointer to an async_dispatcher_t to be used for all
// asynchronous operations.
//
// |context| A pointer to the StartupContext that provides access to the
// environment of the component using this CobaltLogger.
//
// |config_path| The path to the configuration file for the Cobalt project
// associated with the new Logger. This is a binary file containing the compiled
// definitions of the metrics and reports defined for the project. Usually this
// file is generated via the |cobalt_config| target in your BUILD file and
// included in your package via a |resources| clause in your |package|
// definition.
//
// |release_stage| Optional specification of the current release stage of the
// project associated with the new Logger. This determines which of the defined
// metrics are permitted to be collected. The default value of GA (Generally
// Available) permits only metrics tagged as GA.
std::unique_ptr<CobaltLogger> NewCobaltLogger(
    async_dispatcher_t* dispatcher, component::StartupContext* context,
    const std::string& config_path,
    fuchsia::cobalt::ReleaseStage release_stage =
        fuchsia::cobalt::ReleaseStage::GA);

// Returns a CobaltLogger initialized with the provided parameters.
//
// |dispatcher| A pointer to an async_dispatcher_t to be used for all
// asynchronous operations.
//
// |context| A pointer to the StartupContext that provides access to the
// environment of the component using this CobaltLogger.
//
// |profile| The ProjectProfile struct that contains the configuration for this
// CobaltLogger.
std::unique_ptr<CobaltLogger> NewCobaltLogger(
    async_dispatcher_t* dispatcher, component::StartupContext* context,
    fuchsia::cobalt::ProjectProfile profile);

}  // namespace cobalt

#endif  // LIB_COBALT_CPP_COBALT_LOGGER_H_