// 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";

// 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,
                bool supports_explicit_clock_sync,
                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)
      => (bool success);
  StopAndFlush(Recorder recorder);
  RequestClockSyncMarker(string sync_id)
      => (mojo_base.mojom.TimeTicks issue_ts,
          mojo_base.mojom.TimeTicks issue_end_ts);
  RequestBufferStatus() => (uint32 capacity, uint32 count);
  GetCategories() => (string categories);
};

// 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) => (bool success);
  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);
  GetCategories() => (bool success, string categories);
};