path: root/dom/webidl/GleanMetrics.webidl

/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/.
 */

// The definitions in this file are not sorted.
// Please add new ones to the bottom.

/**
 * Base interface for all metric types to make typing more expressive.
 */
[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanMetric {};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanBoolean : GleanMetric {
  /**
   * Set to the specified boolean value.
   *
   * @param value the value to set.
   */
  undefined set(boolean value);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a boolean.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  boolean? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanDatetime : GleanMetric {
  /**
   * Set the datetime to the provided value, or the local now.
   * The internal value will store the local timezone.
   *
   * Note: The metric's time_unit affects the resolution of the value, not the
   *       unit of this function's parameter (which is always PRTime/nanos).
   *
   * @param aValue The (optional) time value as PRTime (nanoseconds since epoch).
   *        Defaults to local now.
   */
  undefined set(optional long long aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a Date.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric as a JS Date with timezone,
   *         or null if there is no value.
   */
  [Throws, ChromeOnly]
  any testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanCounter : GleanMetric {
  /*
   * Increases the counter by `amount`.
   *
   * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
   */
  undefined add(optional long aAmount = 1);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as an integer.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  long? testGetValue(optional UTF8String aPingName = "");
};

dictionary GleanDistributionData {
  required unsigned long long sum;
  required unsigned long long count;
  required record<UTF8String, unsigned long long> values;
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanTimingDistribution : GleanMetric {
  /**
   * Starts tracking time for the provided metric.
   *
   * @returns A unique timer id for the new timer
   */
  unsigned long long start();

  /**
   * Stops tracking time for the provided metric and timer id.
   *
   * Adds a count to the corresponding bucket in the timing distribution.
   * This will record an error if no `start` was called for this TimerId or
   * if this TimerId was used to call `cancel`.
   *
   * @param aId The TimerId associated with this timing. This allows for
   *            concurrent timing of events associated with different ids.
   */
  undefined stopAndAccumulate(unsigned long long aId);

  /**
   * Aborts a previous `start` call. No error is recorded if no `start` was
   * called. (But then where did you get that id from?)
   *
   * @param aId The TimerID whose `start` you wish to abort.
   */
  undefined cancel(unsigned long long aId);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  GleanDistributionData? testGetValue(optional UTF8String aPingName = "");

  /**
   * **Test-only API**
   *
   * Accumulates a raw numeric sample of milliseconds.
   *
   * @param aSample The sample, in milliseconds, to add.
   */
  [ChromeOnly]
  undefined testAccumulateRawMillis(unsigned long long aSample);
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanMemoryDistribution : GleanMetric {
  /**
   * Accumulates the provided signed sample in the metric.
   *
   * @param aSample The sample to be recorded by the metric. The sample is
   *                assumed to be in the confgured memory unit of the metric.
   *
   * Notes: Values bigger than 1 Terabyte (2^40 bytes) are truncated and an
   * InvalidValue error is recorded.
   */
  undefined accumulate(unsigned long long aSample);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a DistributionData.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanCustomDistribution : GleanMetric {
  /**
   * Accumulates the provided signed samples in the metric.
   *
   * @param aSamples - The vector holding the samples to be recorded by the metric.
   *
   * Notes: Discards any negative value in `samples`
   * and report an `ErrorType::InvalidValue` for each of them.
   */
  undefined accumulateSamples(sequence<long long> aSamples);

  /**
   * Accumulates the provided single signed sample in the metric.
   *
   * @param aSample - The sample to be recorded by the metric.
   *
   * Notes: Discards any negative value of `sample` and reports an
   * `ErrorType::InvalidValue`.
   */
  undefined accumulateSingleSample(long long aSample);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a DistributionData.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanString : GleanMetric {
  /**
   * Set the string to the provided value.
   *
   * @param aValue The string to set the metric to.
   */
  undefined set(UTF8String? aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a string.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  UTF8String? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanStringList : GleanMetric {
  /**
   * Adds a new string to the list.
   *
   * Truncates the value and logs an error if it is longer than 100 bytes.
   *
   * @param value The string to add.
   */
  undefined add(UTF8String value);

  /**
   * Sets the string_list to the provided list of strings.
   *
   * Truncates the list and logs an error if longer than 100 items.
   * Truncates any item longer than 100 bytes and logs an error.
   *
   * @param aValue The list of strings to set the metric to.
   */
  undefined set(sequence<UTF8String> aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  sequence<UTF8String>? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanTimespan : GleanMetric {
  /**
   * Start tracking time for the provided metric.
   *
   * This records an error if it’s already tracking time (i.e. start was already
   * called with no corresponding [stop]): in that case the original
   * start time will be preserved.
   */
  undefined start();

  /**
   * Stop tracking time for the provided metric.
   *
   * Sets the metric to the elapsed time, but does not overwrite an already
   * existing value.
   * This will record an error if no [start] was called or there is an already
   * existing value.
   */
  undefined stop();

  /**
   * Aborts a previous start.
   *
   * Does not record an error if there was no previous call to start.
   */
  undefined cancel();

  /**
   * Explicitly sets the timespan value.
   *
   * This API should only be used if you cannot make use of
   * `start`/`stop`/`cancel`.
   *
   * @param aDuration The duration of this timespan, in units matching the
   *        `time_unit` of this metric's definition.
   */
  undefined setRaw(unsigned long aDuration);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  unsigned long long? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanUuid : GleanMetric {
  /**
   * Set to the specified value.
   *
   * @param aValue The UUID to set the metric to.
   */
  undefined set(UTF8String aValue);

  /**
   * Generate a new random UUID and set the metric to it.
   */
  undefined generateAndSet();

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  UTF8String? testGetValue(optional UTF8String aPingName = "");
};

dictionary GleanEventRecord {
  required unsigned long long timestamp;
  required UTF8String category;
  required UTF8String name;
  record<UTF8String, UTF8String> extra;
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanEvent : GleanMetric {

  /*
   * Record an event.
   *
   * @param aExtra An (optional) map of extra values.
   */
  undefined _record(optional record<UTF8String, UTF8String?> aExtra);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   *
   * The difference between event timestamps is in milliseconds
   * See https://mozilla.github.io/glean/book/user/metrics/event.html for further details.
   * Due to limitations of numbers in JavaScript, the timestamp will only be accurate up until 2^53.
   * (This is probably not an issue with the current clock implementation. Probably.)
   */
  [Throws, ChromeOnly]
  sequence<GleanEventRecord>? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanQuantity : GleanMetric {
  /**
   * Set to the specified value.
   *
   * @param aValue The value to set the metric to.
   */
  undefined set(long long aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  long long? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanDenominator : GleanMetric {
  /*
   * Increases the counter by `aAmount`.
   *
   * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
   */
  undefined add(optional long aAmount = 1);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as an integer.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  long? testGetValue(optional UTF8String aPingName = "");
};

dictionary GleanRateData {
  required long numerator;
  required long denominator;
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanNumerator : GleanMetric {
  /*
   * Increases the numerator by `aAmount`.
   *
   * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
   */
  undefined addToNumerator(optional long aAmount = 1);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value in the form {numerator: n, denominator: d}
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  GleanRateData? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanRate : GleanMetric {
  /*
   * Increases the numerator by `amount`.
   *
   * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
   */
  undefined addToNumerator(optional long aAmount = 1);

  /*
   * Increases the denominator by `amount`.
   *
   * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
   */
  undefined addToDenominator(optional long aAmount = 1);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value in the form {numerator: n, denominator: d}
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  GleanRateData? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanUrl : GleanMetric {
  /**
   * Set to the specified value.
   *
   * @param aValue The stringified URL to set the metric to.
   */
  undefined set(UTF8String aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  UTF8String? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanText : GleanMetric {
  /**
   * Set to the provided value.
   *
   * @param aValue The text to set the metric to.
   */
  undefined set(UTF8String aValue);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as a string.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or null if there is no value.
   */
  [Throws, ChromeOnly]
  UTF8String? testGetValue(optional UTF8String aPingName = "");
};

[Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
interface GleanObject : GleanMetric {
  /**
   * Set to the specified object.
   *
   * The structure of the metric is validated against the predefined structure.
   *
   * @param object The object to set the metric to.
   */
  undefined set(object value);

  /**
   * **Test-only API**
   *
   * Gets the currently stored value as an object.
   *
   * This function will attempt to await the last parent-process task (if any)
   * writing to the the metric's storage engine before returning a value.
   * This function will not wait for data from child processes.
   *
   * This doesn't clear the stored value.
   * Parent process only. Panics in child processes.
   *
   * @param aPingName The (optional) name of the ping to retrieve the metric
   *        for. Defaults to the first value in `send_in_pings`.
   *
   * @return value of the stored metric, or undefined if there is no value.
   */
  [Throws, ChromeOnly]
  object? testGetValue(optional UTF8String aPingName = "");
};