/// <summary>
/// Collect and submit a ping for eventual upload by name.
///
/// The ping will be looked up in the known instances of `PingType`. If the
/// ping isn't known, an error is logged and the ping isn't queued for uploading.
///
/// The ping content is assembled as soon as possible, but upload is not
/// guaranteed to happen immediately, as that depends on the upload
/// policies.
///
/// If the ping currently contains no content, it will not be assembled and
/// queued for sending, unless explicitly specified otherwise in the registry
/// file.
/// </summary>
/// <param name="name">Name of the ping to submit.</param>
/// <param name="reason">The reason the ping is being submitted.</param>
internal void SubmitPingByName(string name, string reason = null)
{
Dispatchers.LaunchAPI(() =>
{
SubmitPingByNameSync(name, reason);
});
}
/// <summary>
/// Indicate that an experiment is running. Glean will then add an
/// experiment annotation to the environment which is sent with pings. This
/// information is not persisted between runs.
/// </summary>
/// <param name="experimentId">The id of the active experiment (maximum 100 bytes)</param>
/// <param name="branch">The experiment branch (maximum 100 bytes)</param>
/// <param name="extra">Optional metadata to output with the ping</param>
public void SetExperimentActive(string experimentId, string branch, Dictionary <string, string> extra = null)
{
// The Map is sent over FFI as a pair of arrays, one containing the
// keys, and the other containing the values.
string[] keys = null;
string[] values = null;
Int32 numKeys = 0;
if (extra != null)
{
// While the `ToArray` functions below could throw `ArgumentNullException`, this would
// only happen if `extra` (and `extra.Keys|Values`) is null. Which is not the case, since
// we're specifically checking this.
// Note that the order of `extra.Keys` and `extra.Values` is unspecified, but guaranteed
// to be the same. See
// https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.dictionary-2.values?view=netstandard-2.0#remarks
keys = extra.Keys.ToArray();
values = extra.Values.ToArray();
numKeys = extra.Count();
}
// We dispatch this asynchronously so that, if called before the Glean SDK is
// initialized, it doesn't get ignored and will be replayed after init.
Dispatchers.LaunchAPI(() => {
LibGleanFFI.glean_set_experiment_active(
experimentId,
branch,
keys,
values,
numKeys
);
});
}
/// <summary>
/// Indicate that an experiment is no longer running.
/// </summary>
/// <param name="experimentId">The id of the experiment to deactivate.</param>
public void SetExperimentInactive(string experimentId)
{
// We dispatch this asynchronously so that, if called before the Glean SDK is
// initialized, it doesn't get ignored and will be replayed after init.
Dispatchers.LaunchAPI(() => {
LibGleanFFI.glean_set_experiment_inactive(experimentId);
});
}
/// <summary>
/// Enable or disable Glean collection and upload.
///
/// Metric collection is enabled by default.
///
/// When uploading is disabled, metrics aren't recorded at all and no data
/// is uploaded.
///
/// When disabling, all pending metrics, events and queued pings are cleared
/// and a `deletion-request` is generated.
///
/// When enabling, the core Glean metrics are recreated.
/// </summary>
/// <param name="enabled">When `true`, enable metric collection.</param>
public void SetUploadEnabled(bool enabled)
{
if (!this.initFinished)
{
string msg = "Changing upload enabled before Glean is initialized is not supported.\n" +
"Pass the correct state into `Glean.initialize()`.\n" +
"See documentation at https://mozilla.github.io/glean/book/user/general-api.html#initializing-the-glean-sdk";
Log.Error(msg);
return;
}
// Changing upload enabled always happens asynchronous.
// That way it follows what a user expect when calling it inbetween other calls:
// It executes in the right order.
//
// Because the dispatch queue is halted until Glean is fully initialized
// we can safely enqueue here and it will execute after initialization.
Dispatchers.LaunchAPI(() => {
bool originalEnabled = this.GetUploadEnabled();
LibGleanFFI.glean_set_upload_enabled(enabled);
if (!enabled)
{
// Cancel any pending workers here so that we don't accidentally upload or
// collect data after the upload has been disabled.
// TODO: metricsPingScheduler.cancel()
// Cancel any pending workers here so that we don't accidentally upload
// data after the upload has been disabled.
httpClient.CancelUploads();
}
if (!originalEnabled && enabled)
{
// If uploading is being re-enabled, we have to restore the
// application-lifetime metrics.
InitializeCoreMetrics();
}
if (originalEnabled && !enabled)
{
// If uploading is disabled, we need to send the deletion-request ping
httpClient.TriggerUpload(configuration);
}
});
}
/// <summary>
/// Enable or disable Glean collection and upload.
///
/// Metric collection is enabled by default.
///
/// When uploading is disabled, metrics aren't recorded at all and no data
/// is uploaded.
///
/// When disabling, all pending metrics, events and queued pings are cleared
/// and a `deletion-request` is generated.
///
/// When enabling, the core Glean metrics are recreated.
/// </summary>
/// <param name="enabled">When `true`, enable metric collection.</param>
public void SetUploadEnabled(bool enabled)
{
if (IsInitialized())
{
bool originalEnabled = GetUploadEnabled();
Dispatchers.LaunchAPI(() => {
LibGleanFFI.glean_set_upload_enabled(enabled);
if (!enabled)
{
// Cancel any pending workers here so that we don't accidentally upload or
// collect data after the upload has been disabled.
// TODO: metricsPingScheduler.cancel()
// Cancel any pending workers here so that we don't accidentally upload
// data after the upload has been disabled.
httpClient.CancelUploads();
}
if (!originalEnabled && enabled)
{
// If uploading is being re-enabled, we have to restore the
// application-lifetime metrics.
InitializeCoreMetrics();
}
if (originalEnabled && !enabled)
{
// If uploading is disabled, we need to send the deletion-request ping
httpClient.TriggerUpload(configuration);
}
});
}
else
{
uploadEnabled = enabled;
}
}
