adapter/stats_api.go

   1 // Copyright (c) 2019 Cisco and/or its affiliates.
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at:
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 package adapter
  16
  17 import (
  18         "errors"
  19         "fmt"
  20 )
  21
  22 const (
  23         // DefaultStatsSocket defines a default socket file path for VPP stats API.
  24         DefaultStatsSocket = "/run/vpp/stats.sock"
  25 )
  26
  27 var (
  28         ErrStatsDataBusy     = errors.New("stats data busy")
  29         ErrStatsDirStale     = errors.New("stats dir stale")
  30         ErrStatsDisconnected = errors.New("stats disconnected")
  31         ErrStatsAccessFailed = errors.New("stats access failed")
  32 )
  33
  34 // StatsAPI provides connection to VPP stats API.
  35 type StatsAPI interface {
  36         // Connect establishes client connection to the stats API.
  37         Connect() error
  38         // Disconnect terminates client connection.
  39         Disconnect() error
  40
  41         // ListStats lists names for stats matching patterns.
  42         ListStats(patterns ...string) (names []string, err error)
  43         // DumpStats dumps all stat entries.
  44         DumpStats(patterns ...string) (entries []StatEntry, err error)
  45
  46         // PrepareDir prepares new stat dir for entries that match any of prefixes.
  47         PrepareDir(patterns ...string) (*StatDir, error)
  48         // UpdateDir updates stat dir and all of their entries.
  49         UpdateDir(dir *StatDir) error
  50 }
  51
  52 // StatType represents type of stat directory and simply
  53 // defines what type of stat data is stored in the stat entry.
  54 type StatType int
  55
  56 const (
  57         _                     StatType = 0
  58         ScalarIndex           StatType = 1
  59         SimpleCounterVector   StatType = 2
  60         CombinedCounterVector StatType = 3
  61         ErrorIndex            StatType = 4
  62         NameVector            StatType = 5
  63 )
  64
  65 func (d StatType) String() string {
  66         switch d {
  67         case ScalarIndex:
  68                 return "ScalarIndex"
  69         case SimpleCounterVector:
  70                 return "SimpleCounterVector"
  71         case CombinedCounterVector:
  72                 return "CombinedCounterVector"
  73         case ErrorIndex:
  74                 return "ErrorIndex"
  75         case NameVector:
  76                 return "NameVector"
  77         }
  78         return fmt.Sprintf("UnknownStatType(%d)", d)
  79 }
  80
  81 // StatDir defines directory of stats entries created by PrepareDir.
  82 type StatDir struct {
  83         Epoch   int64
  84         Indexes []uint32
  85         Entries []StatEntry
  86 }
  87
  88 // StatEntry represents single stat entry. The type of stat stored in Data
  89 // is defined by Type.
  90 type StatEntry struct {
  91         Name []byte
  92         Type StatType
  93         Data Stat
  94 }
  95
  96 // Counter represents simple counter with single value, which is usually packet count.
  97 type Counter uint64
  98
  99 // CombinedCounter represents counter with two values, for packet count and bytes count.
 100 type CombinedCounter [2]uint64
 101
 102 func (s CombinedCounter) Packets() uint64 {
 103         return uint64(s[0])
 104 }
 105
 106 func (s CombinedCounter) Bytes() uint64 {
 107         return uint64(s[1])
 108 }
 109
 110 // Name represents string value stored under name vector.
 111 type Name []byte
 112
 113 func (n Name) String() string {
 114         return string(n)
 115 }
 116
 117 // Stat represents some type of stat which is usually defined by StatType.
 118 type Stat interface {
 119         // IsZero returns true if all of its values equal to zero.
 120         IsZero() bool
 121
 122         // isStat is intentionally  unexported to limit implementations of interface to this package,
 123         isStat()
 124 }
 125
 126 // ScalarStat represents stat for ScalarIndex.
 127 type ScalarStat float64
 128
 129 // ErrorStat represents stat for ErrorIndex. The array represents workers.
 130 type ErrorStat []Counter
 131
 132 // SimpleCounterStat represents stat for SimpleCounterVector.
 133 // The outer array represents workers and the inner array represents interface/node/.. indexes.
 134 // Values should be aggregated per interface/node for every worker.
 135 // ReduceSimpleCounterStatIndex can be used to reduce specific index.
 136 type SimpleCounterStat [][]Counter
 137
 138 // CombinedCounterStat represents stat for CombinedCounterVector.
 139 // The outer array represents workers and the inner array represents interface/node/.. indexes.
 140 // Values should be aggregated per interface/node for every worker.
 141 // ReduceCombinedCounterStatIndex can be used to reduce specific index.
 142 type CombinedCounterStat [][]CombinedCounter
 143
 144 // NameStat represents stat for NameVector.
 145 type NameStat []Name
 146
 147 func (ScalarStat) isStat()          {}
 148 func (ErrorStat) isStat()           {}
 149 func (SimpleCounterStat) isStat()   {}
 150 func (CombinedCounterStat) isStat() {}
 151 func (NameStat) isStat()            {}
 152
 153 func (s ScalarStat) IsZero() bool {
 154         return s == 0
 155 }
 156 func (s ErrorStat) IsZero() bool {
 157         if s == nil {
 158                 return true
 159         }
 160         for _, ss := range s {
 161                 if ss != 0 {
 162                         return false
 163                 }
 164         }
 165         return true
 166 }
 167 func (s SimpleCounterStat) IsZero() bool {
 168         if s == nil {
 169                 return true
 170         }
 171         for _, ss := range s {
 172                 for _, sss := range ss {
 173                         if sss != 0 {
 174                                 return false
 175                         }
 176                 }
 177         }
 178         return true
 179 }
 180 func (s CombinedCounterStat) IsZero() bool {
 181         if s == nil {
 182                 return true
 183         }
 184         for _, ss := range s {
 185                 if ss == nil {
 186                         return true
 187                 }
 188                 for _, sss := range ss {
 189                         if sss[0] != 0 || sss[1] != 0 {
 190                                 return false
 191                         }
 192                 }
 193         }
 194         return true
 195 }
 196 func (s NameStat) IsZero() bool {
 197         if s == nil {
 198                 return true
 199         }
 200         for _, ss := range s {
 201                 if len(ss) > 0 {
 202                         return false
 203                 }
 204         }
 205         return true
 206 }
 207
 208 // ReduceSimpleCounterStatIndex returns reduced SimpleCounterStat s for index i.
 209 func ReduceSimpleCounterStatIndex(s SimpleCounterStat, i int) uint64 {
 210         var val uint64
 211         for _, w := range s {
 212                 val += uint64(w[i])
 213         }
 214         return val
 215 }
 216
 217 // ReduceCombinedCounterStatIndex returns reduced CombinedCounterStat s for index i.
 218 func ReduceCombinedCounterStatIndex(s CombinedCounterStat, i int) [2]uint64 {
 219         var val [2]uint64
 220         for _, w := range s {
 221                 val[0] += uint64(w[i][0])
 222                 val[1] += uint64(w[i][1])
 223         }
 224         return val
 225 }