tools/metrics/histograms/histograms.xml

Index: tools/metrics/histograms/histograms.xml
diff --git a/tools/metrics/histograms/histograms.xml b/tools/metrics/histograms/histograms.xml
index dbc6893f3bd19c012904bc24a7b57367a90f4199..9e1b721ed3ac195dab426fccbd971ff52c6c72eb 100644
--- a/tools/metrics/histograms/histograms.xml
+++ b/tools/metrics/histograms/histograms.xml
@@ -59544,6 +59544,61 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="WebAudio.AudioBuffer.Length">

[Mark P, 2016/05/20 23:03:30]

please add units= annotations to all these histograms.

[Raymond Toy, 2016/05/23 23:12:01]

Any constraints on what units might be? 

[Mark P, 2016/05/23 23:41:54]

No.  It's just a string displayed in the dashboard column.
If you use enum=, then it has to be something in the enum list at the bottom of
the file.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The length (in frames) requested by createBuffer(). Recorded for every call
+    to createBuffer().
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.AudioBuffer.NumberOfChannels">
+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The number of channels requested by createBuffer(). Recorded for every call
+    to createBuffer().
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.AudioBuffer.SampleRate">
+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The sample rate (in Hz) requested by createBuffer(). Recorded for every call
+    to createBuffer().
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.AudioBuffer.SampleRateRatio">
+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The ratio of the buffer sample rate from createBuffer() to the context
+    sample rate multiplied by 100. This indicates if the buffer needs to be
+    resampled. Recorded for every call to createBuffer().
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.AudioContext.MaxChannelCount">

[Mark P, 2016/05/23 18:10:24]

Consider "Available" instead of "Count".  Count seems to be more like the number
requested, not a hard cap on the number that could be used.
Also consider putting hardware in the histogram name as well.

[Raymond Toy, 2016/05/23 20:36:03]

I'm ok with changing the name, but maxChannelCount is the name of the attribute
in the audio context.

[Mark P, 2016/05/23 21:30:24]

I'd encourage clarity in the histograms because it might not be just team
members looking at them.  (Yes, even at the expense of differing naming in the
code.  People who care about the details can always look up the call.  But if
the name is misleading, they might think they know what's going on but me
wrong.)  (Also, you could always revise the code.)

[Raymond Toy, 2016/05/24 17:04:12]

I'm ok with changing the name, but maxChannelCount is the actual AudioContext
idl attribute name so I thought that would be clearer.

WDYT?

[Mark P, 2016/05/24 17:35:18]

Again, I'd still prefer the name changed.  I'd read this histogram name the
maximum number of channels used is a webaudio stream, not the maximum available.
 People don't always read the histogram descriptions; let's not mislead them
based on the name.  I don't see any downside to this name--even if users are
familiar with the spec, they'll be able to tell what the new name means.  If you
want to change the code too for consistency and clarity, that's fine, but that's
more of a discussion with the code owners.

[Raymond Toy, 2016/05/24 17:46:40]

No problem; I'll change it.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The maximum number of (hardware) channels available in an AudioContext.
+    Recorded for every WebAudio AudioContext that is created.
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.AudioContext.SampleRate">

[Mark P, 2016/05/23 18:10:25]

ditto about putting hardware in the title, as I can easily imagine having a
software audio sample rate too (e.g., audio is resampled at a lower rate for
uploading).

[Raymond Toy, 2016/05/23 20:36:03]

There is a spec change where an audio context is supposed to allow an
constructor option to specify the sample rate.  Not sure how to handle this, but
perhaps HardWareSampleRate is best in this case.

[Mark P, 2016/05/23 21:30:24]

Ah.

BTW, "Hardware" is the normal way to capitalize the word.

[Raymond Toy, 2016/05/23 23:12:00]

Yeah, typo on my part. I've changed it to HardwareSampleRate now.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The hardware sample rate (in Hz) used by an AudioContext. Recorded for every
+    WebAudio AudioContext that is created.
+  </summary>
+</histogram>
+
 <histogram name="WebAudio.AudioDestination.CallbackBufferSize">
   <owner>rtoy@chromium.org</owner>
   <owner>hongchan@chromium.org</owner>
@@ -59586,6 +59641,16 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="WebAudio.BiquadFilter.Type">

[Mark P, 2016/05/23 18:10:24]

Please use an enum= and then you won't need the enum descriptions in the
histogram description.

[Raymond Toy, 2016/05/23 20:36:03]

Acknowledged.

[Raymond Toy, 2016/05/23 23:12:00]

Done.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The type of the BiquadFilterNode. (0=Lowpass, 1=Highpass, 2=Bandpass,
+    3=Lowshelf, 4=Highshelf, 5=Peaking, 6=Notch, 7=Allpass).  Recorded each time
+    the type is set.

[Mark P, 2016/05/23 18:10:25]

Can you give an approximate description of how often this occurs?

[Raymond Toy, 2016/05/23 20:36:03]

I suspect this only happens once per filter node that is created.  The default
is lowpass and people probably only change the type once.  I find it odd to be
changing the filter type back and forth, unless they want to do weird things.

hongchan: WDYT?

[Raymond Toy, 2016/05/23 23:12:00]

Did you mean in the summary, or just for your infomation?

[Mark P, 2016/05/23 23:41:54]

Both times I asked for descriptions of when they're emitted, I meant to add it
to the description in the file.

[Raymond Toy, 2016/05/24 16:54:22]

Ok.  The summary currently says it's recorded each time the type is set.  Do you
want more than this?

[Mark P, 2016/05/24 17:35:18]

Yes.  It's not obvious how often this is set.  It is set open every web audio
load?  Only web audio loads that have different values than the previous one? 
Set every time a web audio is rebuffered?  Set every ten seconds?  I don't need
precision but having a good idea of the type of things that cause this to be
emitted is good.

[Raymond Toy, 2016/05/24 17:46:40]

I don't have a good feel for this.  It's certainly set once (to the default
lowpass) whenever a biquad filter is created. I assume it gets set once more if
the user wanted a different filter.  I'm assuming after that it never gets set
again.

But a particular page could generate hundreds or thousands of these (but
probably only on user interaction, so not more than a few tens of filters per
second?).

I'm not sure how to phrase this in the summary.

For the other entries for AudioContext or OfflineAudioContext, I think there's
probably only one AudioContext per page.  OfflineAudioContexts can have more but
typically none (?), but I have seen pages that want to create 1000+ (which
doesn't work because we run out of threads).

For the AudioBuffer, there are probably quite a few per page. Up to hundreds, or
maybe thousands, since these hold the sounds to be played.  I don't have a feel
for how often these are created.  I suspect these are created at application
start.

hongchan: Do you have any feel for these?

+  </summary>
+</histogram>
+
 <histogram name="WebAudio.IIRFilterNode.Order">
   <owner>rtoy@chromium.org</owner>
   <owner>hongchan@chromium.org</owner>
@@ -59596,6 +59661,42 @@ http://cs/file:chrome/histograms.xml - but prefer this file for new entries.
   </summary>
 </histogram>
 
+<histogram name="WebAudio.OfflineAudioContext.ChannelCount">

[Mark P, 2016/05/23 18:10:25]

Do all the AudioBuffer and other histograms you're updating above apply both to
online and offline content?

[Raymond Toy, 2016/05/23 20:36:03]

Yes.  We don't much care in in the other histograms whether you're using an
offline or online context.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The number of channels specified for the offline audio context. Recorded for
+    every offline context created.
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.OfflineAudioContext.Length">
+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The length (in frames) specified for the offline audio context. Recorded for
+    every offline context created.
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.OfflineAudioContext.SampleRate">
+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The sample rate (in Hz) specified for the offline audio context. Recorded
+    for every offline context created.
+  </summary>
+</histogram>
+
+<histogram name="WebAudio.PannerNode.PanningModel">

[Mark P, 2016/05/23 18:10:24]

Please use an enum.

[Raymond Toy, 2016/05/23 20:36:03]

Acknowledged.

[Raymond Toy, 2016/05/23 23:12:00]

Done.

+  <owner>rtoy@chromium.org</owner>
+  <owner>hongchan@chromium.org</owner>
+  <summary>
+    The panning model (&quot;equalpower&quot; = 0, &quot;HRTF&quot; = 1) for the
+    PannerNode. Recorded every time the panning model is changed.

[Mark P, 2016/05/23 18:10:24]

Please describe approximate when this happens.

[Raymond Toy, 2016/05/23 20:36:03]

Like the filter type, we expect the panner model to be fixed.  Panner nodes
default to equalpower on creation and I suspect it only gets changed to HRTF and
remains that way forever.

+  </summary>
+</histogram>
+
 <histogram name="WebController.CertVerificationErrorsCacheHit"
     enum="BooleanCacheHit">
   <owner>eugenebut@chromium.org</owner>