/* -*- 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(98d0e975-9cad-4ce3-ae2f-f878b8be6307)] interface nsIFOG : nsISupports { /** * Initialize FOG. * * Call it eventually. Metric data recorded beforehand will be buffered. * * @param aDataPathOverride - The path of a custom Glean data path to use * instead of the profile dir. * @param aAppIdOverride - The application_id to use instead of * "firefox.desktop". * @param aDisableInternalPings - Whether to disable internal pings (baseline, events, metrics). * Default: false. */ void initializeFOG([optional] in AUTF8String aDataPathOverride, [optional] in AUTF8String aAppIdOverride, [optional] in boolean aDisableInternalPings); /** * Register custom pings. * * Ensure all custom pings are registered with Glean. */ void registerCustomPings(); /** * Enable or Disable the logging of pings in the Glean SDK. * See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html * for details. * * @param aEnableLogPings - true to enable logging, false to disable. */ void setLogPings(in boolean aEnableLogPings); /** * Set the tag to be applied to pings assembled from now on. * See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html * for details. * * @param aDebugTag - The string tag to apply. * If it cannot be applied (e.g it contains characters that are * forbidden in HTTP headers) the old value will remain. */ void setTagPings(in ACString aDebugTag); /** * Send the named ping. * See https://firefox-source-docs.mozilla.org/toolkit/components/glean/dev/testing.html * for details. * * @param aPingName - The name of the ping to send. If no ping of that name * exists, or the ping is known but cannot be assembled * (e.g if it is empty), no ping will be sent. */ void sendPing(in ACString aPingName); /** * Indicate that an experiment is running. * Glean will add an experiment annotation which is sent with pings. * This information is not persisted between runs. * * See `glean_core::Glean::set_experiment_active`. * * Logs on error, but does not throw. * * @param aExperimentId - The id/slug of the experiment. * @param aBranch - The name of the active branch of the experiment. * @param aExtra - Optional string -> string dictionary of extra information. */ [implicit_jscontext] void setExperimentActive(in ACString aExperimentId, in ACString aBranch, [optional] in jsval aExtra); /** * Indicate that an experiment is no longer running. * * See `glean_core::Glean::set_experiment_inactive`. * * Logs on error, but does not throw. * * @param aExperimentId - The id/slug of the experiment from setExperimentActive. */ void setExperimentInactive(in ACString aExperimentId); /** * **Test-only API** * * If the identified experiment was set active and hasn't been set inactive, * this will give you the active branch and extra information. * * @param aExperimentId - The id/slug of the experiment from setExperimentActive. * * @return an object of the form * {branch: "branch-name", extra: {extra_key1: extra_value1, ...}} * if there is an active experiment. Undefined, otherwise. */ [implicit_jscontext] jsval testGetExperimentData(in ACString aExperimentId); /** * Set remote-configuration for metrics' disabled property. * * See [`glean_core::Glean::set_metrics_enabled_config`] * * Logs on error, but does not throw. * * @param aJsonConfig - The stringified JSON object in the form * {metric_base_identifier: boolean,} * which may contain multiple metric object entries. */ void applyServerKnobsConfig(in ACString aJsonConfig); /** * ** Test-only Method ** * * Flush all data from all child processes. * * @returns A promise that resolves when the data's been stored. */ [implicit_jscontext] Promise testFlushAllChildren(); /** * ** Test-only Method ** * * Reset FOG and the Glean SDK, clearing storage. */ void testResetFOG([optional] in AUTF8String aDataPathOverride, [optional] in AUTF8String aAppIdOverride); /** * ** Test-only Method ** * * Trigger test metric instrumentation on the GPU, RDD or Socket process. * * @param aProcessType - A PROCESS_TYPE_* value from the constants defined * in the nsIXULRuntime interface. * * @returns A promise that resolves when the test data has been added. * The promise will be rejected if the process type is not supported * or if sending the IPC to the child process fails. */ [implicit_jscontext] Promise testTriggerMetrics(in unsigned long aProcessType); /** * ** Test-only Method ** * * Register a metric. * * This function is deliberately not too friendly to use. You probably aren't * supposed to use it unless you're testing metric registration itself. * * @param aType - The metric's type. * @param aCategory - The metric's category. * @param aName - The metric's name. * @param aPings - The pings to send it in. * @param aLifetime - The metric's lifetime. * @param aDisabled - Whether the metric, though existing, isn't enabled. * @param aExtraArgs - Optional JSON string of extra args. */ uint32_t testRegisterRuntimeMetric(in ACString aType, in ACString aCategory, in ACString aName, in Array aPings, in ACString aLifetime, in boolean aDisabled, [optional] in ACString aExtraArgs); /** * ** Test-only Method ** * * Register a ping. * * This function is deliberately not too friendly to use. You probably aren't * supposed to use it unless you're testing ping registration itself. * * @param aName - The ping's name. * @param aIncludeClientId - Whether the ping should include the client_id. * @param aSendIfEmpty - Whether the ping should send even if empty. * @param aIncludeInfoSections - Whether the ping should include * {client|ping}_info sections. * TODO(jer): docs * @param aReasonCodes - The list of valid reasons for ping submission. */ uint32_t testRegisterRuntimePing(in ACString aName, in boolean aIncludeClientId, in boolean aSendIfEmpty, in boolean aPreciseTimestamps, in boolean aIncludeInfoSections, in boolean aEnabled, in Array aSchedulesPings, in Array aReasonCodes, in boolean aFollowsCollectionEnabled, in Array aUploaderCapabilities); /** * Update the core attribution metrics in Glean. * * @param aSource - The product's attribution source (e.g. "google-play"). * @param aMedium - The product's attribution medium (e.g. "organic" for a search engine). * @param aCampaign - The product's attribution campaign (e.g. "mozilla-org"). * @param aTerm - The product's attribution term (e.g. "browser with developer tools for android"). * @param aContent - The product's attribution content (e.g. "firefoxview"). */ void updateAttribution(in ACString aSource, in ACString aMedium, in ACString aCampaign, in ACString aTerm, in ACString aContent); /** * ** Test-only Method ** * * Returns the core attribution data from Glean. * * @returns the core attribution data from Glean in the form * `{source, medium, campaign, term, content}`. */ [implicit_jscontext] jsval testGetAttribution(); /** * Update the core distribution metrics in Glean. * * @param aName - The product's distribution name (e.g. "MozillaOnline"). */ void updateDistribution(in ACString aName); /** * ** Test-only Method ** * * Returns the core distribution data from Glean. * * @returns the core distribution data from Glean in the form `{name}`. */ [implicit_jscontext] jsval testGetDistribution(); /** * Creates and registers a metric as specified, * making it and its APIs available on the JS Glean global. * * Main process only. * * Not necessary for most uses of FOG and Glean. * If you're not sure if you should call this, * err on the side of not calling it. * * @param aType - The metric's type (e.g., "counter", "string", etc.) * @param aCategory - The metric's category (namespace) * @param aName - The metric's name * @param aPings - The pings to send this metric in * @param aLifetime - The metric's lifetime (e.g., "ping", "application", "user") * @param aDisabled - Whether the metric is disabled * @param aExtraArgs - Optional JSON string of additional configuration * @throws NS_ERROR_INVALID_ARG if required arguments are missing * @throws NS_ERROR_FAILURE if registration fails */ void registerRuntimeMetric(in ACString aType, in ACString aCategory, in ACString aName, in Array aPings, in ACString aLifetime, in boolean aDisabled, [optional] in ACString aExtraArgs); /** * Creates and registers a ping as specified, * making it and its APIs available on the JS GleanPings global. * * Main process only. * * Not necessary for most uses of FOG and Glean. * If you're not sure if you should call this, * err on the side of not calling it. * * @param aName - The ping's name * @param aIncludeClientId - Whether the ping should include the client_id * @param aSendIfEmpty - Whether the ping should send even if empty * @param aPreciseTimestamps - Whether to use precise timestamps * @param aIncludeInfoSections - Whether to include client_info and ping_info sections * @param aEnabled - Whether the ping is enabled * @param aSchedulesPings - Array of pings that this ping schedules * @param aReasonCodes - Array of valid reason codes for this ping * @param aFollowsCollectionEnabled - Whether this ping follows the collection enabled setting * @param aUploaderCapabilities - Array of capabilities that the uploader must support to handle this ping * @throws NS_ERROR_INVALID_ARG if required arguments are missing * @throws NS_ERROR_FAILURE if registration fails */ void registerRuntimePing(in ACString aName, in boolean aIncludeClientId, in boolean aSendIfEmpty, in boolean aPreciseTimestamps, in boolean aIncludeInfoSections, in boolean aEnabled, in Array aSchedulesPings, in Array aReasonCodes, in boolean aFollowsCollectionEnabled, in Array aUploaderCapabilities); };