github.com/livekit/protocol@v1.39.3/protobufs/livekit_metrics.proto (about)

     1  syntax = "proto3";
     2  
     3  package livekit;
     4  option go_package = "github.com/livekit/protocol/livekit";
     5  option csharp_namespace = "LiveKit.Proto";
     6  option ruby_package = "LiveKit::Proto";
     7  
     8  import "google/protobuf/timestamp.proto";
     9  
    10  
    11  /*
    12    Protocol used to record metrics for a specific session.
    13  
    14    Clients send their timestamp in their own monotonically increasing time (e.g `performance.now` on JS).
    15    These timestamps are then augmented by the SFU to its time base.
    16  
    17    A metric can be linked to a specific track by setting `track_sid`.
    18  */
    19  
    20  
    21  // index from [0: MAX_LABEL_PREDEFINED_MAX_VALUE) are for predefined labels (`MetricLabel`)
    22  enum MetricLabel {
    23    AGENTS_LLM_TTFT = 0; // time to first token from LLM
    24    AGENTS_STT_TTFT = 1; // time to final transcription
    25    AGENTS_TTS_TTFB = 2; // time to first byte
    26  
    27    CLIENT_VIDEO_SUBSCRIBER_FREEZE_COUNT = 3;                           // Number of video freezes
    28    CLIENT_VIDEO_SUBSCRIBER_TOTAL_FREEZE_DURATION = 4;                  // total duration of freezes
    29    CLIENT_VIDEO_SUBSCRIBER_PAUSE_COUNT = 5;                            // number of video pauses
    30    CLIENT_VIDEO_SUBSCRIBER_TOTAL_PAUSES_DURATION = 6;                  // total duration of pauses
    31    CLIENT_AUDIO_SUBSCRIBER_CONCEALED_SAMPLES = 7;                      // number of concealed (synthesized) audio samples
    32    CLIENT_AUDIO_SUBSCRIBER_SILENT_CONCEALED_SAMPLES = 8;               // number of silent concealed samples
    33    CLIENT_AUDIO_SUBSCRIBER_CONCEALMENT_EVENTS = 9;                     // number of concealment events
    34    CLIENT_AUDIO_SUBSCRIBER_INTERRUPTION_COUNT = 10;                    // number of interruptions
    35    CLIENT_AUDIO_SUBSCRIBER_TOTAL_INTERRUPTION_DURATION = 11;           // total duration of interruptions
    36    CLIENT_SUBSCRIBER_JITTER_BUFFER_DELAY = 12;                         // total time spent in jitter buffer
    37    CLIENT_SUBSCRIBER_JITTER_BUFFER_EMITTED_COUNT = 13;                 // total time spent in jitter buffer
    38    CLIENT_VIDEO_PUBLISHER_QUALITY_LIMITATION_DURATION_BANDWIDTH = 14;  // total duration spent in bandwidth quality limitation
    39    CLIENT_VIDEO_PUBLISHER_QUALITY_LIMITATION_DURATION_CPU = 15;        // total duration spent in cpu quality limitation
    40    CLIENT_VIDEO_PUBLISHER_QUALITY_LIMITATION_DURATION_OTHER = 16;      // total duration spent in other quality limitation
    41  
    42    PUBLISHER_RTT = 17;   // Publisher RTT (participant -> server)
    43    SERVER_MESH_RTT = 18; // RTT between publisher node and subscriber node (could involve intermedia node(s))
    44    SUBSCRIBER_RTT = 19;  // Subscribe RTT (server -> participant)
    45  
    46    METRIC_LABEL_PREDEFINED_MAX_VALUE = 4096;
    47  }
    48  
    49  message MetricsBatch {
    50    int64 timestamp_ms = 1; // time at which this batch is sent based on a monotonic clock (millisecond resolution)
    51    google.protobuf.Timestamp normalized_timestamp = 2;
    52    // To avoid repeating string values, we store them in a separate list and reference them by index
    53    // This is useful for storing participant identities, track names, etc.
    54    // There is also a predefined list of labels that can be used to reference common metrics.
    55    // They have reserved indices from 0 to (METRIC_LABEL_PREDEFINED_MAX_VALUE - 1).
    56    // Indexes pointing at str_data should start from METRIC_LABEL_PREDEFINED_MAX_VALUE, 
    57    // such that str_data[0] == index of METRIC_LABEL_PREDEFINED_MAX_VALUE.
    58    repeated string str_data = 3;
    59    repeated TimeSeriesMetric time_series = 4;
    60    repeated EventMetric events = 5;
    61  }
    62  
    63  message TimeSeriesMetric {
    64    // Metric name e.g "speech_probablity". The string value is not directly stored in the message, but referenced by index
    65    // in the `str_data` field of `MetricsBatch`
    66    uint32 label = 1;
    67    uint32 participant_identity = 2; // index into `str_data`
    68    uint32 track_sid = 3; // index into `str_data`
    69    repeated MetricSample samples = 4;
    70    uint32 rid = 5; // index into 'str_data'
    71  }
    72  
    73  message MetricSample {
    74    int64 timestamp_ms = 1; // time of metric based on a monotonic clock (in milliseconds)
    75    google.protobuf.Timestamp normalized_timestamp = 2;
    76    float value = 3;
    77  }
    78  
    79  message EventMetric {
    80    uint32 label = 1;
    81    uint32 participant_identity = 2; // index into `str_data`
    82    uint32 track_sid = 3; // index into `str_data`
    83    int64 start_timestamp_ms = 4; // start time of event based on a monotonic clock (in milliseconds)
    84    optional int64 end_timestamp_ms = 5; // end time of event based on a monotonic clock (in milliseconds), if needed
    85    google.protobuf.Timestamp normalized_start_timestamp = 6;
    86    optional google.protobuf.Timestamp normalized_end_timestamp = 7;
    87    string metadata = 8;
    88    uint32 rid = 9; // index into 'str_data'
    89  }