services/tracing/public/mojom/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 tracing.mojom;

import "mojo/public/mojom/base/process_id.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/values.mojom";
import "services/tracing/public/mojom/perfetto_service.mojom";

struct ConnectToTracingRequest {
  PerfettoService perfetto_service;
  AgentRegistry agent_registry;
};

// The tracing service will bind this interface on every other service,
// and pass it pointers to the interfaces within the tracing service
// that the other services should register themselves with.
interface TracedProcess {
  ConnectToTracingService(ConnectToTracingRequest request);
};

// 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 or OBJECT. Their data will be concatenated together and separated by
//   commas.
// - There can be only one agent with data type STRING.
enum TraceDataType {
  ARRAY,
  OBJECT,
  STRING
};

// Tracing agents, like |chrome|, |etw|, and |cros|, use this interface to
// register themselves to the tracing service.
//
// This is a separate interface from |Coordinator| for security and privacy
// reasons: although we want to let almost every process be able to send tracing
// data to the service, we do not want to let an untrusted child process be able
// to collect traces from other processes using the |Coordinator| interface.
interface AgentRegistry {
  RegisterAgent(Agent agent, string label, TraceDataType type,
                mojo_base.mojom.ProcessId pid);
};

// When the tracing service calls |StopAndFlush| on an agent, the agent begins
// serializing data into the given recorder.  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 config, mojo_base.mojom.TimeTicks coordinator_time);
  StopAndFlush(Recorder recorder);
  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 {
  AddChunk(string chunk);
  AddMetadata(mojo_base.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 {
  // The return value is false if tracing is already enabled with a different
  // config. Otherwise, true is returned as soon as the service receives acks
  // from all existing agents and agents that connect during |StartTracing|.
  StartTracing(string config);
  StopAndFlush(handle<data_pipe_producer> stream)
      => (mojo_base.mojom.DictionaryValue metadata);
  // Same as |StopAndFlush| but only write data from a certain |agent_label| to
  // the |stream|.
  StopAndFlushAgent(handle<data_pipe_producer> stream, string agent_label)
      => (mojo_base.mojom.DictionaryValue metadata);
  IsTracing() => (bool is_tracing);
  RequestBufferUsage() => (bool success, float percent_full,
                           uint32 approximate_count);
};