toolkit/components/telemetry/core/TelemetryHistogram.h

   1 /* -*- Mode: C++; 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
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef TelemetryHistogram_h__
   7 #define TelemetryHistogram_h__
   8
   9 #include "mozilla/TelemetryComms.h"
  10 #include "mozilla/TelemetryHistogramEnums.h"
  11 #include "mozilla/TelemetryProcessEnums.h"
  12 #include "nsXULAppAPI.h"
  13 #include "TelemetryCommon.h"
  14
  15 // This module is internal to Telemetry.  It encapsulates Telemetry's
  16 // histogram accumulation and storage logic.  It should only be used by
  17 // Telemetry.cpp.  These functions should not be used anywhere else.
  18 // For the public interface to Telemetry functionality, see Telemetry.h.
  19
  20 namespace TelemetryHistogram {
  21
  22 void InitializeGlobalState(bool canRecordBase, bool canRecordExtended);
  23 void DeInitializeGlobalState();
  24 #ifdef DEBUG
  25 bool GlobalStateHasBeenInitialized();
  26 #endif
  27
  28 bool CanRecordBase();
  29 void SetCanRecordBase(bool b);
  30 bool CanRecordExtended();
  31 void SetCanRecordExtended(bool b);
  32
  33 void InitHistogramRecordingEnabled();
  34
  35 void Accumulate(mozilla::Telemetry::HistogramID aHistogram, uint32_t aSample);
  36 void Accumulate(mozilla::Telemetry::HistogramID aHistogram,
  37                 const nsTArray<uint32_t>& aSamples);
  38 void Accumulate(mozilla::Telemetry::HistogramID aID, const nsCString& aKey,
  39                 uint32_t aSample);
  40 void Accumulate(mozilla::Telemetry::HistogramID aID, const nsCString& aKey,
  41                 const nsTArray<uint32_t>& aSamples);
  42 /*
  43  * Accumulate a sample into the named histogram.
  44  *
  45  * Returns NS_OK on success.
  46  * Returns NS_ERROR_NOT_AVAILABLE if recording Telemetry is disabled.
  47  * Returns NS_ERROR_FAILURE on other errors.
  48  */
  49 nsresult Accumulate(const char* name, uint32_t sample);
  50
  51 /*
  52  * Accumulate a sample into the named keyed histogram by key.
  53  *
  54  * Returns NS_OK on success.
  55  * Returns NS_ERROR_NOT_AVAILABLE if recording Telemetry is disabled.
  56  * Returns NS_ERROR_FAILURE on other errors.
  57  */
  58 nsresult Accumulate(const char* name, const nsCString& key, uint32_t sample);
  59
  60 void AccumulateCategorical(mozilla::Telemetry::HistogramID aId,
  61                            const nsCString& aLabel);
  62 void AccumulateCategorical(mozilla::Telemetry::HistogramID aId,
  63                            const nsTArray<nsCString>& aLabels);
  64
  65 void AccumulateChild(
  66     mozilla::Telemetry::ProcessID aProcessType,
  67     const nsTArray<mozilla::Telemetry::HistogramAccumulation>& aAccumulations);
  68 void AccumulateChildKeyed(
  69     mozilla::Telemetry::ProcessID aProcessType,
  70     const nsTArray<mozilla::Telemetry::KeyedHistogramAccumulation>&
  71         aAccumulations);
  72
  73 /**
  74  * Append the list of registered stores to the given set.
  75  */
  76 nsresult GetAllStores(mozilla::Telemetry::Common::StringHashSet& set);
  77
  78 nsresult GetCategoricalHistogramLabels(JSContext* aCx,
  79                                        JS::MutableHandle<JS::Value> aResult);
  80
  81 nsresult GetHistogramById(const nsACString& name, JSContext* cx,
  82                           JS::MutableHandle<JS::Value> ret);
  83
  84 nsresult GetKeyedHistogramById(const nsACString& name, JSContext* cx,
  85                                JS::MutableHandle<JS::Value> ret);
  86
  87 const char* GetHistogramName(mozilla::Telemetry::HistogramID id);
  88
  89 uint8_t GetHistogramType(mozilla::Telemetry::HistogramID id);
  90
  91 nsresult CreateHistogramSnapshots(JSContext* aCx,
  92                                   JS::MutableHandle<JS::Value> aResult,
  93                                   const nsACString& aStore,
  94                                   unsigned int aDataset, bool aClearSubsession,
  95                                   bool aFilterTest = false);
  96
  97 nsresult GetKeyedHistogramSnapshots(JSContext* aCx,
  98                                     JS::MutableHandle<JS::Value> aResult,
  99                                     const nsACString& aStore,
 100                                     unsigned int aDataset,
 101                                     bool aClearSubsession,
 102                                     bool aFilterTest = false);
 103
 104 size_t GetHistogramSizesOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf);
 105
 106 }  // namespace TelemetryHistogram
 107
 108 #endif  // TelemetryHistogram_h__