@0xef8effe12d55773f;

using Common = import "common.capnp";

struct Task {
    # Data recorded when a new task is spawned

    id @0 :Common.Id;
    # The task's ID.
    #
    # This uniquely identifies this task across all *currently live* tasks.
    # When the task's stats change, or when the task completes, it will be
    # identified by this ID; if the client requires additional information
    # included in the `Task` message, it should store that data and access it
    # by ID.

    metadata @1 :Common.MetaId;
    # The numeric ID of the task's `Metadata`.
    #
    # This identifies the `Metadata` that describes the `tracing` span
    # corresponding to this task. The metadata for this ID will have been sent
    # in a prior `RegisterMetadata` message.

    kind @2 :Kind;
    # The category of task this task belongs to.
    enum Kind {
        spawn @0;
        # Spawned using the main runtime asyncronous task spawning
        blocking @1;
        # Spawning as a blocking operation
    }

    fields @3 :List(Common.Field);
    # A list of 'fields' attached to this task.

    parents @4 :List(Common.SpanId);
    # An ordered list of span IDs corresponding to the `tracing` span context
    # in which this task was spawned.
    #
    # The first span ID in this list is the immediate parent, followed by that
    # span's parent, and so on. The final ID is the root span of the current
    # trace.
    #
    # If this is empty, there were *no* active spans when the task was spawned.
    #
    # These IDs may correspond to `tracing` spans which are *not* tasks, if
    # additional trace data is being collected.

    location @5 :Common.Location;
    # The location in the code where this task was spawned.
}

struct Update {
    # A task state update.
    #
    # Each `Update` contains any task data that has changed since the last
    # update. This includes:
    # - any new tasks that were spawned since the last update
    # - the current stats for any task whose stats changed since the last update

    newTasks @0 :List(Task);
    # A list of new tasks that were spawned since the last `Update` was
    # sent.
    #
    # If this is empty, no new tasks were spawned.

    statsUpdate @1 :Common.IntMap(Stats);
    # Any task stats that have changed since the last update.
    #
    # This is a map of task IDs (64-bit unsigned integers) to task stats. If a
    # task's ID is not included in this map, then its stats have *not* changed
    # since the last `Update` in which they were present. If a task's ID
    # *is* included in this map, the corresponding value represents a complete
    # snapshot of that task's stats at in the current time window.

    droppedEvents @2 :UInt64;
    # A count of how many task events (e.g. polls, spawns, etc) were not
    # recorded because the application's event buffer was at capacity.
    #
    # If everything is working normally, this should be 0. If it is greater
    # than 0, that may indicate that some data is missing from this update, and
    # it may be necessary to increase the number of events buffered by the
    # application to ensure that data loss is avoided.
    #
    # If the application's instrumentation ensures reliable delivery of events,
    # this will always be 0.
}

struct TaskDetails {
    # A task details update

    id @0 :Common.Id;
    # The tasks id to which the details belong to

    now @1 :Common.Timestamp;
    # The timestamp for when the update to the task took place

    pollTimesHistogram @2 :DurationHistogram;
    # A histogram of task poll durations

    scheduledTimesHistogram @3 :DurationHistogram;
    # A histogram of task scheduled durations
    #
    # The scheduled duration is the time a task spends between woken and when it is next polled
}

struct Stats {
    # Task performance statistics

    createdAt @0 :Common.Timestamp;
    # Timestamp of when the task was created

    droppedAt @1 :Common.Timestamp;
    # Timestamp of when the task was dropped

    wakes @2 :UInt64;
    # Total number of times this task has been woken over its lifetime

    wakerClones @3 :UInt64;
    # Total number of times this tasks waker was cloned

    wakerDrops @4 :UInt64;
    # Total number of times this tasks waker was dropped

    lastWake @5 :Common.Optional(Common.Timestamp);
    # The timestamp of the most recent time this task has been woken.
    #
    # If this is `Nothing`, the task has not yet been woken

    pollStats @6 :Common.PollStats;
    # Contains task poll statistics

    selfWakes @7 :UInt64;
    # Total number of times this task has woken itself

    scheduledTime @8 :Common.Duration;
    # The total duration this task was scheduled prior to being polled, summed
    # across all poll cycles.
    #
    # Note that this includes only polls that have started, and does not
    # reflect any scheduled state where the task hasn't yet been polled.
    # Subtracting both `busy_time` (from the task's `PollStats`) and
    # `scheduled_time` from the total lifetime of the task results in the
    # amount of time it spent unable to progress because it was waiting on
    # some resource.
}

struct DurationHistogram {
    rawHistogram @0 :Data;
    # HdrHistogram.rs `Histogram` serialized to binary in the V2 format

    maxValue @1 :UInt64;
    # The histograms maximum value

    highOutliers @2 :UInt64;
    # The number of outliers which have exceeded the histograms maximum value

    highestOutlier @3 :UInt64;
    # The highest recorded outlier. This only has a sensible value if `highOutliers` is greater than zero
}