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 == 'COBALT_UMA') {
  //       // log Cobalt 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. Both the enable/disable settings
  // are persistent or "sticky". That is, you only have to call them once
  // and that setting will persist through multiple app lifecycles until the
  // enable/disable APIs are explicitly called again.
  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. Note, the enable()
  // and disable() APIs are asynchronous under the hood. This means if you call
  // isEnabled() immediately after enable/disable, you may get unexpected
  // results.
  // TODO(b/290064552): Update this when H5vccMetrics APIs support async
  // behavior.
  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. This setting is persistent. That is, it's "sticky"
  // and will be persisted through multiple app lifetimes unless it's called
  // again with a different value.
  void setMetricEventInterval(unsigned long intervalSeconds);
};

// Callback invoked when a new metric payload is ready to be published. The
// payload is a base64 encoded 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);