fabaccess-bffh/runtime/console-api/schema/common.capnp

@0x911648bc10d7e94f;

struct Timestamp {
    # Timestamp in consisting of a 64-bit second counter and a 32-bit nanosecond counter

    seconds @0 :Int64;
    # Non-leap second counter since 1970-01-01T00:00:00Z

    nanoseconds @1 :UInt32;
    # Nanosecond counter since the last non-leap second
}

struct Duration {
    # Duration struct consiting of a 64-bit seconds value and a 32-bit *signed* nanosecond value

    seconds @0 :Int64;
    # Seconds of duration

    nanoseconds @1 :Int32;
    # Nanoseconds of duration
}

struct Optional(T) {
    union {
        nothing @0 :Void;
        just @1 :T;
    }
}

struct Id {
    id @0 :UInt64;
}

struct MetaId {
    id @0 :UInt64;
}

struct SpanId {
    id @0 :UInt64;
}

struct Field {
    name :union {
        string @0 :Text;
        # Name as immediate string
        index @1 :UInt64;
        # An index position into the `Metadata.field_names` of the metadata for
        # the task span that the field came from
    }

    value :union {
        debug @2 :Text;
        # Value serialized to string using `fmt::Debug`
        string @3 :Text;
        # A string value
        u64 @4 :UInt64;
        # An unsigned integer value
        i64 @5 :Int64;
        # A signed integer value
        bool @6 :Bool;
        # A boolean value
    }

    metadataId @7 :MetaId;
    # Metadata for the task span that the field came from
}

struct Span {
    # Represents a period of time in which a program was executing in a particular context.
    #
    # Corresponds to `Span` in the `tracing` crate.

    id @0 :SpanId;
    # An id that unique identifies this span in relation to other spans

    metadataId @1 :MetaId;
    # Identifier for metadata describing static characteristics of all spans originating
    # from that callsite, such as its name, source code location, verbosity level, and
    # the names of its fields.

    fields @2 :List(Field);
    # User-defined key-value pairs of arbitrary data that describe the context the span represents

    at @3 :Timestamp;
    # Timestamp for the span
}

struct Location {
    file @0 :Text;
    # File path
    modulePath @1 :Text;
    # Rust module path
    line @2 :UInt32;
    # Line number
    column @3 :UInt32;
}

struct RegisterMetadata {
    # Any new metadata that was registered since the last update

    metadata @0 :List(NewMetadata);
    # The new metadata that was registered

    struct NewMetadata {
        id @0 :MetaId;
        # Unique identifier for the metadata

        metadata @1 :Metadata;
        # Metadata payload
    }
}

struct Metadata {
    # Metadata associated with a span or an event

    name @0 :Text;
    # Name of the span or event

    target @1 :Text;
    # Describes the part of the system where the span or event that this metadata describes occured

    modulePath @2 :Text;
    # Path to the Rust module where the span occured

    location @3 :Location;
    # Rust source code location associated with this span or event

    kind @4 :Kind;
    # Indicates wheter this metadata is associated with a span or an event
    enum Kind {
        span @0;
        event @1;
    }

    level @5 :Level;
    # Describes the level of verbosity of a span or event
    enum Level {
        error @0;
        # Designates very serious errors

        warn @1;
        # Designates hazardous situations

        info @2;
        # Designates useful information

        debug @3;
        # Designates lower priority information

        trace @4;
        # Designates very low priority, often extremely verbose, information
    }
}

struct PollStats {
    # Contains stats about objects that can be polled. Currently these can be:
    # - tasks that have been spawned
    # - async operations that are performed within the context of a task

    polls @0 :UInt64;
    # The total number of times this object was polled

    firstPoll @1 :Optional(Timestamp);
    # The timestamp of the first time this object was polled.
    #
    # If this is `Nothing`, the object has not yet been polled.
    #
    # Subtracting this timestamp from `created_at` can be used to calculate the
    # time to first poll for this object, a measurement of executor latency.

    lastPollStarted @2 :Optional(Timestamp);
    # The timestamp of the most recent time this objects's poll method was invoked.
    #
    # If this is `Nothing`, the object has not yet been polled.
    #
    # If the object has only been polled a single time, then this value may be
    # equal to the `first_poll` timestamp.

    lastPollEnded @3 :Optional(Timestamp);
    # The timestamp of the most recent time this objects's poll method finished execution.
    #
    # If this is `Nothing`, the object has not yet been polled or is currently being polled.
    #
    # If the object does not exist anymore, then this is the time the final invocation of
    # its poll method has completed.

    busyTime @4 :Duration;
    # The total duration this object was being *actively polled*, summed across
    # all polls.
    #
    # Note that this includes only polls that have completed, and does not
    # reflect any in-progress polls. Subtracting `busy_time` from the
    # total lifetime of the polled object results in the amount of time it
    # has spent *waiting* to be polled (including the `scheduled_time` value
    # from `TaskStats`, if this is a task).
}

struct Attribute {
    # State attributes of an entity. These are dependent on the type of the entity.
    #
    # For example, a timer resource will have a duration, while a semaphore resource may
    # have a permit count. Likewise, the async ops of a semaphore may have attributes
    # indicating how many permits they are trying to acquire vs how many are acquired.
    # These values may change over time. Therefore, they live in the runtime stats rather
    # than the static data describing the entity.

    field @0 :Field;
    # The key-value pair for the attribute

    unit @1 :Text;
    # Some values carry an unit of measurement, e.g. durations given in 'ms'.
}

struct Map(K, V) {
    entries @0 :List(Entry);
    struct Entry {
        key @0 :K;
        value @1 :V;
    }
}

struct IntMap(V) {
    entries @0 :List(Entry);
    struct Entry {
        key @0 :UInt64;
        value @1 :V;
    }
}