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 indexed names for stats matching patterns.
  42         ListStats(patterns ...string) (indexes []StatIdentifier, 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         // PrepareDirOnIndex prepares new stat dir for entries that match any of indexes.
  49         PrepareDirOnIndex(indexes ...uint32) (*StatDir, error)
  50         // UpdateDir updates stat dir and all of their entries.
  51         UpdateDir(dir *StatDir) error
  52 }
  53
  54 // StatType represents type of stat directory and simply
  55 // defines what type of stat data is stored in the stat entry.
  56 type StatType int
  57
  58 const (
  59         _                     StatType = 0
  60         ScalarIndex           StatType = 1
  61         SimpleCounterVector   StatType = 2
  62         CombinedCounterVector StatType = 3
  63         ErrorIndex            StatType = 4
  64         NameVector            StatType = 5
  65         Empty                 StatType = 6
  66         Symlink               StatType = 7
  67 )
  68
  69 func (d StatType) String() string {
  70         switch d {
  71         case ScalarIndex:
  72                 return "ScalarIndex"
  73         case SimpleCounterVector:
  74                 return "SimpleCounterVector"
  75         case CombinedCounterVector:
  76                 return "CombinedCounterVector"
  77         case ErrorIndex:
  78                 return "ErrorIndex"
  79         case NameVector:
  80                 return "NameVector"
  81         case Empty:
  82                 return "Empty"
  83         case Symlink:
  84                 return "Symlink"
  85         }
  86         return fmt.Sprintf("UnknownStatType(%d)", d)
  87 }
  88
  89 // StatDir defines directory of stats entries created by PrepareDir.
  90 type StatDir struct {
  91         Epoch   int64
  92         Entries []StatEntry
  93 }
  94
  95 // StatIdentifier holds a stat entry name and index
  96 type StatIdentifier struct {
  97         Index uint32
  98         Name  []byte
  99 }
 100
 101 // StatEntry represents single stat entry. The type of stat stored in Data
 102 // is defined by Type.
 103 type StatEntry struct {
 104         StatIdentifier
 105         Type    StatType
 106         Data    Stat
 107         Symlink bool
 108 }
 109
 110 // Counter represents simple counter with single value, which is usually packet count.
 111 type Counter uint64
 112
 113 // CombinedCounter represents counter with two values, for packet count and bytes count.
 114 type CombinedCounter [2]uint64
 115
 116 func (s CombinedCounter) Packets() uint64 {
 117         return s[0]
 118 }
 119
 120 func (s CombinedCounter) Bytes() uint64 {
 121         return s[1]
 122 }
 123
 124 // Name represents string value stored under name vector.
 125 type Name []byte
 126
 127 func (n Name) String() string {
 128         return string(n)
 129 }
 130
 131 // Stat represents some type of stat which is usually defined by StatType.
 132 type Stat interface {
 133         // IsZero returns true if all of its values equal to zero.
 134         IsZero() bool
 135
 136         // Type returns underlying type of a stat
 137         Type() StatType
 138
 139         // isStat is intentionally  unexported to limit implementations of interface to this package,
 140         isStat()
 141 }
 142
 143 // ScalarStat represents stat for ScalarIndex.
 144 type ScalarStat float64
 145
 146 // ErrorStat represents stat for ErrorIndex. The array represents workers.
 147 type ErrorStat []Counter
 148
 149 // SimpleCounterStat represents indexed stat for SimpleCounterVector.
 150 // The outer array represents workers and the inner array represents interface/node/.. indexes.
 151 // Values should be aggregated per interface/node for every worker.
 152 // ReduceSimpleCounterStatIndex can be used to reduce specific index.
 153 type SimpleCounterStat [][]Counter
 154
 155 // CombinedCounterStat represents indexed stat for CombinedCounterVector.
 156 // The outer array represents workers and the inner array represents interface/node/.. indexes.
 157 // Values should be aggregated per interface/node for every worker.
 158 // ReduceCombinedCounterStatIndex can be used to reduce specific index.
 159 type CombinedCounterStat [][]CombinedCounter
 160
 161 // NameStat represents stat for NameVector.
 162 type NameStat []Name
 163
 164 // EmptyStat represents removed counter directory
 165 type EmptyStat string
 166
 167 func (ScalarStat) isStat()          {}
 168 func (ErrorStat) isStat()           {}
 169 func (SimpleCounterStat) isStat()   {}
 170 func (CombinedCounterStat) isStat() {}
 171 func (NameStat) isStat()            {}
 172 func (EmptyStat) isStat()           {}
 173
 174 func (s ScalarStat) IsZero() bool {
 175         return s == 0
 176 }
 177
 178 func (s ScalarStat) Type() StatType {
 179         return ScalarIndex
 180 }
 181
 182 func (s ErrorStat) IsZero() bool {
 183         if s == nil {
 184                 return true
 185         }
 186         for _, ss := range s {
 187                 if ss != 0 {
 188                         return false
 189                 }
 190         }
 191         return true
 192 }
 193
 194 func (s ErrorStat) Type() StatType {
 195         return ErrorIndex
 196 }
 197
 198 func (s SimpleCounterStat) IsZero() bool {
 199         if s == nil {
 200                 return true
 201         }
 202         for _, ss := range s {
 203                 for _, sss := range ss {
 204                         if sss != 0 {
 205                                 return false
 206                         }
 207                 }
 208         }
 209         return true
 210 }
 211
 212 func (s SimpleCounterStat) Type() StatType {
 213         return SimpleCounterVector
 214 }
 215
 216 func (s CombinedCounterStat) IsZero() bool {
 217         if s == nil {
 218                 return true
 219         }
 220         for _, ss := range s {
 221                 if ss == nil {
 222                         return true
 223                 }
 224                 for _, sss := range ss {
 225                         if sss[0] != 0 || sss[1] != 0 {
 226                                 return false
 227                         }
 228                 }
 229         }
 230         return true
 231 }
 232
 233 func (s CombinedCounterStat) Type() StatType {
 234         return CombinedCounterVector
 235 }
 236
 237 func (s NameStat) IsZero() bool {
 238         if s == nil {
 239                 return true
 240         }
 241         for _, ss := range s {
 242                 if len(ss) > 0 {
 243                         return false
 244                 }
 245         }
 246         return true
 247 }
 248
 249 func (s NameStat) Type() StatType {
 250         return NameVector
 251 }
 252
 253 func (s EmptyStat) IsZero() bool {
 254         return true
 255 }
 256
 257 func (s EmptyStat) Type() StatType {
 258         return Empty
 259 }
 260
 261 // ReduceSimpleCounterStatIndex returns reduced SimpleCounterStat s for index i.
 262 func ReduceSimpleCounterStatIndex(s SimpleCounterStat, i int) uint64 {
 263         var val uint64
 264         for _, w := range s {
 265                 val += uint64(w[i])
 266         }
 267         return val
 268 }
 269
 270 // ReduceCombinedCounterStatIndex returns reduced CombinedCounterStat s for index i.
 271 func ReduceCombinedCounterStatIndex(s CombinedCounterStat, i int) [2]uint64 {
 272         var val [2]uint64
 273         for _, w := range s {
 274                 val[0] += w[i][0]
 275                 val[1] += w[i][1]
 276         }
 277         return val
 278 }