cobalt/h5vcc/h5vcc_metrics.idl

// Copyright 2023 The Cobalt Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Defines an interface to support interactions with Cobalt metric logging.
// For example, a callback API such that the web client can intercept and
// process metrics sent from Cobalt.

interface H5vccMetrics {
  // Interface for web client to bind an event handler that will be invoked
  // every time Cobalt wants to upload a metrics payload. Only one event
  // handler callback can be registered at any time. Duplicate calls to
  // onMetricEvent will override any previously registered callback.
  //
  // Example usage in JS:
  //
  //   window.h5vcc.metrics.onMetricEvent((metricType, payload) => {
  //     if (metricType == 'UMA') {
  //       // log UMA payload here...
  //     }
  //   });
  void onMetricEvent(H5vccMetricEventHandler eventHandler);

  // Enable Cobalt metrics logging. Metrics are disabled by default and should
  // be enabled as soon as possible. When enabled, at regular intervals, the
  // bound onMetricEvent callback will be called with telemetry payloads to
  // be uploaded and logged on the server.
  // TODO(b/286898092): Update docs here when setting is persistent.
  void enable();

  // Disable Cobalt metrics logging. If disabled, the metric event handler
  // should never get called afterward.
  void disable();

  // Returns the current enabled state of metrics reporting.
  boolean isEnabled();

  // Sets the frequency in which Cobalt metrics will be snapshotted and sent to
  // the metric event handler. Defaults to 5 minutes if not set. Must be > 0,
  // else will be ignored.
  void setMetricEventInterval(unsigned long intervalSeconds);
};

// Callback invoked when a new metric payload is ready to be published. The
// payload is a serialized protobuf and the metric type should give the consumer
// a hint on how to deserialize it. See h5vcc_metric_type.idl for more info.
callback H5vccMetricEventHandler =
    void(H5vccMetricType metricType, DOMString metricPayload);