pkg/analysis_server/tool/spec/spec_input.html - Issue 2922603002: Add an analytics domain to the analysis server.

Side by Side Diff: pkg/analysis_server/tool/spec/spec_input.html

Issue 2922603002: Add an analytics domain to the analysis server. (Closed)

Patch Set: Created 3 years, 6 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

OLD	NEW
1 <!doctype html>	1 <!doctype html>

2 <html>	2 <html>

3 <head>	3 <head>

4 <meta charset="UTF-8"/>	4 <meta charset="UTF-8"/>

5 <title>Analysis Server API Specification</title>	5 <title>Analysis Server API Specification</title>

6 </head>	6 </head>

7 <body>	7 <body>

8 <h1>Analysis Server API Specification</h1>	8 <h1>Analysis Server API Specification</h1>

9 <h1 style="color:#999999">Version	9 <h1 style="color:#999999">Version

10 <version>1.18.1</version>	10 <version>1.18.1</version>

(...skipping 2194 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
2205 this call will return an error of <tt>DEBUG_PORT_COULD_NOT_BE_OPENED</tt>.	2205 this call will return an error of <tt>DEBUG_PORT_COULD_NOT_BE_OPENED</tt>.

2206 </p>	2206 </p>

2207 <result>	2207 <result>

2208 <field name="port">	2208 <field name="port">

2209 <ref>int</ref>	2209 <ref>int</ref>

2210 <p>The diagnostic server port.</p>	2210 <p>The diagnostic server port.</p>

2211 </field>	2211 </field>

2212 </result>	2212 </result>

2213 </request>	2213 </request>

2214 </domain>	2214 </domain>

	2215 <domain name="analytics" experimental="true">

	2216 <p>

	2217 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 "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. Show quoted text On 2017/06/02 15:57:31, Brian Wilkerson wrote: > "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). Updated with some verbiage.
	2218 </p>

	2219 <request method="isEnabled">

	2220 <p>Query whether analytics is enabled.</p>

	2221 <result>

	2222 <field name="enabled">

	2223 <ref>bool</ref>

	2224 <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 t 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.
	2225 </field>

	2226 </result>

	2227 </request>

	2228 <request method="enable">

	2229 <p>Enable or disable sending analytics information.</p>

	2230 <params>

	2231 <field name="value">

	2232 <ref>bool</ref>

	2233 <p>Enable or disable analytics.</p>
	Brian Wilkerson 2017/06/02 15:57:31 Perhaps something like ----- Enable or disable th 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. -----
	2234 </field>

	2235 </params>

	2236 </request>

	2237 <request method="sendEvent">

	2238 <p>Send information about client events.</p>
	Brian Wilkerson 2017/06/02 15:57:31 Perhaps we can be more specific. ----- Ask the an 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.
	2239 <params>

	2240 <field name="action">

	2241 <ref>String</ref>

	2242 <p>The client action name.</p>
	Brian Wilkerson 2017/06/02 15:57:31 For consistency with the changes above, perhaps - For consistency with the changes above, perhaps ----- The value used to indicate which action was performed. -----
	2243 </field>

	2244 </params>

	2245 </request>

	2246 <request method="sendTiming">

	2247 <p>Send timing information for client events (e.g. code completions).</p>
	Brian Wilkerson 2017/06/02 15:57:30 Needs similar work. Needs similar work.
	2248 <params>

	2249 <field name="variable">
	Brian Wilkerson 2017/06/02 15:57:31 Should we keep the name from the underlying API, o 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 analy Show quoted text On 2017/06/02 15:57:31, Brian Wilkerson wrote: > 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. 'variable' is what it's called in the google analytics API, but I think in context 'event' would make more sense.
	2250 <ref>String</ref>

	2251 <p>The variable name for the event.</p>

	2252 </field>

	2253 <field name="millis">

	2254 <ref>int</ref>

	2255 <p>The duration of the event in milliseconds.</p>

	2256 </field>

	2257 </params>

	2258 </request>

	2259 </domain>

2215 <types>	2260 <types>

2216 <h2 class="domain"><a name="types">Types</a></h2>	2261 <h2 class="domain"><a name="types">Types</a></h2>

2217 <p>	2262 <p>

2218 This section contains descriptions of the data types referenced	2263 This section contains descriptions of the data types referenced

2219 in the API’s of the various domains.	2264 in the API’s of the various domains.

2220 </p>	2265 </p>

2221 <include path="../../../analyzer_plugin/tool/spec/common_types_spec.html"	2266 <include path="../../../analyzer_plugin/tool/spec/common_types_spec.html"

2222 import="package:analyzer_plugin/protocol/protocol_common.dart"></incl ude>	2267 import="package:analyzer_plugin/protocol/protocol_common.dart"></incl ude>

2223 <type name="AnalysisErrorFixes">	2268 <type name="AnalysisErrorFixes">

2224 <p>	2269 <p>

(...skipping 1266 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
3491 This section contains a list of all of the errors that are	3536 This section contains a list of all of the errors that are

3492 produced by the server and the data that is returned with each.	3537 produced by the server and the data that is returned with each.

3493 </p>	3538 </p>

3494 <p>	3539 <p>

3495 TODO: TBD	3540 TODO: TBD

3496 </p>	3541 </p>

3497 <h2 class="domain"><a name="index">Index</a></h2>	3542 <h2 class="domain"><a name="index">Index</a></h2>

3498 <index></index>	3543 <index></index>

3499 </body>	3544 </body>

3500 </html>	3545 </html>

OLD	NEW

« pkg/analysis_server/lib/src/domain_analytics.dart ('K') | « pkg/analysis_server/tool/spec/generated/java/AnalysisServer.java ('k') | no next file » | no next file with comments »