tracing: the client lib of the tracing service

services/resource_coordinator/public/interfaces/tracing/tracing.mojom

 // Copyright 2017 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 module resource_coordinator.tracing.mojom;
 
 import "mojo/common/time.mojom";
 import "mojo/common/values.mojom";
 
 // The JSON type of data coming from a tracing agents.
 //
 // - All agents with the same label should have the same type.
 // - There can be multiple agents with the same label, if their data type is
 //   ARRAY. Their data will be concatenated together and separated by commas.
 // - There can be only one agent with data type STRING.
 enum TraceDataType {
   ARRAY,
   STRING
 };
 
 // Tracing agents, like |chrome|, |etw|, |battor|, and |cros|, use this
 // interface to register themselves to the tracing service.
-interface Factory {
-  RegisterAgent(Agent agent, string name, string label, TraceDataType type,
+interface AgentSet {

[Primiano Tucci (use gerrit), 2017/05/11 15:31:07]

Out of curiosity, what is the reason why this is not just a method of
Coordinator? Why do we need the two interfaces to be separated? (Don't have
strong objections but just trying to understand the tradeoff... I wonder if I
should do the same for memory_instrumentation).
If this is separate, I think that AgentRegistry might be a better name. Until
now, before I reched this line, I was thinking that AgentSet was a wrapper
around std::set<Agent> 

[chiniforooshan, 2017/05/15 20:44:12]

Renamed to AgentRegistry.

This is for security and privacy. We don't want to let all children to be able
to collect and see trace events from other processes (e.g. can contain sensitive
navigation data that cannot be given to a possibly-compromised child process).
But, we want to let all children to be able to register themselves as trace
providers. So, we need to provide the registration to all children but
coordination ability only to trusted processes (i.e. the browser).

The design doc linked in the CL document has a section about this.

[Primiano Tucci (use gerrit), 2017/05/16 04:45:11]

Yup, sorry I added this comment before getting to that part of the doc. Makes
perfect sense (maybe clarify in a readme or in the comment). Knowing myself I am
sure that 3 months from now I am going to ping you and ask "hey why did we split
the two and they are not the same?" :P

[chiniforooshan, 2017/05/16 15:14:44]

Done.

+  RegisterAgent(Agent agent, string label, TraceDataType type,
                 bool supports_explicit_clock_sync_);
 };
 
-// There should be at most one implementation of this interface per process.
 // When the tracing service calls |StopAndFlush| on an agent, the agent begins
 // serializing data into the recorder that was given in the |StartTracing| call.
 // When finished, the agent should close the recorder connection to signal the
 // tracing service that no more data will be sent.
 interface Agent {
-  StartTracing(string categories, Recorder recorder);
+  // If |report_categories_only| is true, the agent should not send trace events
+  // to the recorder; they will be ignored; it should send only the list of
+  // categories known to the agent.
+  StartTracing(
+      string config, Recorder recorder, bool report_categories_only) => ();
   StopAndFlush();
-  RequestClockSyncMarker() => (mojo.common.mojom.TimeTicks issue_ts,
-                               mojo.common.mojom.TimeTicks issue_end_ts);
+  RequestClockSyncMarker(string sync_id) => (
+      mojo.common.mojom.TimeTicks issue_ts,
+      mojo.common.mojom.TimeTicks issue_end_ts);
   RequestBufferStatus() => (uint32 capacity, uint32 count);
 };
 
 // An agent can make several calls to |AddChunk|. Chunks will be concatenated
 // with no separator (type STRING) or using comma as the separator (type ARRAY).
 // There should be only one agent of type STRING per agent label; otherwise
 // their trace data would be mixed up.
 interface Recorder {
+  AddCategories(string categories);
   AddChunk(string chunk);
   AddMetadata(mojo.common.mojom.DictionaryValue metadata);
 };
 
 // A tracing controller uses this interface to coordinate trace data collection
 // from all registered agents. At any given time, there should be at most one
 // connected controller.
 interface Coordinator {
-  StartTracing(handle<data_pipe_producer> stream, string categories);
+  StartTracing(handle<data_pipe_producer> stream, string config);
   StopAndFlush();
   IsTracing() => (bool is_tracing);
-  RequestBufferUsage() => (float percent_full, uint32 approximate_count);
+  RequestBufferUsage() => (bool success, float percent_full,
+                           uint32 approximate_count);
+  GetCategories() => (string categories);
 };