Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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,
*/
// 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
* 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 = "");
};