blob: add5085d638b2f988cec2a9001409a1ca0dc2cdb [file] [log] [blame]
// 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
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// 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);