Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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
#ifndef mozilla_glean_JOG_h
#define mozilla_glean_JOG_h
#include "nsStringFwd.h"
#include "nsTArray.h"
#include "mozilla/Maybe.h"
namespace mozilla::glean {
class JOG {
public:
/**
* Returns whether JOG knows about a category by this name
*
* @param aCategoryName The category name to check.
*
* @returns true if JOG is aware of a category by the given name at this time
*/
static bool HasCategory(const nsACString& aCategoryName);
/**
* Runs the runtime registrar.
*
* Locates the runtime metrics file and, if present, loads and processes it.
*
* Only does any work at all if !mozilla::IsPackagedBuild()
*
* **Note:** When this function does something, it is expensive, running
* synchronous file I/O to ensure that the registration is complete when this
* call returns.
*
* @param aForce Set to `true` if you want to force the I/O to run. Defaults
* to `false`, which doesn't run the I/O if it's already run and
* returns the previous return value.
* @returns whether it found the runtime metrics file and succesfully loaded,
* processed, and registered the described metrics.
*/
static bool EnsureRuntimeMetricsRegistered(bool aForce = false);
/**
* Returns whether, if a metric is absent in the runtime-registered metrics,
* you should check the compile-time-registered metrics.
*
* Runtime-registered metrics can either replace all compile-time-registered
* metrics (like in artefact builds) or just be supplementing compile-time-
* registered metrics (like addons/dynamic telemetry/etc).
*
* This is tied to the current state of runtime metric registration. So it
* may return false at one time and true later (e.g. if RuntimeRegistrar is
* run in between).
*
* @return true if you should treat the runtime-registered metrics as
* authoritative and comprehensive.
*/
static bool AreRuntimeMetricsComprehensive();
/**
* Adds the runtime-registered metrics' categories to `aNames`.
*
* @param aNames The list to add the categories' names to.
*/
static void GetCategoryNames(nsTArray<nsString>& aNames);
/**
* Get the metric id+type in a u32 for a named runtime-registered metric.
*
* Return value's only useful to GleanJSMetricsLookup.h
*
* @param aMetricName The `myCategory.myName` dotted.camelCase metric name.
* @return Nothing() if no metric by that name was registered at runtime.
* Otherwise, the encoded u32 with metric id and metric type id for
* the runtime-registered metric.
*/
static Maybe<uint32_t> GetMetric(const nsACString& aMetricName);
/**
* Get the metric name for an identified runtime-registered metric.
*
* @param aMetricId The id of the runtime-registered metric.
* @return Nothing() if no metric by that id has been registered.
* Otherwise, the `myCategory.myName` dotted.camelCase metric name of
* the runtime-registered metric.
*/
static Maybe<nsCString> GetMetricName(uint32_t aMetricId);
/**
* Adds `aCategoryName`'s runtime-registered metrics' names to `aNames`.
*
* @param aCategoryName The name of the category we want the metric names for.
* @param aNames The list to add the metrics' names to.
*/
static void GetMetricNames(const nsACString& aCategoryName,
nsTArray<nsString>& aNames);
/**
* Get the ping id in a u32 for a named runtime-registered ping.
*
* Return value's only useful to GleanJSPingsLookup.h
*
* @param aPingName The ping name.
* @return Nothing() if no ping by that name was registered at runtime.
* Otherwise, the id for the runtime-registered ping.
*/
static Maybe<uint32_t> GetPing(const nsACString& aPingName);
/**
* Adds the runtime-registered pings' names to `aNames`.
*
* @param aNames The list to add the pings' names to.
*/
static void GetPingNames(nsTArray<nsString>& aNames);
};
} // namespace mozilla::glean
#endif /* mozilla_glean_JOG_h */