Add an analytics domain to the analysis server.

pkg/analysis_server/tool/spec/spec_input.html

Index: pkg/analysis_server/tool/spec/spec_input.html
diff --git a/pkg/analysis_server/tool/spec/spec_input.html b/pkg/analysis_server/tool/spec/spec_input.html
index b322e53f964277a0303bdb659cef588d696e2da2..db3fdf9c940d71f0df0b1f9b046bec8d3b52c731 100644
--- a/pkg/analysis_server/tool/spec/spec_input.html
+++ b/pkg/analysis_server/tool/spec/spec_input.html
@@ -2212,6 +2212,51 @@
     </result>
   </request>
 </domain>
+<domain name="analytics" experimental="true">
+  <p>
+    The analytics domain contains APIs related to analytics and usage reporting.

[Brian Wilkerson, 2017/06/02 15:57:31]

"and"? Makes it sound like analytics reporting and usage reporting are two
separate things.

It would probably be worth writing some text explaining what information clients
should send to server. Not all client authors will understand what analytics can
be used for. Or perhaps adding examples to each request would be sufficient.

It would also be worth indicating that analysis server will send it's own data
(this is in addition to the data it's sending, not everything it's sending) and
explain where the data is going (and whether / how authors of clients can get
information based on the analytics they send us).

[devoncarew, 2017/06/02 20:17:03]

Updated with some verbiage.

+  </p>
+  <request method="isEnabled">
+    <p>Query whether analytics is enabled.</p>
+    <result>
+      <field name="enabled">
+        <ref>bool</ref>
+        <p>Whether sending analytics is enabled or not.</p>

[Brian Wilkerson, 2017/06/02 15:57:31]

tl;dr spec docs should be complete, not terse

I think this could be confusing because "send" could have two different
interpretations. It could be taken to mean that this indicates whether the
`sendEvent` and `sendTiming` requests can be used (whether analytics should be
sent to server). What it really indicates is whether any analytics information
sent to server will be sent to the cloud. This needs to be clarified.

It should be explained in the docs that the value of the flag can change at any
time (not just via the `enable` request), so clients cannot depend on the value
returned by this request to not change.

We should make it clear that the purpose of this request is to provide an
indication of the value of the flag at a given moment, but that clients are not
required to (and should not) use the value returned to decide whether or not to
send the `sendEvent` and `sendTiming` requests. Those requests should be used
unconditionally and server will determine whether or not it is appropriate to
forward the information to the cloud at the time each request is received.

+      </field>
+    </result>
+  </request>
+  <request method="enable">
+    <p>Enable or disable sending analytics information.</p>
+    <params>
+      <field name="value">
+        <ref>bool</ref>
+        <p>Enable or disable analytics.</p>

[Brian Wilkerson, 2017/06/02 15:57:31]

Perhaps something like

-----
Enable or disable the sending of analytics data from the analysis server to
<however we describe where the data is going>. Note that there are other ways
for users to change this setting, so clients cannot assume that they have
complete control over this setting. In particular, there is no guarantee that
the result returned by the <tt>isEnabled</tt> request will match the last value
set via this request.
-----

+      </field>
+    </params>
+  </request>
+  <request method="sendEvent">
+    <p>Send information about client events.</p>

[Brian Wilkerson, 2017/06/02 15:57:31]

Perhaps we can be more specific.

-----
Ask the analysis server to include the fact that an action was performed in the
client as part of the analytics data being sent. The data will only be included
if the sending of analytics data is enabled at the time the request is
processed. The action that was performed is indicated by the value of the
<tt>action</tt> field.

The value of the action field should not include the identity of the client. The
analytics data sent by server will include the client id passed in using the
<tt>--client-id</tt> command-line argument. The request will be ignored if the
client id was not provided when server was started.
-----

Also, some examples would be useful.

+    <params>
+      <field name="action">
+        <ref>String</ref>
+        <p>The client action name.</p>

[Brian Wilkerson, 2017/06/02 15:57:31]

For consistency with the changes above, perhaps

-----
The value used to indicate which action was performed.
-----

+      </field>
+    </params>
+  </request>
+  <request method="sendTiming">
+    <p>Send timing information for client events (e.g. code completions).</p>

[Brian Wilkerson, 2017/06/02 15:57:30]

Needs similar work.

+    <params>
+      <field name="variable">

[Brian Wilkerson, 2017/06/02 15:57:31]

Should we keep the name from the underlying API, or would it make more sense to
name this "event"? The latter seems more consistent with "action" and with the
descriptions we're providing.

[devoncarew, 2017/06/02 20:17:03]

'variable' is what it's called in the google analytics API, but I think in
context 'event' would make more sense.

+        <ref>String</ref>
+        <p>The variable name for the event.</p>
+      </field>
+      <field name="millis">
+        <ref>int</ref>
+        <p>The duration of the event in milliseconds.</p>
+      </field>
+    </params>
+  </request>
+</domain>
 <types>
   <h2 class="domain"><a name="types">Types</a></h2>
   <p>