diff options
Diffstat (limited to 'toolkit/components/glean/xpcom/nsIGleanMetrics.idl')
| -rw-r--r-- | toolkit/components/glean/xpcom/nsIGleanMetrics.idl | 696 |
1 files changed, 696 insertions, 0 deletions
diff --git a/toolkit/components/glean/xpcom/nsIGleanMetrics.idl b/toolkit/components/glean/xpcom/nsIGleanMetrics.idl new file mode 100644 index 0000000000..fff0bf1c61 --- /dev/null +++ b/toolkit/components/glean/xpcom/nsIGleanMetrics.idl @@ -0,0 +1,696 @@ +/* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */ +/* 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/. */ + +#include "nsISupports.idl" + +[scriptable, uuid(d3180fe0-19fa-11eb-8b6f-0800200c9a66)] +interface nsIGleanBoolean : nsISupports +{ + /** + * Set to the specified boolean value. + * + * @param value the value to set. + */ + void set(in bool 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 undefined if there is no value. + */ + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(aa15fd20-1e8a-11eb-9bec-0800200c9a66)] +interface nsIGleanDatetime : nsISupports +{ + /** + * 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. + */ + [optional_argc] + void set([optional] in PRTime aValue); + + /** + * **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 as a JS Date with timezone, + * or undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(05b89d2a-d57c-11ea-82da-3f63399a6f5a)] +interface nsIGleanCounter : nsISupports +{ + /* + * Increases the counter by `amount`. + * + * @param amount The amount to increase by. Should be positive. + */ + void add(in int32_t amount); + + /** + * **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 undefined if there is no value. + */ + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(92e14730-9b5f-45a1-b018-f588d0b964d8)] +interface nsIGleanTimingDistribution : nsISupports +{ + /** + * Starts tracking time for the provided metric. + * + * @returns A unique timer id for the new timer + */ + [implicit_jscontext] + jsval 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. + */ + void stopAndAccumulate(in uint64_t 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. + */ + void cancel(in uint64_t aId); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in ACString aPingName); + + /** + * **Test-only API** + * + * Accumulates a raw numeric sample of milliseconds. + * + * Test-only until we find a use-case and decent JS Time Duration type. + * + * @param aSample The sample, in milliseconds, to add. + */ + void testAccumulateRawMillis(in uint64_t aSample); +}; + +[scriptable, uuid(eea5ed46-16ba-46cd-bb1f-504581987fe1)] +interface nsIGleanMemoryDistribution : nsISupports +{ + /* + * Accumulates the provided 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. + */ + void accumulate(in uint64_t 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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in ACString aPingName); +}; + +[scriptable, uuid(45cc016f-c1d5-4d54-aaa5-a802cf65f23b)] +interface nsIGleanCustomDistribution : nsISupports +{ + /* + * 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. + */ + void accumulateSamples(in Array<int64_t> aSamples); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in ACString aPingName); +}; + +[scriptable, function, uuid(e5447f62-4b03-497c-81e9-6ab683d20380)] +interface nsIGleanPingTestCallback : nsISupports +{ + void call(in ACString aReason); +}; + +[scriptable, uuid(5223a48b-687d-47ff-a629-fd4a72d1ecfa)] +interface nsIGleanPing : nsISupports +{ + /** + * Collect and submit the ping for eventual upload. + * + * This will collect all stored data to be included in the ping. + * Data with lifetime `ping` will then be reset. + * + * If the ping is configured with `send_if_empty = false` + * and the ping currently contains no content, + * it will not be queued for upload. + * If the ping is configured with `send_if_empty = true` + * it will be queued for upload even if empty. + * + * Pings always contain the `ping_info` and `client_info` sections. + * See [ping sections](https://mozilla.github.io/glean/book/user/pings/index.html#ping-sections) + * for details. + * + * @param aReason - Optional. The reason the ping is being submitted. + * Must match one of the configured `reason_codes`. + */ + void submit([optional] in ACString aReason); + + /** + * **Test-only API** + * + * Register a callback to be called right before this ping is next submitted. + * The provided function is called exactly once before submitting. + * + * Note: The callback will be called on any call to submit. + * A ping might not be sent afterwards, e.g. if the ping is empty and + * `send_if_empty` is `false`. + * + * @param aCallback - The callback to call on the next submit. + */ + void testBeforeNextSubmit(in nsIGleanPingTestCallback aCallback); +}; + +[scriptable, uuid(d84a3555-46f1-48c1-9122-e8e88b069d2b)] +interface nsIGleanString : nsISupports +{ + /* + * Set to the specified value. + * + * @param value The string to set the metric to. + */ + void set(in AUTF8String value); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(46751205-2ac7-47dc-91d2-ef4a95ef2af9)] +interface nsIGleanStringList : nsISupports +{ + /** + * Adds a new string to the list. + * + * Truncates the value and logs an error if it is longer than 50 bytes. + * + * @param value The string to add. + */ + void add(in AUTF8String value); + + /** + * Sets to a specific list of strings. + * + * Truncates the list and logs an error if longer than 20 items. + * Truncates any item longer than 50 bytes and logs an error. + * + * @param value The list of strings to set. + */ + void set(in Array<AUTF8String> value); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(2586530c-030f-11eb-93cb-cbf30d25225a)] +interface nsIGleanTimespan : nsISupports +{ + /** + * 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. + */ + void 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. + */ + void stop(); + + /** + * Aborts a previous start. + * + * Does not record an error if there was no previous call to start. + */ + void 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. + */ + void setRaw(in uint32_t aDuration); + + /** + * **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 undefined if there is no value. + */ + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(395700e7-06f6-46be-adcc-ea58977fda6d)] +interface nsIGleanUuid : nsISupports +{ + /** + * Set to the specified value. + * + * @param aValue The UUID to set the metric to. + */ + void set(in AUTF8String aValue); + + /** + * Generate a new random UUID and set the metric to it. + */ + void generateAndSet(); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(1b01424a-1f55-11eb-92a5-0754f6c3f240)] +interface nsIGleanEvent : nsISupports +{ + /* + * Record an event. + * + * @param aExtra An (optional) map of extra values. + */ + [implicit_jscontext] + void record([optional] in jsval aExtra); + + /** + * **Test-only API** + * + * Get a list of currently stored events for this event metric. + * + * 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. + * + * The data is an array of objects: + * + * ``` + * [ + * { + * timestamp: Integer, + * category: String, + * name: String, + * extra: { + * String: String + * ... + * } + * }, + * ... + * ] + * ``` + * + * 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.) + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(0558c1b2-2cb1-4e21-a0a0-6a91a35ef219)] +interface nsIGleanQuantity : nsISupports +{ + /** + * Set to the specified value. + * + * @param value the value to set. + */ + void set(in int64_t value); + + /** + * **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 undefined if there is no value. + */ + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(394d9d3b-9e7e-48cc-b76c-a89a51830da3)] +interface nsIGleanDenominator : nsISupports +{ + /* + * Increases the counter by `amount`. + * + * @param amount The amount to increase by. Should be positive. + */ + void add(in int32_t amount); + + /** + * **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 undefined if there is no value. + */ + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(153fff71-7edd-49b4-a166-4697aa89c7a1)] +interface nsIGleanNumerator : nsISupports +{ + /* + * Increases the numerator by `amount`. + * + * @param amount The amount to increase by. Should be positive. + */ + void addToNumerator(in int32_t amount); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(920cf631-2b1e-4efe-ae2e-f03277c3112a)] +interface nsIGleanRate : nsISupports +{ + /* + * Increases the numerator by `amount`. + * + * @param amount The amount to increase by. Should be positive. + */ + void addToNumerator(in int32_t amount); + + /* + * Increases the denominator by `amount`. + * + * @param amount The amount to increase by. Should be positive. + */ + void addToDenominator(in int32_t amount); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(a59672c4-bc48-4bfe-8f9c-6f408a59d819)] +interface nsIGleanUrl : nsISupports +{ + /* + * Sets to the specified stringified URL. + * + * @param value The stringified URL to set the metric to. + */ + void set(in AUTF8String value); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; + +[scriptable, uuid(fafceafb-c3a0-4424-b3b9-b7bd487f6bb4)] +interface nsIGleanText : nsISupports +{ + /* + * Set to the specified value. + * + * @param value The text to set the metric to. + */ + void set(in AUTF8String value); + + /** + * **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 undefined if there is no value. + */ + [implicit_jscontext] + jsval testGetValue([optional] in AUTF8String aPingName); +}; |