dom/webidl/GleanMetrics.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 // The definitions in this file are not sorted.
   8 // Please add new ones to the bottom.
   9
  10 /**
  11  * Base interface for all metric types to make typing more expressive.
  12  */
  13 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
  14 interface GleanMetric {};
  15
  16 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
  17 interface GleanBoolean : GleanMetric {
  18   /**
  19    * Set to the specified boolean value.
  20    *
  21    * @param value the value to set.
  22    */
  23   undefined set(boolean value);
  24
  25   /**
  26    * **Test-only API**
  27    *
  28    * Gets the currently stored value as a boolean.
  29    *
  30    * This function will attempt to await the last parent-process task (if any)
  31    * writing to the the metric's storage engine before returning a value.
  32    * This function will not wait for data from child processes.
  33    *
  34    * This doesn't clear the stored value.
  35    * Parent process only. Panics in child processes.
  36    *
  37    * @param aPingName The (optional) name of the ping to retrieve the metric
  38    *        for. Defaults to the first value in `send_in_pings`.
  39    *
  40    * @return value of the stored metric, or null if there is no value.
  41    */
  42   [Throws, ChromeOnly]
  43   boolean? testGetValue(optional UTF8String aPingName = "");
  44 };
  45
  46 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
  47 interface GleanDatetime : GleanMetric {
  48   /**
  49    * Set the datetime to the provided value, or the local now.
  50    * The internal value will store the local timezone.
  51    *
  52    * Note: The metric's time_unit affects the resolution of the value, not the
  53    *       unit of this function's parameter (which is always PRTime/nanos).
  54    *
  55    * @param aValue The (optional) time value as PRTime (nanoseconds since epoch).
  56    *        Defaults to local now.
  57    */
  58   undefined set(optional long long aValue);
  59
  60   /**
  61    * **Test-only API**
  62    *
  63    * Gets the currently stored value as a Date.
  64    *
  65    * This function will attempt to await the last parent-process task (if any)
  66    * writing to the the metric's storage engine before returning a value.
  67    * This function will not wait for data from child processes.
  68    *
  69    * This doesn't clear the stored value.
  70    * Parent process only. Panics in child processes.
  71    *
  72    * @param aPingName The (optional) name of the ping to retrieve the metric
  73    *        for. Defaults to the first value in `send_in_pings`.
  74    *
  75    * @return value of the stored metric as a JS Date with timezone,
  76    *         or null if there is no value.
  77    */
  78   [Throws, ChromeOnly]
  79   any testGetValue(optional UTF8String aPingName = "");
  80 };
  81
  82 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
  83 interface GleanCounter : GleanMetric {
  84   /*
  85    * Increases the counter by `amount`.
  86    *
  87    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
  88    */
  89   undefined add(optional long aAmount = 1);
  90
  91   /**
  92    * **Test-only API**
  93    *
  94    * Gets the currently stored value as an integer.
  95    *
  96    * This function will attempt to await the last parent-process task (if any)
  97    * writing to the the metric's storage engine before returning a value.
  98    * This function will not wait for data from child processes.
  99    *
 100    * This doesn't clear the stored value.
 101    * Parent process only. Panics in child processes.
 102    *
 103    * @param aPingName The (optional) name of the ping to retrieve the metric
 104    *        for. Defaults to the first value in `send_in_pings`.
 105    *
 106    * @return value of the stored metric, or null if there is no value.
 107    */
 108   [Throws, ChromeOnly]
 109   long? testGetValue(optional UTF8String aPingName = "");
 110 };
 111
 112 dictionary GleanDistributionData {
 113   required unsigned long long sum;
 114   required record<UTF8String, unsigned long long> values;
 115 };
 116
 117 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 118 interface GleanTimingDistribution : GleanMetric {
 119   /**
 120    * Starts tracking time for the provided metric.
 121    *
 122    * @returns A unique timer id for the new timer
 123    */
 124   unsigned long long start();
 125
 126   /**
 127    * Stops tracking time for the provided metric and timer id.
 128    *
 129    * Adds a count to the corresponding bucket in the timing distribution.
 130    * This will record an error if no `start` was called for this TimerId or
 131    * if this TimerId was used to call `cancel`.
 132    *
 133    * @param aId The TimerId associated with this timing. This allows for
 134    *            concurrent timing of events associated with different ids.
 135    */
 136   undefined stopAndAccumulate(unsigned long long aId);
 137
 138   /**
 139    * Aborts a previous `start` call. No error is recorded if no `start` was
 140    * called. (But then where did you get that id from?)
 141    *
 142    * @param aId The TimerID whose `start` you wish to abort.
 143    */
 144   undefined cancel(unsigned long long aId);
 145
 146   /**
 147    * **Test-only API**
 148    *
 149    * Gets the currently stored value.
 150    *
 151    * This function will attempt to await the last parent-process task (if any)
 152    * writing to the the metric's storage engine before returning a value.
 153    * This function will not wait for data from child processes.
 154    *
 155    * This doesn't clear the stored value.
 156    * Parent process only. Panics in child processes.
 157    *
 158    * @param aPingName The (optional) name of the ping to retrieve the metric
 159    *        for. Defaults to the first value in `send_in_pings`.
 160    *
 161    * @return value of the stored metric, or null if there is no value.
 162    */
 163   [Throws, ChromeOnly]
 164   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 165
 166   /**
 167    * **Test-only API**
 168    *
 169    * Accumulates a raw numeric sample of milliseconds.
 170    *
 171    * @param aSample The sample, in milliseconds, to add.
 172    */
 173   [ChromeOnly]
 174   undefined testAccumulateRawMillis(unsigned long long aSample);
 175 };
 176
 177 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 178 interface GleanMemoryDistribution : GleanMetric {
 179   /**
 180    * Accumulates the provided signed sample in the metric.
 181    *
 182    * @param aSample The sample to be recorded by the metric. The sample is
 183    *                assumed to be in the confgured memory unit of the metric.
 184    *
 185    * Notes: Values bigger than 1 Terabyte (2^40 bytes) are truncated and an
 186    * InvalidValue error is recorded.
 187    */
 188   undefined accumulate(unsigned long long aSample);
 189
 190   /**
 191    * **Test-only API**
 192    *
 193    * Gets the currently stored value as a DistributionData.
 194    *
 195    * This function will attempt to await the last parent-process task (if any)
 196    * writing to the the metric's storage engine before returning a value.
 197    * This function will not wait for data from child processes.
 198    *
 199    * This doesn't clear the stored value.
 200    * Parent process only. Panics in child processes.
 201    *
 202    * @param aPingName The (optional) name of the ping to retrieve the metric
 203    *        for. Defaults to the first value in `send_in_pings`.
 204    *
 205    * @return value of the stored metric, or null if there is no value.
 206    */
 207   [Throws, ChromeOnly]
 208   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 209 };
 210
 211 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 212 interface GleanCustomDistribution : GleanMetric {
 213   /**
 214    * Accumulates the provided signed samples in the metric.
 215    *
 216    * @param aSamples - The vector holding the samples to be recorded by the metric.
 217    *
 218    * Notes: Discards any negative value in `samples`
 219    * and report an `ErrorType::InvalidValue` for each of them.
 220    */
 221   undefined accumulateSamples(sequence<long long> aSamples);
 222
 223   /**
 224    * **Test-only API**
 225    *
 226    * Gets the currently stored value as a DistributionData.
 227    *
 228    * This function will attempt to await the last parent-process task (if any)
 229    * writing to the the metric's storage engine before returning a value.
 230    * This function will not wait for data from child processes.
 231    *
 232    * This doesn't clear the stored value.
 233    * Parent process only. Panics in child processes.
 234    *
 235    * @param aPingName The (optional) name of the ping to retrieve the metric
 236    *        for. Defaults to the first value in `send_in_pings`.
 237    *
 238    * @return value of the stored metric, or null if there is no value.
 239    */
 240   [Throws, ChromeOnly]
 241   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 242 };
 243
 244 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 245 interface GleanString : GleanMetric {
 246   /**
 247    * Set the string to the provided value.
 248    *
 249    * @param aValue The string to set the metric to.
 250    */
 251   undefined set(UTF8String? aValue);
 252
 253   /**
 254    * **Test-only API**
 255    *
 256    * Gets the currently stored value as a string.
 257    *
 258    * This function will attempt to await the last parent-process task (if any)
 259    * writing to the the metric's storage engine before returning a value.
 260    * This function will not wait for data from child processes.
 261    *
 262    * This doesn't clear the stored value.
 263    * Parent process only. Panics in child processes.
 264    *
 265    * @param aPingName The (optional) name of the ping to retrieve the metric
 266    *        for. Defaults to the first value in `send_in_pings`.
 267    *
 268    * @return value of the stored metric, or null if there is no value.
 269    */
 270   [Throws, ChromeOnly]
 271   UTF8String? testGetValue(optional UTF8String aPingName = "");
 272 };
 273
 274 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 275 interface GleanStringList : GleanMetric {
 276   /**
 277    * Adds a new string to the list.
 278    *
 279    * Truncates the value and logs an error if it is longer than 100 bytes.
 280    *
 281    * @param value The string to add.
 282    */
 283   undefined add(UTF8String value);
 284
 285   /**
 286    * Sets the string_list to the provided list of strings.
 287    *
 288    * Truncates the list and logs an error if longer than 100 items.
 289    * Truncates any item longer than 100 bytes and logs an error.
 290    *
 291    * @param aValue The list of strings to set the metric to.
 292    */
 293   undefined set(sequence<UTF8String> aValue);
 294
 295   /**
 296    * **Test-only API**
 297    *
 298    * Gets the currently stored value.
 299    *
 300    * This function will attempt to await the last parent-process task (if any)
 301    * writing to the the metric's storage engine before returning a value.
 302    * This function will not wait for data from child processes.
 303    *
 304    * This doesn't clear the stored value.
 305    * Parent process only. Panics in child processes.
 306    *
 307    * @param aPingName The (optional) name of the ping to retrieve the metric
 308    *        for. Defaults to the first value in `send_in_pings`.
 309    *
 310    * @return value of the stored metric, or null if there is no value.
 311    */
 312   [Throws, ChromeOnly]
 313   sequence<UTF8String>? testGetValue(optional UTF8String aPingName = "");
 314 };
 315
 316 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 317 interface GleanTimespan : GleanMetric {
 318   /**
 319    * Start tracking time for the provided metric.
 320    *
 321    * This records an error if it’s already tracking time (i.e. start was already
 322    * called with no corresponding [stop]): in that case the original
 323    * start time will be preserved.
 324    */
 325   undefined start();
 326
 327   /**
 328    * Stop tracking time for the provided metric.
 329    *
 330    * Sets the metric to the elapsed time, but does not overwrite an already
 331    * existing value.
 332    * This will record an error if no [start] was called or there is an already
 333    * existing value.
 334    */
 335   undefined stop();
 336
 337   /**
 338    * Aborts a previous start.
 339    *
 340    * Does not record an error if there was no previous call to start.
 341    */
 342   undefined cancel();
 343
 344   /**
 345    * Explicitly sets the timespan value.
 346    *
 347    * This API should only be used if you cannot make use of
 348    * `start`/`stop`/`cancel`.
 349    *
 350    * @param aDuration The duration of this timespan, in units matching the
 351    *        `time_unit` of this metric's definition.
 352    */
 353   undefined setRaw(unsigned long aDuration);
 354
 355   /**
 356    * **Test-only API**
 357    *
 358    * Gets the currently stored value.
 359    *
 360    * This function will attempt to await the last parent-process task (if any)
 361    * writing to the the metric's storage engine before returning a value.
 362    * This function will not wait for data from child processes.
 363    *
 364    * This doesn't clear the stored value.
 365    * Parent process only. Panics in child processes.
 366    *
 367    * @param aPingName The (optional) name of the ping to retrieve the metric
 368    *        for. Defaults to the first value in `send_in_pings`.
 369    *
 370    * @return value of the stored metric, or null if there is no value.
 371    */
 372   [Throws, ChromeOnly]
 373   unsigned long long? testGetValue(optional UTF8String aPingName = "");
 374 };
 375
 376 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 377 interface GleanUuid : GleanMetric {
 378   /**
 379    * Set to the specified value.
 380    *
 381    * @param aValue The UUID to set the metric to.
 382    */
 383   undefined set(UTF8String aValue);
 384
 385   /**
 386    * Generate a new random UUID and set the metric to it.
 387    */
 388   undefined generateAndSet();
 389
 390   /**
 391    * **Test-only API**
 392    *
 393    * Gets the currently stored value.
 394    *
 395    * This function will attempt to await the last parent-process task (if any)
 396    * writing to the the metric's storage engine before returning a value.
 397    * This function will not wait for data from child processes.
 398    *
 399    * This doesn't clear the stored value.
 400    * Parent process only. Panics in child processes.
 401    *
 402    * @param aPingName The (optional) name of the ping to retrieve the metric
 403    *        for. Defaults to the first value in `send_in_pings`.
 404    *
 405    * @return value of the stored metric, or null if there is no value.
 406    */
 407   [Throws, ChromeOnly]
 408   UTF8String? testGetValue(optional UTF8String aPingName = "");
 409 };
 410
 411 dictionary GleanEventRecord {
 412   required unsigned long long timestamp;
 413   required UTF8String category;
 414   required UTF8String name;
 415   record<UTF8String, UTF8String> extra;
 416 };
 417
 418 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 419 interface GleanEvent : GleanMetric {
 420
 421   /*
 422    * Record an event.
 423    *
 424    * @param aExtra An (optional) map of extra values.
 425    */
 426   undefined _record(optional record<UTF8String, UTF8String?> aExtra);
 427
 428   /**
 429    * **Test-only API**
 430    *
 431    * Gets the currently stored value.
 432    *
 433    * This function will attempt to await the last parent-process task (if any)
 434    * writing to the the metric's storage engine before returning a value.
 435    * This function will not wait for data from child processes.
 436    *
 437    * This doesn't clear the stored value.
 438    * Parent process only. Panics in child processes.
 439    *
 440    * @param aPingName The (optional) name of the ping to retrieve the metric
 441    *        for. Defaults to the first value in `send_in_pings`.
 442    *
 443    * @return value of the stored metric, or null if there is no value.
 444    *
 445    * The difference between event timestamps is in milliseconds
 446    * See https://mozilla.github.io/glean/book/user/metrics/event.html for further details.
 447    * Due to limitations of numbers in JavaScript, the timestamp will only be accurate up until 2^53.
 448    * (This is probably not an issue with the current clock implementation. Probably.)
 449    */
 450   [Throws, ChromeOnly]
 451   sequence<GleanEventRecord>? testGetValue(optional UTF8String aPingName = "");
 452 };
 453
 454 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 455 interface GleanQuantity : GleanMetric {
 456   /**
 457    * Set to the specified value.
 458    *
 459    * @param aValue The value to set the metric to.
 460    */
 461   undefined set(long long aValue);
 462
 463   /**
 464    * **Test-only API**
 465    *
 466    * Gets the currently stored value.
 467    *
 468    * This function will attempt to await the last parent-process task (if any)
 469    * writing to the the metric's storage engine before returning a value.
 470    * This function will not wait for data from child processes.
 471    *
 472    * This doesn't clear the stored value.
 473    * Parent process only. Panics in child processes.
 474    *
 475    * @param aPingName The (optional) name of the ping to retrieve the metric
 476    *        for. Defaults to the first value in `send_in_pings`.
 477    *
 478    * @return value of the stored metric, or null if there is no value.
 479    */
 480   [Throws, ChromeOnly]
 481   long long? testGetValue(optional UTF8String aPingName = "");
 482 };
 483
 484 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 485 interface GleanDenominator : GleanMetric {
 486   /*
 487    * Increases the counter by `aAmount`.
 488    *
 489    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 490    */
 491   undefined add(optional long aAmount = 1);
 492
 493   /**
 494    * **Test-only API**
 495    *
 496    * Gets the currently stored value as an integer.
 497    *
 498    * This function will attempt to await the last parent-process task (if any)
 499    * writing to the the metric's storage engine before returning a value.
 500    * This function will not wait for data from child processes.
 501    *
 502    * This doesn't clear the stored value.
 503    * Parent process only. Panics in child processes.
 504    *
 505    * @param aPingName The (optional) name of the ping to retrieve the metric
 506    *        for. Defaults to the first value in `send_in_pings`.
 507    *
 508    * @return value of the stored metric, or null if there is no value.
 509    */
 510   [Throws, ChromeOnly]
 511   long? testGetValue(optional UTF8String aPingName = "");
 512 };
 513
 514 dictionary GleanRateData {
 515   required long numerator;
 516   required long denominator;
 517 };
 518
 519 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 520 interface GleanNumerator : GleanMetric {
 521   /*
 522    * Increases the numerator by `aAmount`.
 523    *
 524    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 525    */
 526   undefined addToNumerator(optional long aAmount = 1);
 527
 528   /**
 529    * **Test-only API**
 530    *
 531    * Gets the currently stored value in the form {numerator: n, denominator: d}
 532    *
 533    * This function will attempt to await the last parent-process task (if any)
 534    * writing to the the metric's storage engine before returning a value.
 535    * This function will not wait for data from child processes.
 536    *
 537    * This doesn't clear the stored value.
 538    * Parent process only. Panics in child processes.
 539    *
 540    * @param aPingName The (optional) name of the ping to retrieve the metric
 541    *        for. Defaults to the first value in `send_in_pings`.
 542    *
 543    * @return value of the stored metric, or null if there is no value.
 544    */
 545   [Throws, ChromeOnly]
 546   GleanRateData? testGetValue(optional UTF8String aPingName = "");
 547 };
 548
 549 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 550 interface GleanRate : GleanMetric {
 551   /*
 552    * Increases the numerator by `amount`.
 553    *
 554    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 555    */
 556   undefined addToNumerator(optional long aAmount = 1);
 557
 558   /*
 559    * Increases the denominator by `amount`.
 560    *
 561    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 562    */
 563   undefined addToDenominator(optional long aAmount = 1);
 564
 565   /**
 566    * **Test-only API**
 567    *
 568    * Gets the currently stored value in the form {numerator: n, denominator: d}
 569    *
 570    * This function will attempt to await the last parent-process task (if any)
 571    * writing to the the metric's storage engine before returning a value.
 572    * This function will not wait for data from child processes.
 573    *
 574    * This doesn't clear the stored value.
 575    * Parent process only. Panics in child processes.
 576    *
 577    * @param aPingName The (optional) name of the ping to retrieve the metric
 578    *        for. Defaults to the first value in `send_in_pings`.
 579    *
 580    * @return value of the stored metric, or null if there is no value.
 581    */
 582   [Throws, ChromeOnly]
 583   GleanRateData? testGetValue(optional UTF8String aPingName = "");
 584 };
 585
 586 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 587 interface GleanUrl : GleanMetric {
 588   /**
 589    * Set to the specified value.
 590    *
 591    * @param aValue The stringified URL to set the metric to.
 592    */
 593   undefined set(UTF8String aValue);
 594
 595   /**
 596    * **Test-only API**
 597    *
 598    * Gets the currently stored value.
 599    *
 600    * This function will attempt to await the last parent-process task (if any)
 601    * writing to the the metric's storage engine before returning a value.
 602    * This function will not wait for data from child processes.
 603    *
 604    * This doesn't clear the stored value.
 605    * Parent process only. Panics in child processes.
 606    *
 607    * @param aPingName The (optional) name of the ping to retrieve the metric
 608    *        for. Defaults to the first value in `send_in_pings`.
 609    *
 610    * @return value of the stored metric, or null if there is no value.
 611    */
 612   [Throws, ChromeOnly]
 613   UTF8String? testGetValue(optional UTF8String aPingName = "");
 614 };
 615
 616 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 617 interface GleanText : GleanMetric {
 618   /**
 619    * Set to the provided value.
 620    *
 621    * @param aValue The text to set the metric to.
 622    */
 623   undefined set(UTF8String aValue);
 624
 625   /**
 626    * **Test-only API**
 627    *
 628    * Gets the currently stored value as a string.
 629    *
 630    * This function will attempt to await the last parent-process task (if any)
 631    * writing to the the metric's storage engine before returning a value.
 632    * This function will not wait for data from child processes.
 633    *
 634    * This doesn't clear the stored value.
 635    * Parent process only. Panics in child processes.
 636    *
 637    * @param aPingName The (optional) name of the ping to retrieve the metric
 638    *        for. Defaults to the first value in `send_in_pings`.
 639    *
 640    * @return value of the stored metric, or null if there is no value.
 641    */
 642   [Throws, ChromeOnly]
 643   UTF8String? testGetValue(optional UTF8String aPingName = "");
 644 };