path: root/third_party/rust/glean-core/src/glean.udl

namespace glean {
    void glean_enable_logging();

    // Initialize the logging system to send JSON messages to a file descriptor
    // (Unix) or file handle (Windows).
    //
    // No-op on Android and iOS. Use `glean_enable_logging` instead.
    void glean_enable_logging_to_fd(u64 fd);

    // Initializes Glean.
    //
    // This will fully initialize Glean in a separate thread.
    // It will return immediately.
    void glean_initialize(InternalConfiguration cfg, ClientInfoMetrics client_info, OnGleanEvents callbacks);

    /// Shuts down Glean in an orderly fashion.
    void glean_shutdown();

    // Creates and initializes a new Glean object for use in a subprocess.
    //
    // Importantly, this will not send any pings at startup, since that
    // sort of management should only happen in the main process.
    //
    // Must only be used for an uploader process.
    // The general API or any metrics API **will not work**.
    boolean glean_initialize_for_subprocess(InternalConfiguration cfg);

    void glean_set_upload_enabled(boolean enabled);

    // Experiment reporting API
    void glean_set_experiment_active(string experiment_id, string branch, record<DOMString, string> extra);
    void glean_set_experiment_inactive(string experiment_id);
    RecordedExperiment? glean_test_get_experiment_data(string experiment_id);

    // Experimentation ID API
    void glean_set_experimentation_id(string experimentation_id);
    string? glean_test_get_experimentation_id();

    // EXPERIMENTAL: Register a listener to receive notification of event recordings
    //
    // tag: String value used later to unregister the listener
    // listener: An object which implements the GleanEventListener interface
    void glean_register_event_listener(string tag, GleanEventListener listener);
    // EXPERIMENTAL: Unregister a previously registered event listener
    //
    // tag: The tag used when registering the listener
    void glean_unregister_event_listener(string tag);

    // Server Knobs API
    void glean_set_metrics_enabled_config(string json);

    boolean glean_set_debug_view_tag(string tag);
    boolean glean_set_source_tags(sequence<string> tags);
    void glean_set_log_pings(boolean value);

    void glean_handle_client_active();
    void glean_handle_client_inactive();

    void glean_submit_ping_by_name(string ping_name, optional string? reason = null);
    boolean glean_submit_ping_by_name_sync(string ping_name, optional string? reason = null);

    void glean_set_test_mode(boolean enabled);
    void glean_test_destroy_glean(boolean clear_stores, optional string? data_path = null);

    void glean_set_dirty_flag(boolean flag);

    PingUploadTask glean_get_upload_task();
    UploadTaskAction glean_process_ping_upload_response(string uuid, UploadResult result);
};

// A `Cow<'static, str>`, but really it's always the owned part.
[Custom]
typedef string CowString;

// The Glean configuration.
//
// This exposes all configurable parameters to the SDK side.
// They should not be exposed directly to users of the SDK (except `upload_enabled`).
dictionary InternalConfiguration {
    string data_path;
    string application_id;
    string language_binding_name;
    boolean upload_enabled;
    u32? max_events;
    boolean delay_ping_lifetime_io;
    string app_build;
    boolean use_core_mps;
    boolean trim_data_to_registered_pings;
    LevelFilter? log_level;
    PingRateLimit? rate_limit;
    boolean enable_event_timestamps;
    string? experimentation_id;
};

// How to specify the rate pings may be uploaded before they are throttled.
dictionary PingRateLimit {
    u64 seconds_per_interval;
    u32 pings_per_interval;
};

// An enum representing the different logging levels for the `log` crate.
enum LevelFilter {
    "Off",
    "Error",
    "Warn",
    "Info",
    "Debug",
    "Trace",
};

// Values for the `client_info` metrics.
// The language SDK should collect them on `initialize` once.
// They will be re-used, e.g. when upload is toggled from off to on, to re-set them.
//
// See https://mozilla.github.io/glean/book/user/pings/index.html#the-client_info-section for details.
dictionary ClientInfoMetrics {
    string app_build;
    string app_display_version;
    Datetime app_build_date;
    string architecture;
    string os_version;

    string? channel = null;
    string? locale = null;
    string? device_manufacturer = null;
    string? device_model = null;
    string? android_sdk_version = null;
    i64? windows_build_number = null;
};

[Error]
enum CallbackError {
  "UnexpectedError",
};

// A callback object, that is stored within the core logic for the entire lifetime of the application.
//
// This is used to trigger certain actions that need to happen on the foreign-language side.
callback interface OnGleanEvents {
    // Initialization finished.
    //
    // The language SDK can do additional things from within the same initializer thread,
    // e.g. starting to observe application events for foreground/background behavior.
    // The observer then needs to call the respective client activity API.
    void initialize_finished();

    // Trigger the uploader whenever a ping was submitted.
    //
    // This should not block.
    // The uploader needs to asynchronously poll Glean for new pings to upload.
    [Throws=CallbackError]
    void trigger_upload();

    // Start the Metrics Ping Scheduler.
    //
    // *Note*: The implementor
    // * DOES NOT need to schedule the uploader.
    // * MUST NOT use a dispatched call in the immediate invocation.
    //
    // Returns whether it submitted a ping immediately.
    boolean start_metrics_ping_scheduler();

    // Called when upload is disabled and uploads should be stopped
    [Throws=CallbackError]
    void cancel_uploads();

    // Called on shutdown, before Glean is fully shutdown.
    //
    // * This MUST NOT put any new tasks on the dispatcher.
    //   * New tasks will be ignored.
    // * This SHOULD NOT block arbitrarily long.
    //   * Shutdown waits for a maximum of 30 seconds.
    [Throws=CallbackError]
    void shutdown();
};

// A callback handler that receives the IDs of recorded events
callback interface GleanEventListener {
    // Called when an event is recorded, indicating the id of the event
    void on_event_recorded(string id);
};

// Deserialized experiment data.
dictionary RecordedExperiment {
    // The experiment's branch.
    string branch;
    // Any extra data associated with this experiment.
    record<DOMString, string>? extra;
};

// Represents a request to upload a ping.
dictionary PingRequest {
    // The Job ID to identify this request,
    // this is the same as the ping UUID.
    string document_id;
    // The path for the server to upload the ping to.
    string path;
    // The body of the request, as a byte array.
    // If gzip encoded, then the `headers` list will
    // contain a `Content-Encoding` header with the value `gzip`.
    sequence<u8> body;
    // A map with all the headers to be sent with the request.
    record<DOMString, string> headers;
    // Whether the body has {client|ping}_info sections.
    boolean body_has_info_sections;
    // The ping's name. Likely also somewhere in `path`.
    string ping_name;
};

// An enum representing the possible upload tasks to be performed by an uploader.
[Enum]
interface PingUploadTask {
    // An upload task.
    //
    // * request: the ping request for upload
    Upload(PingRequest request);
    // A flag signaling that the pending pings directories are not done being processed,
    // thus the requester should wait and come back later.
    //
    // * time: The time in milliseconds the requester should wait before requesting a new task.
    Wait(u64 time);

    // A flag signaling that requester doesn't need to request
    // any more upload tasks at this moment.
    //
    // * unused: _ignored_.
    Done(i8 unused);
};

// The result of an attempted ping upload.
[Enum]
interface UploadResult {
    // A recoverable failure.
    //
    // During upload something went wrong,/ e.g. the network connection failed.
    // The upload should be retried at a later time.
    //
    // * unused: _ignored_.
    RecoverableFailure(i8 unused);

    // An unrecoverable upload failure.
    //
    // A possible cause might be a malformed URL.
    //
    // * unused: _ignored_.
    UnrecoverableFailure(i8 unused);

    // A HTTP response code.
    //
    // This can still indicate an error, depending on the status code.
    //
    // * code: The HTTP status code
    HttpStatus(i32 code);

    // Signal that this uploader is done with work
    // and won't accept new work.
    Done(i8 unused);
};

// Communicating back whether the uploader loop should continue.
enum UploadTaskAction {
    // Instruct the caller to continue with work.
    "Next",

    // Instruct the caller to end work.
    "End",
};

// The supported metrics' lifetimes.
//
// A metric's lifetime determines when its stored data gets reset.
enum Lifetime {
    // The metric is reset with each sent ping
    "Ping",
    // The metric is reset on application restart
    "Application",
    // The metric is reset with each user profile
    "User",
};

// The possible error types for metric recording.
enum ErrorType {
    // For when the value to be recorded does not match the metric-specific restrictions
    "InvalidValue",
    // For when the label of a labeled metric does not match the restrictions
    "InvalidLabel",
    // For when the metric caught an invalid state while recording
    "InvalidState",
    // For when the value to be recorded overflows the metric-specific upper range
    "InvalidOverflow",
};

interface PingType {
    constructor(string name, boolean include_client_id, boolean send_if_empty, boolean precise_timestamps, boolean include_info_sections, sequence<string> reason_codes);
    void submit(optional string? reason = null);
};

// The common set of data shared across all different metric types.
dictionary CommonMetricData {
    // The metric's category.
    string category;
    // The metric's name.
    string name;

    // List of ping names to include this metric in.
    sequence<string> send_in_pings;
    // The metric's lifetime.
    Lifetime lifetime;

    // Whether or not the metric is disabled.
    //
    // Disabled metrics are never recorded.
    boolean disabled;

    // Dynamic label.
    //
    // When a labeled metric factory creates the specific metric to be recorded to,
    // dynamic labels are stored in the specific label so that
    // we can validate them when the Glean singleton is available.
    string? dynamic_label = null;
};

interface CounterMetric {
    constructor(CommonMetricData meta);

    void add(optional i32 amount = 1);

    i32? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// Different resolutions supported by the time related metric types
// (e.g. DatetimeMetric).
enum TimeUnit {
    // Represents nanosecond precision.
    "Nanosecond",
    // Represents microsecond precision.
    "Microsecond",
    // Represents millisecond precision.
    "Millisecond",
    // Represents second precision.
    "Second",
    // Represents minute precision.
    "Minute",
    // Represents hour precision.
    "Hour",
    // Represents day precision.
    "Day",
};

interface TimespanMetric {
    constructor(CommonMetricData meta, TimeUnit time_unit);

    void start();

    void stop();

    void cancel();

    void set_raw_nanos(i64 elapsed);

    i64? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface BooleanMetric {
    constructor(CommonMetricData meta);

    void set(boolean value);

    boolean? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface StringMetric {
    constructor(CommonMetricData meta);

    void set(string value);

    string? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface LabeledCounter {
    constructor(CommonMetricData meta, sequence<CowString>? labels);

    CounterMetric get(string label);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface LabeledBoolean {
    constructor(CommonMetricData meta, sequence<CowString>? labels);

    BooleanMetric get(string label);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface LabeledString {
    constructor(CommonMetricData meta, sequence<CowString>? labels);

    StringMetric get(string label);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface StringListMetric {
    constructor(CommonMetricData meta);

    void add(string value);

    void set(sequence<string> value);

    sequence<string>? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface UrlMetric {
    constructor(CommonMetricData meta);

    void set(string value);

    string? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface UuidMetric {
    constructor(CommonMetricData meta);

    void set(string value);

    string generate_and_set();

    string? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface QuantityMetric {
    constructor(CommonMetricData meta);

    void set(i64 value);

    i64? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// A snapshot of all buckets and the accumulated sum of a distribution.
dictionary DistributionData {
    // A map containig the bucket index mapped to the accumulated count.
    record<i64, i64> values;

    // The accumulated sum of all the samples in the distribution.
    i64 sum;

    // The total number of entries in the distribution.
    i64 count;
};

// Identifier for a running timer.
//
// Its internals are considered private,
// but due to UniFFI's behavior we expose it as a dictionary for now.
dictionary TimerId {
    u64 id;
};

interface TimingDistributionMetric {
    constructor(CommonMetricData meta, TimeUnit time_unit);

    TimerId start();

    void stop_and_accumulate(TimerId timer_id);

    void cancel(TimerId timer_id);

    void accumulate_samples(sequence<i64> samples);

    void accumulate_single_sample(i64 sample);

    DistributionData? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// Different resolutions supported by the memory related metric types
// (e.g. MemoryDistributionMetric).
enum MemoryUnit {
    // 1 byte
    "Byte",
    // 2^10 bytes
    "Kilobyte",
    // 2^20 bytes
    "Megabyte",
    // 2^30 bytes
    "Gigabyte",
};

interface MemoryDistributionMetric {
    constructor(CommonMetricData meta, MemoryUnit memory_unit);

    void accumulate(i64 sample);

    void accumulate_samples(sequence<i64> samples);

    DistributionData? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// Different kinds of histograms.
enum HistogramType {
    // A histogram with linear distributed buckets.
    "Linear",
    // A histogram with exponential distributed buckets.
    "Exponential",
};

interface CustomDistributionMetric {
    constructor(CommonMetricData meta, i64 range_min, i64 range_max, i64 bucket_count, HistogramType histogram_type);

    void accumulate_samples(sequence<i64> samples);

    void accumulate_single_sample(i64 sample);

    DistributionData? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// Representation of a date, time and timezone.
dictionary Datetime {
    i32 year;
    u32 month;
    u32 day;
    u32 hour;
    u32 minute;
    u32 second;
    u32 nanosecond;
    i32 offset_seconds;
};

interface DatetimeMetric {
    constructor(CommonMetricData meta, TimeUnit time_unit);

    void set(optional Datetime? value = null);

    Datetime? test_get_value(optional string? ping_name = null);

    string? test_get_value_as_string(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

// Represents the recorded data for a single event.
dictionary RecordedEvent {
    // The timestamp of when the event was recorded.
    //
    // This allows to order events from a single process run.
    u64 timestamp;

    // The event's category.
    //
    // This is defined by users in the metrics file.
    string category;

    // The event's name.
    //
    // This is defined by users in the metrics file.
    string name;

    // A map of all extra data values.
    //
    // The set of allowed extra keys is defined by users in the metrics file.
    record<DOMString, string>? extra;
};

interface EventMetric {
    constructor(CommonMetricData meta, sequence<string> allowed_extra_keys);

    void record(record<DOMString, string> extra);

    sequence<RecordedEvent>? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

dictionary Rate {
    i32 numerator;
    i32 denominator;
};

interface RateMetric {
    constructor(CommonMetricData meta);

    void add_to_numerator(i32 amount);

    void add_to_denominator(i32 amount);

    Rate? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface DenominatorMetric {
    constructor(CommonMetricData meta, sequence<CommonMetricData> numerators);

    void add(i32 amount);

    i32? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface NumeratorMetric {
    constructor(CommonMetricData meta);

    void add_to_numerator(i32 amount);

    Rate? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};

interface TextMetric {
    constructor(CommonMetricData meta);

    void set(string value);

    string? test_get_value(optional string? ping_name = null);

    i32 test_get_num_recorded_errors(ErrorType error);
};