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