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 unsigned long long count;
 115   required record<UTF8String, unsigned long long> values;
 116 };
 117
 118 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 119 interface GleanTimingDistribution : GleanMetric {
 120   /**
 121    * Starts tracking time for the provided metric.
 122    *
 123    * @returns A unique timer id for the new timer
 124    */
 125   unsigned long long start();
 126
 127   /**
 128    * Stops tracking time for the provided metric and timer id.
 129    *
 130    * Adds a count to the corresponding bucket in the timing distribution.
 131    * This will record an error if no `start` was called for this TimerId or
 132    * if this TimerId was used to call `cancel`.
 133    *
 134    * @param aId The TimerId associated with this timing. This allows for
 135    *            concurrent timing of events associated with different ids.
 136    */
 137   undefined stopAndAccumulate(unsigned long long aId);
 138
 139   /**
 140    * Aborts a previous `start` call. No error is recorded if no `start` was
 141    * called. (But then where did you get that id from?)
 142    *
 143    * @param aId The TimerID whose `start` you wish to abort.
 144    */
 145   undefined cancel(unsigned long long aId);
 146
 147   /**
 148    * **Test-only API**
 149    *
 150    * Gets the currently stored value.
 151    *
 152    * This function will attempt to await the last parent-process task (if any)
 153    * writing to the the metric's storage engine before returning a value.
 154    * This function will not wait for data from child processes.
 155    *
 156    * This doesn't clear the stored value.
 157    * Parent process only. Panics in child processes.
 158    *
 159    * @param aPingName The (optional) name of the ping to retrieve the metric
 160    *        for. Defaults to the first value in `send_in_pings`.
 161    *
 162    * @return value of the stored metric, or null if there is no value.
 163    */
 164   [Throws, ChromeOnly]
 165   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 166
 167   /**
 168    * **Test-only API**
 169    *
 170    * Accumulates a raw numeric sample of milliseconds.
 171    *
 172    * @param aSample The sample, in milliseconds, to add.
 173    */
 174   [ChromeOnly]
 175   undefined testAccumulateRawMillis(unsigned long long aSample);
 176 };
 177
 178 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 179 interface GleanMemoryDistribution : GleanMetric {
 180   /**
 181    * Accumulates the provided signed sample in the metric.
 182    *
 183    * @param aSample The sample to be recorded by the metric. The sample is
 184    *                assumed to be in the confgured memory unit of the metric.
 185    *
 186    * Notes: Values bigger than 1 Terabyte (2^40 bytes) are truncated and an
 187    * InvalidValue error is recorded.
 188    */
 189   undefined accumulate(unsigned long long aSample);
 190
 191   /**
 192    * **Test-only API**
 193    *
 194    * Gets the currently stored value as a DistributionData.
 195    *
 196    * This function will attempt to await the last parent-process task (if any)
 197    * writing to the the metric's storage engine before returning a value.
 198    * This function will not wait for data from child processes.
 199    *
 200    * This doesn't clear the stored value.
 201    * Parent process only. Panics in child processes.
 202    *
 203    * @param aPingName The (optional) name of the ping to retrieve the metric
 204    *        for. Defaults to the first value in `send_in_pings`.
 205    *
 206    * @return value of the stored metric, or null if there is no value.
 207    */
 208   [Throws, ChromeOnly]
 209   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 210 };
 211
 212 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 213 interface GleanCustomDistribution : GleanMetric {
 214   /**
 215    * Accumulates the provided signed samples in the metric.
 216    *
 217    * @param aSamples - The vector holding the samples to be recorded by the metric.
 218    *
 219    * Notes: Discards any negative value in `samples`
 220    * and report an `ErrorType::InvalidValue` for each of them.
 221    */
 222   undefined accumulateSamples(sequence<long long> aSamples);
 223
 224   /**
 225    * Accumulates the provided single signed sample in the metric.
 226    *
 227    * @param aSample - The sample to be recorded by the metric.
 228    *
 229    * Notes: Discards any negative value of `sample` and reports an
 230    * `ErrorType::InvalidValue`.
 231    */
 232   undefined accumulateSingleSample(long long aSample);
 233
 234   /**
 235    * **Test-only API**
 236    *
 237    * Gets the currently stored value as a DistributionData.
 238    *
 239    * This function will attempt to await the last parent-process task (if any)
 240    * writing to the the metric's storage engine before returning a value.
 241    * This function will not wait for data from child processes.
 242    *
 243    * This doesn't clear the stored value.
 244    * Parent process only. Panics in child processes.
 245    *
 246    * @param aPingName The (optional) name of the ping to retrieve the metric
 247    *        for. Defaults to the first value in `send_in_pings`.
 248    *
 249    * @return value of the stored metric, or null if there is no value.
 250    */
 251   [Throws, ChromeOnly]
 252   GleanDistributionData? testGetValue(optional UTF8String aPingName = "");
 253 };
 254
 255 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 256 interface GleanString : GleanMetric {
 257   /**
 258    * Set the string to the provided value.
 259    *
 260    * @param aValue The string to set the metric to.
 261    */
 262   undefined set(UTF8String? aValue);
 263
 264   /**
 265    * **Test-only API**
 266    *
 267    * Gets the currently stored value as a string.
 268    *
 269    * This function will attempt to await the last parent-process task (if any)
 270    * writing to the the metric's storage engine before returning a value.
 271    * This function will not wait for data from child processes.
 272    *
 273    * This doesn't clear the stored value.
 274    * Parent process only. Panics in child processes.
 275    *
 276    * @param aPingName The (optional) name of the ping to retrieve the metric
 277    *        for. Defaults to the first value in `send_in_pings`.
 278    *
 279    * @return value of the stored metric, or null if there is no value.
 280    */
 281   [Throws, ChromeOnly]
 282   UTF8String? testGetValue(optional UTF8String aPingName = "");
 283 };
 284
 285 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 286 interface GleanStringList : GleanMetric {
 287   /**
 288    * Adds a new string to the list.
 289    *
 290    * Truncates the value and logs an error if it is longer than 100 bytes.
 291    *
 292    * @param value The string to add.
 293    */
 294   undefined add(UTF8String value);
 295
 296   /**
 297    * Sets the string_list to the provided list of strings.
 298    *
 299    * Truncates the list and logs an error if longer than 100 items.
 300    * Truncates any item longer than 100 bytes and logs an error.
 301    *
 302    * @param aValue The list of strings to set the metric to.
 303    */
 304   undefined set(sequence<UTF8String> aValue);
 305
 306   /**
 307    * **Test-only API**
 308    *
 309    * Gets the currently stored value.
 310    *
 311    * This function will attempt to await the last parent-process task (if any)
 312    * writing to the the metric's storage engine before returning a value.
 313    * This function will not wait for data from child processes.
 314    *
 315    * This doesn't clear the stored value.
 316    * Parent process only. Panics in child processes.
 317    *
 318    * @param aPingName The (optional) name of the ping to retrieve the metric
 319    *        for. Defaults to the first value in `send_in_pings`.
 320    *
 321    * @return value of the stored metric, or null if there is no value.
 322    */
 323   [Throws, ChromeOnly]
 324   sequence<UTF8String>? testGetValue(optional UTF8String aPingName = "");
 325 };
 326
 327 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 328 interface GleanTimespan : GleanMetric {
 329   /**
 330    * Start tracking time for the provided metric.
 331    *
 332    * This records an error if it’s already tracking time (i.e. start was already
 333    * called with no corresponding [stop]): in that case the original
 334    * start time will be preserved.
 335    */
 336   undefined start();
 337
 338   /**
 339    * Stop tracking time for the provided metric.
 340    *
 341    * Sets the metric to the elapsed time, but does not overwrite an already
 342    * existing value.
 343    * This will record an error if no [start] was called or there is an already
 344    * existing value.
 345    */
 346   undefined stop();
 347
 348   /**
 349    * Aborts a previous start.
 350    *
 351    * Does not record an error if there was no previous call to start.
 352    */
 353   undefined cancel();
 354
 355   /**
 356    * Explicitly sets the timespan value.
 357    *
 358    * This API should only be used if you cannot make use of
 359    * `start`/`stop`/`cancel`.
 360    *
 361    * @param aDuration The duration of this timespan, in units matching the
 362    *        `time_unit` of this metric's definition.
 363    */
 364   undefined setRaw(unsigned long aDuration);
 365
 366   /**
 367    * **Test-only API**
 368    *
 369    * Gets the currently stored value.
 370    *
 371    * This function will attempt to await the last parent-process task (if any)
 372    * writing to the the metric's storage engine before returning a value.
 373    * This function will not wait for data from child processes.
 374    *
 375    * This doesn't clear the stored value.
 376    * Parent process only. Panics in child processes.
 377    *
 378    * @param aPingName The (optional) name of the ping to retrieve the metric
 379    *        for. Defaults to the first value in `send_in_pings`.
 380    *
 381    * @return value of the stored metric, or null if there is no value.
 382    */
 383   [Throws, ChromeOnly]
 384   unsigned long long? testGetValue(optional UTF8String aPingName = "");
 385 };
 386
 387 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 388 interface GleanUuid : GleanMetric {
 389   /**
 390    * Set to the specified value.
 391    *
 392    * @param aValue The UUID to set the metric to.
 393    */
 394   undefined set(UTF8String aValue);
 395
 396   /**
 397    * Generate a new random UUID and set the metric to it.
 398    */
 399   undefined generateAndSet();
 400
 401   /**
 402    * **Test-only API**
 403    *
 404    * Gets the currently stored value.
 405    *
 406    * This function will attempt to await the last parent-process task (if any)
 407    * writing to the the metric's storage engine before returning a value.
 408    * This function will not wait for data from child processes.
 409    *
 410    * This doesn't clear the stored value.
 411    * Parent process only. Panics in child processes.
 412    *
 413    * @param aPingName The (optional) name of the ping to retrieve the metric
 414    *        for. Defaults to the first value in `send_in_pings`.
 415    *
 416    * @return value of the stored metric, or null if there is no value.
 417    */
 418   [Throws, ChromeOnly]
 419   UTF8String? testGetValue(optional UTF8String aPingName = "");
 420 };
 421
 422 dictionary GleanEventRecord {
 423   required unsigned long long timestamp;
 424   required UTF8String category;
 425   required UTF8String name;
 426   record<UTF8String, UTF8String> extra;
 427 };
 428
 429 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 430 interface GleanEvent : GleanMetric {
 431
 432   /*
 433    * Record an event.
 434    *
 435    * @param aExtra An (optional) map of extra values.
 436    */
 437   undefined _record(optional record<UTF8String, UTF8String?> aExtra);
 438
 439   /**
 440    * **Test-only API**
 441    *
 442    * Gets the currently stored value.
 443    *
 444    * This function will attempt to await the last parent-process task (if any)
 445    * writing to the the metric's storage engine before returning a value.
 446    * This function will not wait for data from child processes.
 447    *
 448    * This doesn't clear the stored value.
 449    * Parent process only. Panics in child processes.
 450    *
 451    * @param aPingName The (optional) name of the ping to retrieve the metric
 452    *        for. Defaults to the first value in `send_in_pings`.
 453    *
 454    * @return value of the stored metric, or null if there is no value.
 455    *
 456    * The difference between event timestamps is in milliseconds
 457    * See https://mozilla.github.io/glean/book/user/metrics/event.html for further details.
 458    * Due to limitations of numbers in JavaScript, the timestamp will only be accurate up until 2^53.
 459    * (This is probably not an issue with the current clock implementation. Probably.)
 460    */
 461   [Throws, ChromeOnly]
 462   sequence<GleanEventRecord>? testGetValue(optional UTF8String aPingName = "");
 463 };
 464
 465 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 466 interface GleanQuantity : GleanMetric {
 467   /**
 468    * Set to the specified value.
 469    *
 470    * @param aValue The value to set the metric to.
 471    */
 472   undefined set(long long aValue);
 473
 474   /**
 475    * **Test-only API**
 476    *
 477    * Gets the currently stored value.
 478    *
 479    * This function will attempt to await the last parent-process task (if any)
 480    * writing to the the metric's storage engine before returning a value.
 481    * This function will not wait for data from child processes.
 482    *
 483    * This doesn't clear the stored value.
 484    * Parent process only. Panics in child processes.
 485    *
 486    * @param aPingName The (optional) name of the ping to retrieve the metric
 487    *        for. Defaults to the first value in `send_in_pings`.
 488    *
 489    * @return value of the stored metric, or null if there is no value.
 490    */
 491   [Throws, ChromeOnly]
 492   long long? testGetValue(optional UTF8String aPingName = "");
 493 };
 494
 495 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 496 interface GleanDenominator : GleanMetric {
 497   /*
 498    * Increases the counter by `aAmount`.
 499    *
 500    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 501    */
 502   undefined add(optional long aAmount = 1);
 503
 504   /**
 505    * **Test-only API**
 506    *
 507    * Gets the currently stored value as an integer.
 508    *
 509    * This function will attempt to await the last parent-process task (if any)
 510    * writing to the the metric's storage engine before returning a value.
 511    * This function will not wait for data from child processes.
 512    *
 513    * This doesn't clear the stored value.
 514    * Parent process only. Panics in child processes.
 515    *
 516    * @param aPingName The (optional) name of the ping to retrieve the metric
 517    *        for. Defaults to the first value in `send_in_pings`.
 518    *
 519    * @return value of the stored metric, or null if there is no value.
 520    */
 521   [Throws, ChromeOnly]
 522   long? testGetValue(optional UTF8String aPingName = "");
 523 };
 524
 525 dictionary GleanRateData {
 526   required long numerator;
 527   required long denominator;
 528 };
 529
 530 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 531 interface GleanNumerator : GleanMetric {
 532   /*
 533    * Increases the numerator by `aAmount`.
 534    *
 535    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 536    */
 537   undefined addToNumerator(optional long aAmount = 1);
 538
 539   /**
 540    * **Test-only API**
 541    *
 542    * Gets the currently stored value in the form {numerator: n, denominator: d}
 543    *
 544    * This function will attempt to await the last parent-process task (if any)
 545    * writing to the the metric's storage engine before returning a value.
 546    * This function will not wait for data from child processes.
 547    *
 548    * This doesn't clear the stored value.
 549    * Parent process only. Panics in child processes.
 550    *
 551    * @param aPingName The (optional) name of the ping to retrieve the metric
 552    *        for. Defaults to the first value in `send_in_pings`.
 553    *
 554    * @return value of the stored metric, or null if there is no value.
 555    */
 556   [Throws, ChromeOnly]
 557   GleanRateData? testGetValue(optional UTF8String aPingName = "");
 558 };
 559
 560 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 561 interface GleanRate : GleanMetric {
 562   /*
 563    * Increases the numerator by `amount`.
 564    *
 565    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 566    */
 567   undefined addToNumerator(optional long aAmount = 1);
 568
 569   /*
 570    * Increases the denominator by `amount`.
 571    *
 572    * @param aAmount The (optional) amount to increase by. Should be positive. Defaults to 1.
 573    */
 574   undefined addToDenominator(optional long aAmount = 1);
 575
 576   /**
 577    * **Test-only API**
 578    *
 579    * Gets the currently stored value in the form {numerator: n, denominator: d}
 580    *
 581    * This function will attempt to await the last parent-process task (if any)
 582    * writing to the the metric's storage engine before returning a value.
 583    * This function will not wait for data from child processes.
 584    *
 585    * This doesn't clear the stored value.
 586    * Parent process only. Panics in child processes.
 587    *
 588    * @param aPingName The (optional) name of the ping to retrieve the metric
 589    *        for. Defaults to the first value in `send_in_pings`.
 590    *
 591    * @return value of the stored metric, or null if there is no value.
 592    */
 593   [Throws, ChromeOnly]
 594   GleanRateData? testGetValue(optional UTF8String aPingName = "");
 595 };
 596
 597 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 598 interface GleanUrl : GleanMetric {
 599   /**
 600    * Set to the specified value.
 601    *
 602    * @param aValue The stringified URL to set the metric to.
 603    */
 604   undefined set(UTF8String aValue);
 605
 606   /**
 607    * **Test-only API**
 608    *
 609    * Gets the currently stored value.
 610    *
 611    * This function will attempt to await the last parent-process task (if any)
 612    * writing to the the metric's storage engine before returning a value.
 613    * This function will not wait for data from child processes.
 614    *
 615    * This doesn't clear the stored value.
 616    * Parent process only. Panics in child processes.
 617    *
 618    * @param aPingName The (optional) name of the ping to retrieve the metric
 619    *        for. Defaults to the first value in `send_in_pings`.
 620    *
 621    * @return value of the stored metric, or null if there is no value.
 622    */
 623   [Throws, ChromeOnly]
 624   UTF8String? testGetValue(optional UTF8String aPingName = "");
 625 };
 626
 627 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 628 interface GleanText : GleanMetric {
 629   /**
 630    * Set to the provided value.
 631    *
 632    * @param aValue The text to set the metric to.
 633    */
 634   undefined set(UTF8String aValue);
 635
 636   /**
 637    * **Test-only API**
 638    *
 639    * Gets the currently stored value as a string.
 640    *
 641    * This function will attempt to await the last parent-process task (if any)
 642    * writing to the the metric's storage engine before returning a value.
 643    * This function will not wait for data from child processes.
 644    *
 645    * This doesn't clear the stored value.
 646    * Parent process only. Panics in child processes.
 647    *
 648    * @param aPingName The (optional) name of the ping to retrieve the metric
 649    *        for. Defaults to the first value in `send_in_pings`.
 650    *
 651    * @return value of the stored metric, or null if there is no value.
 652    */
 653   [Throws, ChromeOnly]
 654   UTF8String? testGetValue(optional UTF8String aPingName = "");
 655 };
 656
 657 [Func="nsGlobalWindowInner::IsGleanNeeded", Exposed=Window]
 658 interface GleanObject : GleanMetric {
 659   /**
 660    * Set to the specified object.
 661    *
 662    * The structure of the metric is validated against the predefined structure.
 663    *
 664    * @param object The object to set the metric to.
 665    */
 666   undefined set(object value);
 667
 668   /**
 669    * **Test-only API**
 670    *
 671    * Gets the currently stored value as an object.
 672    *
 673    * This function will attempt to await the last parent-process task (if any)
 674    * writing to the the metric's storage engine before returning a value.
 675    * This function will not wait for data from child processes.
 676    *
 677    * This doesn't clear the stored value.
 678    * Parent process only. Panics in child processes.
 679    *
 680    * @param aPingName The (optional) name of the ping to retrieve the metric
 681    *        for. Defaults to the first value in `send_in_pings`.
 682    *
 683    * @return value of the stored metric, or undefined if there is no value.
 684    */
 685   [Throws, ChromeOnly]
 686   object? testGetValue(optional UTF8String aPingName = "");
 687 };