mojo/services/flog/interfaces/flog.mojom

// Copyright 2016 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.

[DartPackage="mojo_services"]
module mojo.flog;

// Exposed by the log service to enable creation and consumption of logs.
[ServiceName="mojo::flog::FlogService"]
interface FlogService {
  // Creates a new logger.
  CreateLogger(FlogLogger& logger, string label);

  // Gets the descriptions of all logs.
  GetLogDescriptions() => (array<FlogDescription> descriptions);

  // Gets a reader for the specified log.
  CreateReader(FlogReader& reader, uint32 log_id);

  // Deletes the indicated log.
  DeleteLog(uint32 log_id);

  // Deletes all logs.
  DeleteAllLogs();
};

// A logger that logs messages regarding multiple channels.
interface FlogLogger {
  // Logs a MojoLogger-style message.
  LogMojoLoggerMessage(
      int64 time_us,
      int32 log_level,
      string? message,
      string? source_file,
      uint32 source_line);

  // Logs the creation of a channel.
  LogChannelCreation(int64 time_us, uint32 channel_id, string type_name,
      uint64 subject_address);

  // Logs a message sent to an existing channel.
  LogChannelMessage(int64 time_us, uint32 channel_id, array<uint8> data);

  // Logs the deletion of a channel.
  LogChannelDeletion(int64 time_us, uint32 channel_id);
};

// A reader that reads messages from one or more logs.
interface FlogReader {
  // Gets entries from the log starting and the specified index (entries are
  // indexed starting at 0). If the log is open, the callback will be called
  // when max_count entries are avaiable starting at start_index. If the log
  // is closed, the callback will be called immediately with as many entries
  // as are available starting at start_index and not exceeding max_count
  // entries.
  GetEntries(uint32 start_index, uint32 max_count) =>
      (array<FlogEntry> entries);
};

// Describes a log.
struct FlogDescription {
  uint32 log_id;
  string label;
  bool open;
};

// Log entry produced by |FlogReader|. Entry type is determined by interrogating
// the |details| field. FlogEntry and its subordinates duplicate the semantics
// of FlogLogger. This approach keeps producers simple (they don't have to
// create a bunch of structs and unions to log a message) and allows consumers
// to pull entries rather than having to implement FlogLogger.
struct FlogEntry {
  int64 time_us;
  uint32 log_id;
  uint32 channel_id;
  FlogEntryDetails? details;
};

union FlogEntryDetails {
  FlogMojoLoggerMessageEntryDetails mojo_logger_message;
  FlogChannelCreationEntryDetails channel_creation;
  FlogChannelMessageEntryDetails channel_message;
  FlogChannelDeletionEntryDetails channel_deletion;
};

struct FlogMojoLoggerMessageEntryDetails {
  int32 log_level;
  string? message;
  string? source_file;
  uint32 source_line;
};

struct FlogChannelCreationEntryDetails {
  string type_name;
  uint64 subject_address;
};

struct FlogChannelMessageEntryDetails {
  array<uint8> data;
};

struct FlogChannelDeletionEntryDetails {
};