You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by ne...@apache.org on 2016/10/28 20:15:57 UTC
[19/30] incubator-trafficcontrol git commit: Add TM2 godoc comments
Add TM2 godoc comments
Project: http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/commit/be2bb6b7
Tree: http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/tree/be2bb6b7
Diff: http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/diff/be2bb6b7
Branch: refs/heads/master
Commit: be2bb6b78ac387f58acd654e2c0278052ec64633
Parents: 75efb49
Author: Robert Butts <ro...@gmail.com>
Authored: Fri Oct 21 14:57:03 2016 -0600
Committer: Dave Neuman <ne...@apache.org>
Committed: Fri Oct 28 14:00:36 2016 -0600
----------------------------------------------------------------------
.../traffic_monitor/cache/astats.go | 21 ++--------
.../experimental/traffic_monitor/cache/cache.go | 13 +++++-
.../traffic_monitor/config/config.go | 15 +++++--
.../traffic_monitor/deliveryservice/stat.go | 9 +++++
.../traffic_monitor/deliveryservicedata/stat.go | 42 ++++++++++++++++++++
.../experimental/traffic_monitor/enum/enum.go | 23 +++++++++--
.../manager/cacheavailablestatus.go | 7 ++++
.../traffic_monitor/manager/datarequest.go | 13 ++++++
.../traffic_monitor/manager/dsstats.go | 5 +++
.../traffic_monitor/manager/events.go | 4 ++
.../traffic_monitor/manager/healthresult.go | 5 +++
.../traffic_monitor/manager/lastkbpsstats.go | 3 ++
.../traffic_monitor/manager/manager.go | 1 +
.../traffic_monitor/manager/monitorconfig.go | 4 ++
.../traffic_monitor/manager/opsconfig.go | 3 ++
.../traffic_monitor/manager/peer.go | 1 +
.../traffic_monitor/manager/stathistory.go | 4 ++
.../traffic_monitor/manager/uintman.go | 4 ++
.../traffic_monitor/peer/crstates.go | 24 ++++++++++-
.../experimental/traffic_monitor/peer/peer.go | 4 ++
.../traffic_monitor/srvhttp/srvhttp.go | 29 +++++++++++++-
.../traffic_monitor/traffic_monitor.go | 3 ++
.../trafficopsdata/trafficopsdata.go | 4 ++
.../trafficopswrapper/trafficopswrapper.go | 6 +++
.../experimental/traffic_monitor/version.go | 1 +
25 files changed, 219 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/cache/astats.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/cache/astats.go b/traffic_monitor/experimental/traffic_monitor/cache/astats.go
index ad658f8..55bbd6f 100644
--- a/traffic_monitor/experimental/traffic_monitor/cache/astats.go
+++ b/traffic_monitor/experimental/traffic_monitor/cache/astats.go
@@ -2,14 +2,15 @@ package cache
import (
"encoding/json"
- "io"
)
+// Astats contains ATS data returned from the Astats ATS plugin. This includes generic stats, as well as fixed system stats.
type Astats struct {
Ats map[string]interface{} `json:"ats"`
System AstatsSystem `json:"system"`
}
+// AstatsSystem represents fixed system stats returne from ATS by the Astats plugin.
type AstatsSystem struct {
InfName string `json:"inf.name"`
InfSpeed int `json:"inf.speed"`
@@ -22,25 +23,9 @@ type AstatsSystem struct {
AstatsLoad int `json:"astatsLoad"`
}
-type AstatsAdapter struct{}
-
+// Unmarshal unmarshalls the given bytes, which must be JSON Astats data, into an Astats object.
func Unmarshal(body []byte) (Astats, error) {
var aStats Astats
err := json.Unmarshal(body, &aStats)
return aStats, err
}
-
-func (AstatsAdapter) Transform(r io.Reader) ([]Astats, error) {
- dec := json.NewDecoder(r)
- var as []Astats
-
- for {
- var a Astats
- if err := dec.Decode(&a); err == io.EOF {
- return as, nil
- } else if err != nil {
- return as, err
- }
- as = append(as, a)
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/cache/cache.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/cache/cache.go b/traffic_monitor/experimental/traffic_monitor/cache/cache.go
index f679cf5..0d5a95c 100644
--- a/traffic_monitor/experimental/traffic_monitor/cache/cache.go
+++ b/traffic_monitor/experimental/traffic_monitor/cache/cache.go
@@ -17,6 +17,7 @@ import (
"time"
)
+// Handler is a cache handler, which fulfills the common/handler `Handler` interface.
type Handler struct {
ResultChannel chan Result
Notify int
@@ -25,20 +26,22 @@ type Handler struct {
MultipleSpaceRegex *regexp.Regexp
}
-// NewHandler does NOT precomputes stat data before calling ResultChannel, and Result.Precomputed will be nil
+// NewHandler returns a new cache handler. Note this handler does NOT precomputes stat data before calling ResultChannel, and Result.Precomputed will be nil
func NewHandler() Handler {
return Handler{ResultChannel: make(chan Result), MultipleSpaceRegex: regexp.MustCompile(" +")}
}
-// NewPrecomputeHandler precomputes stat data and populates result.Precomputed before passing to ResultChannel.
+// NewPrecomputeHandler constructs a new cache Handler, which precomputes stat data and populates result.Precomputed before passing to ResultChannel.
func NewPrecomputeHandler(toData todata.TODataThreadsafe, peerStates peer.CRStatesPeersThreadsafe) Handler {
return Handler{ResultChannel: make(chan Result), MultipleSpaceRegex: regexp.MustCompile(" +"), ToData: &toData, PeerStates: &peerStates}
}
+// Precompute returns whether this handler precomputes data before passing the result to the ResultChannel
func (handler Handler) Precompute() bool {
return handler.ToData != nil && handler.PeerStates != nil
}
+// PrecomputedData represents data parsed and pre-computed from the Result.
type PrecomputedData struct {
DeliveryServiceStats map[enum.DeliveryServiceName]dsdata.Stat
OutBytes int64
@@ -47,6 +50,7 @@ type PrecomputedData struct {
Reporting bool
}
+// Result is the data result returned by a cache.
type Result struct {
ID enum.CacheName
Available bool
@@ -59,6 +63,7 @@ type Result struct {
PollFinished chan<- uint64
}
+// Vitals is the vitals data returned from a cache.
type Vitals struct {
LoadAvg float64
BytesOut int64
@@ -67,16 +72,19 @@ type Vitals struct {
MaxKbpsOut int64
}
+// Stat is a generic stat, including the untyped value and the time the stat was taken.
type Stat struct {
Time int64 `json:"time"`
Value interface{} `json:"value"`
}
+// Stats is designed for returning via the API. It contains result history for each cache, as well as common API data.
type Stats struct {
srvhttp.CommonAPIData
Caches map[enum.CacheName]map[string][]Stat `json:"caches"`
}
+// Filter filters whether stats and caches should be returned from a data set.
type Filter interface {
UseStat(name string) bool
UseCache(name enum.CacheName) bool
@@ -126,6 +134,7 @@ func StatsMarshall(statHistory map[enum.CacheName][]Result, filter Filter, param
return json.Marshal(stats)
}
+// Handle handles results fetched from a cache, parsing the raw Reader data and passing it along to a chan for further processing.
func (handler Handler) Handle(id string, r io.Reader, err error, pollID uint64, pollFinished chan<- uint64) {
log.Debugf("poll %v %v handle start\n", pollID, time.Now())
result := Result{
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/config/config.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/config/config.go b/traffic_monitor/experimental/traffic_monitor/config/config.go
index f8bbe30..9e56f51 100644
--- a/traffic_monitor/experimental/traffic_monitor/config/config.go
+++ b/traffic_monitor/experimental/traffic_monitor/config/config.go
@@ -6,12 +6,19 @@ import (
"time"
)
+// LogLocation is a location to log to. This may be stdout, stderr, null (/dev/null), or a valid file path.
type LogLocation string
-const LogLocationStdout = "stdout"
-const LogLocationStderr = "stderr"
-const LogLocationNull = "null"
+const (
+ // LogLocationStdout indicates the stdout IO stream
+ LogLocationStdout = "stdout"
+ // LogLocationStderr indicates the stderr IO stream
+ LogLocationStderr = "stderr"
+ // LogLocationNull indicates the null IO stream (/dev/null)
+ LogLocationNull = "null"
+)
+// Config is the configuration for the application. It includes myriad data, such as polling intervals and log locations.
type Config struct {
CacheHealthPollingInterval time.Duration `json:"-"`
CacheStatPollingInterval time.Duration `json:"-"`
@@ -31,6 +38,7 @@ type Config struct {
ServeWriteTimeout time.Duration `json:"-"`
}
+// DefaultConfig is the default configuration for the application, if no configuration file is given, or if a given config setting doesn't exist in the config file.
var DefaultConfig = Config{
CacheHealthPollingInterval: 6 * time.Second,
CacheStatPollingInterval: 6 * time.Second,
@@ -76,6 +84,7 @@ func (c *Config) MarshalJSON() ([]byte, error) {
})
}
+// UnmarshalJSON populates this config object from given JSON bytes.
func (c *Config) UnmarshalJSON(data []byte) error {
type Alias Config
aux := &struct {
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/deliveryservice/stat.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/deliveryservice/stat.go b/traffic_monitor/experimental/traffic_monitor/deliveryservice/stat.go
index 2fe8586..d8dd30c 100644
--- a/traffic_monitor/experimental/traffic_monitor/deliveryservice/stat.go
+++ b/traffic_monitor/experimental/traffic_monitor/deliveryservice/stat.go
@@ -22,6 +22,7 @@ type Stats struct {
DeliveryService map[enum.DeliveryServiceName]dsdata.Stat `json:"deliveryService"`
}
+// Copy performs a deep copy of this Stats object.
func (s Stats) Copy() Stats {
b := NewStats()
for k, v := range s.DeliveryService {
@@ -30,6 +31,7 @@ func (s Stats) Copy() Stats {
return b
}
+// Get returns the stats for the given delivery service, and whether it exists.
func (s Stats) Get(name enum.DeliveryServiceName) (dsdata.StatReadonly, bool) {
ds, ok := s.DeliveryService[name]
return ds, ok
@@ -120,10 +122,12 @@ type LastStats struct {
Caches map[enum.CacheName]LastStatsData
}
+// NewLastStats returns a new LastStats object, initializing internal pointer values.
func NewLastStats() LastStats {
return LastStats{DeliveryServices: map[enum.DeliveryServiceName]LastDSStat{}, Caches: map[enum.CacheName]LastStatsData{}}
}
+// Copy performs a deep copy of this LastStats object.
func (a LastStats) Copy() LastStats {
b := NewLastStats()
for k, v := range a.DeliveryServices {
@@ -144,6 +148,7 @@ type LastDSStat struct {
Total LastStatsData
}
+// Copy performs a deep copy of this LastDSStat object.
func (a LastDSStat) Copy() LastDSStat {
b := LastDSStat{
CacheGroups: map[enum.CacheGroupName]LastStatsData{},
@@ -171,6 +176,7 @@ func newLastDSStat() LastDSStat {
}
}
+// LastStatsData contains the last stats and per-second calculations for bytes and status codes received from a cache.
type LastStatsData struct {
Bytes LastStatData
Status2xx LastStatData
@@ -190,6 +196,7 @@ func (a LastStatsData) Sum(b LastStatsData) LastStatsData {
}
}
+// LastStatData contains the value, time it was received, and per-second calculation since the previous stat, for a stat from a cache.
type LastStatData struct {
PerSec float64
Stat int64
@@ -204,6 +211,7 @@ func (a LastStatData) Sum(b LastStatData) LastStatData {
}
}
+// BytesPerKilobit is the number of bytes in a kilobit.
const BytesPerKilobit = 125
func addLastStat(lastData LastStatData, newStat int64, newStatTime time.Time) (LastStatData, error) {
@@ -374,6 +382,7 @@ func addPerSecStats(statHistory map[enum.CacheName][]cache.Result, dsStats Stats
return dsStats, lastStats
}
+// CreateStats aggregates and creates statistics from given stat history. It returns the created stats, information about these stats necessary for the next calculation, and any error.
func CreateStats(statHistory map[enum.CacheName][]cache.Result, toData todata.TOData, crStates peer.Crstates, lastStats LastStats, now time.Time) (Stats, LastStats, error) {
start := time.Now()
dsStats := NewStats()
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/deliveryservicedata/stat.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/deliveryservicedata/stat.go b/traffic_monitor/experimental/traffic_monitor/deliveryservicedata/stat.go
index a05b391..c9eb77f 100644
--- a/traffic_monitor/experimental/traffic_monitor/deliveryservicedata/stat.go
+++ b/traffic_monitor/experimental/traffic_monitor/deliveryservicedata/stat.go
@@ -16,7 +16,10 @@ type Filter interface {
WithinStatHistoryMax(int) bool
}
+// StatName is the name of a stat.
type StatName string
+
+// StatOld is the old JSON representation of a stat, from Traffic Monitor 1.0.
type StatOld struct {
Time int64 `json:"time"`
Value string `json:"value"`
@@ -24,16 +27,19 @@ type StatOld struct {
Index int `json:"index,omitempty"` // TODO set? remove?
}
+// StatsOld is the old JSON representation of stats, from Traffic Monitor 1.0. It is designed to be serialized and returns from an API, and includes stat history for each delivery service, as well as data common to most endpoints.
type StatsOld struct {
DeliveryService map[enum.DeliveryServiceName]map[StatName][]StatOld `json:"deliveryService"`
srvhttp.CommonAPIData
}
+// StatsReadonly is a read-only interface for delivery service Stats, designed to be passed to multiple goroutine readers.
type StatsReadonly interface {
Get(enum.DeliveryServiceName) (StatReadonly, bool)
JSON(Filter, url.Values) StatsOld
}
+// StatReadonly is a read-only interface for a delivery service Stat, designed to be passed to multiple goroutine readers.
type StatReadonly interface {
Copy() Stat
Common() StatCommonReadonly
@@ -42,6 +48,7 @@ type StatReadonly interface {
Total() StatCacheStats
}
+// StatCommonReadonly is a read-only interface for a delivery service's common Stat data, designed to be passed to multiple goroutine readers.
type StatCommonReadonly interface {
Copy() StatCommon
CachesConfigured() StatInt
@@ -53,26 +60,36 @@ type StatCommonReadonly interface {
CachesAvailable() StatInt
}
+// StatMeta includes metadata about a particular stat.
type StatMeta struct {
Time int `json:"time"`
}
+
+// StatFloat is a float stat, combined with its metadata
type StatFloat struct {
StatMeta
Value float64 `json:"value"`
}
+
+// StatBool is a boolean stat, combined with its metadata
type StatBool struct {
StatMeta
Value bool `json:"value"`
}
+
+// StatInt is an integer stat, combined with its metadata
type StatInt struct {
StatMeta
Value int64 `json:"value"`
}
+
+// StatString is a string stat, combined with its metadata
type StatString struct {
StatMeta
Value string `json:"value"`
}
+// StatCommon contains stat data common to most delivery service stats.
type StatCommon struct {
CachesConfiguredNum StatInt `json:"caches_configured"`
CachesReporting map[enum.CacheName]bool `json:"caches_reporting"`
@@ -83,6 +100,7 @@ type StatCommon struct {
CachesAvailableNum StatInt `json:"caches_available"`
}
+// Copy returns a deep copy of this StatCommon object.
func (a StatCommon) Copy() StatCommon {
b := a
for k, v := range a.CachesReporting {
@@ -91,13 +109,18 @@ func (a StatCommon) Copy() StatCommon {
return b
}
+// CachesConfigured returns the number of caches configured for this delivery service stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) CachesConfigured() StatInt {
return a.CachesConfiguredNum
}
+
+// CacheReporting returns the number of caches reporting for this delivery service stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) CacheReporting(name enum.CacheName) (bool, bool) {
c, ok := a.CachesReporting[name]
return c, ok
}
+
+// CachesReportingNames returns the list of caches reporting for this delivery service stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) CachesReportingNames() []enum.CacheName {
names := make([]enum.CacheName, 0, len(a.CachesReporting))
for name := range a.CachesReporting {
@@ -105,18 +128,28 @@ func (a StatCommon) CachesReportingNames() []enum.CacheName {
}
return names
}
+
+// Error returns the error string of this delivery service stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) Error() StatString {
return a.ErrorStr
}
+
+// Status returns the status string of this delivery service stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) Status() StatString {
return a.StatusStr
}
+
+// Healthy returns whether this delivery service is considered healthy by this stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) Healthy() StatBool {
return a.IsHealthy
}
+
+// Available returns whether this delivery service is considered available by this stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) Available() StatBool {
return a.IsAvailable
}
+
+// CachesAvailable returns the number of caches available to the delivery service in this stat. It is part of the StatCommonReadonly interface.
func (a StatCommon) CachesAvailable() StatInt {
return a.CachesAvailableNum
}
@@ -141,6 +174,7 @@ type StatCacheStats struct {
TpsTotal StatInt `json:"tps_total"`
}
+// Sum adds the given cache stats to this cache stats. Numeric values are summed; strings are appended.
func (a StatCacheStats) Sum(b StatCacheStats) StatCacheStats {
return StatCacheStats{
OutBytes: StatInt{Value: a.OutBytes.Value + b.OutBytes.Value},
@@ -160,6 +194,7 @@ func (a StatCacheStats) Sum(b StatCacheStats) StatCacheStats {
}
}
+// Stat represents a complete delivery service stat, for a given poll, or at the time requested.
type Stat struct {
CommonStats StatCommon
CacheGroups map[enum.CacheGroupName]StatCacheStats
@@ -169,8 +204,10 @@ type Stat struct {
TotalStats StatCacheStats
}
+// ErrNotProcessedStat indicates a stat received is not used by Traffic Monitor, nor returned by any API endpoint. Receiving this error indicates the stat has been discarded.
var ErrNotProcessedStat = errors.New("This stat is not used.")
+// NewStat returns a new delivery service Stat, initializing pointer members.
func NewStat() *Stat {
return &Stat{
CacheGroups: map[enum.CacheGroupName]StatCacheStats{},
@@ -181,6 +218,7 @@ func NewStat() *Stat {
}
}
+// Copy performs a deep copy of this Stat. It does not modify, and is thus safe for multiple goroutines.
func (a Stat) Copy() Stat {
b := Stat{
CommonStats: a.CommonStats.Copy(),
@@ -205,20 +243,24 @@ func (a Stat) Copy() Stat {
return b
}
+// Common returns the common stat data for this stat. It is part of the StatCommonReadonly interface.
func (a Stat) Common() StatCommonReadonly {
return a.CommonStats
}
+// CacheGroup returns the data for the given cachegroup in this stat. It is part of the StatCommonReadonly interface.
func (a Stat) CacheGroup(name enum.CacheGroupName) (StatCacheStats, bool) {
c, ok := a.CacheGroups[name]
return c, ok
}
+// Type returns the aggregated data for the given cache type in this stat. It is part of the StatCommonReadonly interface.
func (a Stat) Type(name enum.CacheType) (StatCacheStats, bool) {
t, ok := a.Types[name]
return t, ok
}
+// Total returns the aggregated total data in this stat. It is part of the StatCommonReadonly interface.
func (a Stat) Total() StatCacheStats {
return a.TotalStats
}
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/enum/enum.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/enum/enum.go b/traffic_monitor/experimental/traffic_monitor/enum/enum.go
index b0547da..e028a74 100644
--- a/traffic_monitor/experimental/traffic_monitor/enum/enum.go
+++ b/traffic_monitor/experimental/traffic_monitor/enum/enum.go
@@ -6,22 +6,31 @@ import (
"strings"
)
+// TrafficMonitorName is the hostname of a Traffic Monitor peer.
type TrafficMonitorName string
+// CacheName is the hostname of a CDN cache.
type CacheName string
+// CacheGroupName is the name of a CDN cachegroup.
type CacheGroupName string
+// DeliveryServiceName is the name of a CDN delivery service.
type DeliveryServiceName string
+// CacheType is the type (or tier) of a CDN cache.
type CacheType string
const (
- CacheTypeEdge = CacheType("EDGE")
- CacheTypeMid = CacheType("MID")
+ // CacheTypeEdge represents an edge cache.
+ CacheTypeEdge = CacheType("EDGE")
+ // CacheTypeMid represents a mid cache.
+ CacheTypeMid = CacheType("MID")
+ // CacheTypeInvalid represents an cache type enumeration. Note this is the default construction for a CacheType.
CacheTypeInvalid = CacheType("")
)
+// String returns a string representation of this cache type.
func (t CacheType) String() string {
switch t {
case CacheTypeEdge:
@@ -33,6 +42,7 @@ func (t CacheType) String() string {
}
}
+// CacheTypeFromString returns a cache type object from its string representation, or CacheTypeInvalid if the string is not a valid type.
func CacheTypeFromString(s string) CacheType {
s = strings.ToLower(s)
switch s {
@@ -49,11 +59,15 @@ func CacheTypeFromString(s string) CacheType {
type DSType string
const (
- DSTypeHTTP = DSType("http")
- DSTypeDNS = DSType("dns")
+ // DSTypeHTTP represents an HTTP delivery service
+ DSTypeHTTP = DSType("http")
+ // DSTypeDNS represents a DNS delivery service
+ DSTypeDNS = DSType("dns")
+ // DSTypeInvalid represents an invalid delivery service type enumeration. Note this is the default construction for a DSType.
DSTypeInvalid = DSType("")
)
+// String returns a string representation of this delivery service type.
func (t DSType) String() string {
switch t {
case DSTypeHTTP:
@@ -65,6 +79,7 @@ func (t DSType) String() string {
}
}
+// DSTypeFromString returns a delivery service type object from its string representation, or DSTypeInvalid if the string is not a valid type.
func DSTypeFromString(s string) DSType {
s = strings.ToLower(s)
switch s {
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/cacheavailablestatus.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/cacheavailablestatus.go b/traffic_monitor/experimental/traffic_monitor/manager/cacheavailablestatus.go
index ab05e1a..c81232d 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/cacheavailablestatus.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/cacheavailablestatus.go
@@ -9,18 +9,22 @@ import (
// TODO put somewhere more generic
const CacheAvailableStatusReported = "REPORTED"
+// CacheAvailableStatus is the available status of the given cache. It includes a boolean available/unavailable flag, and a descriptive string.
type CacheAvailableStatus struct {
Available bool
Status string
}
+// CacheAvailableStatuses is the available status of each cache.
type CacheAvailableStatuses map[enum.CacheName]CacheAvailableStatus
+// CacheAvailableStatusThreadsafe wraps a map of cache available statuses to be safe for multiple reader goroutines and one writer.
type CacheAvailableStatusThreadsafe struct {
caches *CacheAvailableStatuses
m *sync.RWMutex
}
+// Copy copies this CacheAvailableStatuses. It does not modify, and thus is safe for multiple reader goroutines.
func (a CacheAvailableStatuses) Copy() CacheAvailableStatuses {
b := CacheAvailableStatuses(map[enum.CacheName]CacheAvailableStatus{})
for k, v := range a {
@@ -29,17 +33,20 @@ func (a CacheAvailableStatuses) Copy() CacheAvailableStatuses {
return b
}
+// NewCacheAvailableStatusThreadsafe creates and returns a new CacheAvailableStatusThreadsafe, initializing internal pointer values.
func NewCacheAvailableStatusThreadsafe() CacheAvailableStatusThreadsafe {
c := CacheAvailableStatuses(map[enum.CacheName]CacheAvailableStatus{})
return CacheAvailableStatusThreadsafe{m: &sync.RWMutex{}, caches: &c}
}
+// Get returns the internal map of cache statuses. The returned map MUST NOT be modified. If modification is necessary, copy.
func (o *CacheAvailableStatusThreadsafe) Get() CacheAvailableStatuses {
o.m.RLock()
defer o.m.RUnlock()
return *o.caches
}
+// Set sets the internal map of cache availability. This MUST NOT be called by multiple goroutines.
func (o *CacheAvailableStatusThreadsafe) Set(v CacheAvailableStatuses) {
o.m.Lock()
*o.caches = v
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/datarequest.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/datarequest.go b/traffic_monitor/experimental/traffic_monitor/manager/datarequest.go
index 860d877..e6da58a 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/datarequest.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/datarequest.go
@@ -22,14 +22,17 @@ import (
towrap "github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/trafficopswrapper"
)
+// JSONEvents represents the structure we wish to serialize to JSON, for Events.
type JSONEvents struct {
Events []Event `json:"events"`
}
+// CacheState represents the available state of a cache.
type CacheState struct {
Value bool `json:"value"`
}
+// APIPeerStates contains the data to be returned for an API call to get the peer states of a Traffic Monitor. This contains common API data returned by most endpoints, and a map of peers, to caches' states.
type APIPeerStates struct {
srvhttp.CommonAPIData
Peers map[enum.TrafficMonitorName]map[enum.CacheName][]CacheState `json:"peers"`
@@ -56,6 +59,7 @@ type CacheStatFilter struct {
cacheTypes map[enum.CacheName]enum.CacheType
}
+// UseCache returns whether the given cache is in the filter.
func (f *CacheStatFilter) UseCache(name enum.CacheName) bool {
if _, inHosts := f.hosts[name]; len(f.hosts) != 0 && !inHosts {
return false
@@ -66,6 +70,7 @@ func (f *CacheStatFilter) UseCache(name enum.CacheName) bool {
return true
}
+// UseStat returns whether the given stat is in the filter.
func (f *CacheStatFilter) UseStat(statName string) bool {
if len(f.statsToUse) == 0 {
return true
@@ -82,6 +87,7 @@ func (f *CacheStatFilter) UseStat(statName string) bool {
return false
}
+// WithinStatHistoryMax returns whether the given history index is less than the max history of this filter.
func (f *CacheStatFilter) WithinStatHistoryMax(n int) bool {
if f.historyCount == 0 {
return true
@@ -172,6 +178,7 @@ type DSStatFilter struct {
dsTypes map[enum.DeliveryServiceName]enum.DSType
}
+// UseDeliveryService returns whether the given delivery service is in this filter.
func (f *DSStatFilter) UseDeliveryService(name enum.DeliveryServiceName) bool {
if _, inDSes := f.deliveryServices[name]; len(f.deliveryServices) != 0 && !inDSes {
return false
@@ -182,6 +189,7 @@ func (f *DSStatFilter) UseDeliveryService(name enum.DeliveryServiceName) bool {
return true
}
+// UseStat returns whether the given stat is in this filter.
func (f *DSStatFilter) UseStat(statName string) bool {
if len(f.statsToUse) == 0 {
return true
@@ -198,6 +206,7 @@ func (f *DSStatFilter) UseStat(statName string) bool {
return false
}
+// WithinStatHistoryMax returns whether the given history index is less than the max history of this filter.
func (f *DSStatFilter) WithinStatHistoryMax(n int) bool {
if f.historyCount == 0 {
return true
@@ -289,6 +298,7 @@ type PeerStateFilter struct {
cacheTypes map[enum.CacheName]enum.CacheType
}
+// UsePeer returns whether the given Traffic Monitor peer is in this filter.
func (f *PeerStateFilter) UsePeer(name enum.TrafficMonitorName) bool {
if _, inPeers := f.peersToUse[name]; len(f.peersToUse) != 0 && !inPeers {
return false
@@ -296,6 +306,7 @@ func (f *PeerStateFilter) UsePeer(name enum.TrafficMonitorName) bool {
return true
}
+// UseCache returns whether the given cache is in this filter.
func (f *PeerStateFilter) UseCache(name enum.CacheName) bool {
if f.cacheType != enum.CacheTypeInvalid && f.cacheTypes[name] != f.cacheType {
return false
@@ -317,6 +328,7 @@ func (f *PeerStateFilter) UseCache(name enum.CacheName) bool {
return false
}
+// WithinStatHistoryMax returns whether the given history index is less than the max history of this filter.
func (f *PeerStateFilter) WithinStatHistoryMax(n int) bool {
if f.historyCount == 0 {
return true
@@ -697,6 +709,7 @@ func createAPIPeerStates(peerStates map[enum.TrafficMonitorName]peer.Crstates, f
return apiPeerStates
}
+// Stats contains statistics data about this running app. Designed to be returned via an API endpoint.
type Stats struct {
MaxMemoryMB uint64 `json:"Max Memory (MB)"`
GitRevision string `json:"git-revision"`
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/dsstats.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/dsstats.go b/traffic_monitor/experimental/traffic_monitor/manager/dsstats.go
index 6ca7b8b..1745c5e 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/dsstats.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/dsstats.go
@@ -6,26 +6,31 @@ import (
"sync"
)
+// DSStatsThreadsafe wraps a deliveryservice.Stats object to be safe for multiple reader goroutines and a single writer.
type DSStatsThreadsafe struct {
dsStats *ds.Stats
m *sync.RWMutex
}
+// DSStatsReader permits reading of a dsdata.Stats object, but not writing. This is designed so a Stats object can safely be passed to multiple goroutines, without worry one may unsafely write.
type DSStatsReader interface {
Get() dsdata.StatsReadonly
}
+// NewDSStatsThreadsafe returns a deliveryservice.Stats object wrapped to be safe for multiple readers and a single writer.
func NewDSStatsThreadsafe() DSStatsThreadsafe {
s := ds.NewStats()
return DSStatsThreadsafe{m: &sync.RWMutex{}, dsStats: &s}
}
+// Get returns a Stats object safe for reading by multiple goroutines
func (o *DSStatsThreadsafe) Get() dsdata.StatsReadonly {
o.m.RLock()
defer o.m.RUnlock()
return *o.dsStats
}
+// Set sets the internal Stats object. This MUST NOT be called by multiple goroutines.
func (o *DSStatsThreadsafe) Set(newDsStats ds.Stats) {
o.m.Lock()
*o.dsStats = newDsStats
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/events.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/events.go b/traffic_monitor/experimental/traffic_monitor/manager/events.go
index 3d6c139..674186b 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/events.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/events.go
@@ -6,6 +6,7 @@ import (
"github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/enum"
)
+// Event represents an event change in aggregated data. For example, a cache being marked as unavailable.
type Event struct {
Index uint64 `json:"index"`
Time int64 `json:"time"`
@@ -16,6 +17,7 @@ type Event struct {
Available bool `json:"isAvailable"`
}
+// EventsThreadsafe provides safe access for multiple goroutines readers and a single writer to a stored Events slice.
type EventsThreadsafe struct {
events *[]Event
m *sync.RWMutex
@@ -29,11 +31,13 @@ func copyEvents(a []Event) []Event {
return b
}
+// NewEventsThreadsafe creates a new single-writer-multiple-reader Threadsafe object
func NewEventsThreadsafe(maxEvents uint64) EventsThreadsafe {
i := uint64(0)
return EventsThreadsafe{m: &sync.RWMutex{}, events: &[]Event{}, nextIndex: &i, max: maxEvents}
}
+// Get returns the internal slice of Events for reading. This MUST NOT be modified. If modification is necessary, copy the slice.
func (o *EventsThreadsafe) Get() []Event {
o.m.RLock()
defer o.m.RUnlock()
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/healthresult.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/healthresult.go b/traffic_monitor/experimental/traffic_monitor/manager/healthresult.go
index 5074f26..5cefd06 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/healthresult.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/healthresult.go
@@ -13,13 +13,16 @@ import (
todata "github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/trafficopsdata"
)
+// DurationMap represents a map of cache names to durations
type DurationMap map[enum.CacheName]time.Duration
+// DurationMapThreadsafe wraps a DurationMap in an object safe for a single writer and multiple readers
type DurationMapThreadsafe struct {
durationMap *DurationMap
m *sync.RWMutex
}
+// Copy copies this duration map.
func (a DurationMap) Copy() DurationMap {
b := DurationMap{}
for k, v := range a {
@@ -28,6 +31,7 @@ func (a DurationMap) Copy() DurationMap {
return b
}
+// NewDurationMapThreadsafe returns a new DurationMapThreadsafe safe for multiple readers and a single writer goroutine.
func NewDurationMapThreadsafe() DurationMapThreadsafe {
m := DurationMap{}
return DurationMapThreadsafe{m: &sync.RWMutex{}, durationMap: &m}
@@ -40,6 +44,7 @@ func (o *DurationMapThreadsafe) Get() DurationMap {
return *o.durationMap
}
+// Set sets the internal duration map. This MUST NOT be called by multiple goroutines.
func (o *DurationMapThreadsafe) Set(d DurationMap) {
o.m.Lock()
*o.durationMap = d
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/lastkbpsstats.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/lastkbpsstats.go b/traffic_monitor/experimental/traffic_monitor/manager/lastkbpsstats.go
index 89ffa6b..3751cec 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/lastkbpsstats.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/lastkbpsstats.go
@@ -5,11 +5,13 @@ import (
"sync"
)
+// LastStatsThreadsafe wraps a deliveryservice.LastStats object to be safe for multiple readers and one writer.
type LastStatsThreadsafe struct {
stats *ds.LastStats
m *sync.RWMutex
}
+// NewLastStatsThreadsafe returns a wrapped a deliveryservice.LastStats object safe for multiple readers and one writer.
func NewLastStatsThreadsafe() LastStatsThreadsafe {
s := ds.NewLastStats()
return LastStatsThreadsafe{m: &sync.RWMutex{}, stats: &s}
@@ -22,6 +24,7 @@ func (o *LastStatsThreadsafe) Get() ds.LastStats {
return *o.stats
}
+// Set sets the internal LastStats object. This MUST NOT be called by multiple goroutines.
func (o *LastStatsThreadsafe) Set(s ds.LastStats) {
o.m.Lock()
*o.stats = s
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/manager.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/manager.go b/traffic_monitor/experimental/traffic_monitor/manager/manager.go
index 8d479b5..c362b33 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/manager.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/manager.go
@@ -17,6 +17,7 @@ import (
"github.com/davecheney/gmx"
)
+// StaticAppData encapsulates data about the app available at startup
type StaticAppData struct {
StartTime time.Time
GitRevision string
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/monitorconfig.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/monitorconfig.go b/traffic_monitor/experimental/traffic_monitor/manager/monitorconfig.go
index 2016116..ec82f2f 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/monitorconfig.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/monitorconfig.go
@@ -12,6 +12,7 @@ import (
"sync"
)
+// CopyTrafficMonitorConfigMap returns a deep copy of the given TrafficMonitorConfigMap
func CopyTrafficMonitorConfigMap(a *to.TrafficMonitorConfigMap) to.TrafficMonitorConfigMap {
b := to.TrafficMonitorConfigMap{}
b.TrafficServer = map[string]to.TrafficServer{}
@@ -41,11 +42,13 @@ func CopyTrafficMonitorConfigMap(a *to.TrafficMonitorConfigMap) to.TrafficMonito
return b
}
+// TrafficMonitorConfigMapThreadsafe encapsulates a TrafficMonitorConfigMap safe for multiple readers and a single writer.
type TrafficMonitorConfigMapThreadsafe struct {
monitorConfig *to.TrafficMonitorConfigMap
m *sync.RWMutex
}
+// NewTrafficMonitorConfigMapThreadsafe returns an encapsulated TrafficMonitorConfigMap safe for multiple readers and a single writer.
func NewTrafficMonitorConfigMapThreadsafe() TrafficMonitorConfigMapThreadsafe {
return TrafficMonitorConfigMapThreadsafe{monitorConfig: &to.TrafficMonitorConfigMap{}, m: &sync.RWMutex{}}
}
@@ -64,6 +67,7 @@ func (t *TrafficMonitorConfigMapThreadsafe) Set(c to.TrafficMonitorConfigMap) {
t.m.Unlock()
}
+// StartMonitorConfigManager runs the monitor config manager goroutine, and returns the threadsafe data which it sets.
func StartMonitorConfigManager(
monitorConfigPollChan <-chan to.TrafficMonitorConfigMap,
localStates peer.CRStatesThreadsafe,
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/opsconfig.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/opsconfig.go b/traffic_monitor/experimental/traffic_monitor/manager/opsconfig.go
index b2ba283..03448dc 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/opsconfig.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/opsconfig.go
@@ -23,16 +23,19 @@ type OpsConfigThreadsafe struct {
m *sync.RWMutex
}
+// NewOpsConfigThreadsafe returns a new single-writer-multiple-reader OpsConfig
func NewOpsConfigThreadsafe() OpsConfigThreadsafe {
return OpsConfigThreadsafe{m: &sync.RWMutex{}, opsConfig: &handler.OpsConfig{}}
}
+// Get gets the internal OpsConfig object. This MUST NOT be modified. If modification is necessary, copy the object.
func (o *OpsConfigThreadsafe) Get() handler.OpsConfig {
o.m.RLock()
defer o.m.RUnlock()
return *o.opsConfig
}
+// Set sets the internal OpsConfig object. This MUST NOT be called from multiple goroutines.
func (o *OpsConfigThreadsafe) Set(newOpsConfig handler.OpsConfig) {
o.m.Lock()
*o.opsConfig = newOpsConfig
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/peer.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/peer.go b/traffic_monitor/experimental/traffic_monitor/manager/peer.go
index 2bca917..7050940 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/peer.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/peer.go
@@ -76,6 +76,7 @@ func combineCrStates(peerStates map[enum.TrafficMonitorName]peer.Crstates, local
return combinedStates
}
+// CacheNameSlice is a slice of cache names, which fulfills the `sort.Interface` interface.
type CacheNameSlice []enum.CacheName
func (p CacheNameSlice) Len() int { return len(p) }
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/stathistory.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/stathistory.go b/traffic_monitor/experimental/traffic_monitor/manager/stathistory.go
index 8dda3e2..24edcf7 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/stathistory.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/stathistory.go
@@ -13,6 +13,7 @@ import (
todata "github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/trafficopsdata"
)
+// StatHistory is a map of cache names, to an array of result history from each cache.
type StatHistory map[enum.CacheName][]cache.Result
func copyStat(a []cache.Result) []cache.Result {
@@ -21,6 +22,7 @@ func copyStat(a []cache.Result) []cache.Result {
return b
}
+// Copy copies returns a deep copy of this StatHistory
func (a StatHistory) Copy() StatHistory {
b := StatHistory{}
for k, v := range a {
@@ -38,10 +40,12 @@ type StatHistoryThreadsafe struct {
max uint64
}
+// Max returns the max history to be stored for any cache
func (h StatHistoryThreadsafe) Max() uint64 {
return h.max
}
+// NewStatHistoryThreadsafe returns a new StatHistory safe for multiple readers and a single writer.
func NewStatHistoryThreadsafe(maxHistory uint64) StatHistoryThreadsafe {
h := StatHistory{}
return StatHistoryThreadsafe{m: &sync.RWMutex{}, statHistory: &h, max: maxHistory}
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/manager/uintman.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/manager/uintman.go b/traffic_monitor/experimental/traffic_monitor/manager/uintman.go
index d85e4a7..953308f 100644
--- a/traffic_monitor/experimental/traffic_monitor/manager/uintman.go
+++ b/traffic_monitor/experimental/traffic_monitor/manager/uintman.go
@@ -4,19 +4,23 @@ import (
"sync/atomic"
)
+// UintThreadsafe provides safe access for multiple goroutines readers and a single writer to a stored uint.
type UintThreadsafe struct {
val *uint64
}
+// NewUintThreadsafe returns a new single-writer-multiple-reader threadsafe uint
func NewUintThreadsafe() UintThreadsafe {
v := uint64(0)
return UintThreadsafe{val: &v}
}
+// Get gets the internal uint. This is safe for multiple readers
func (u *UintThreadsafe) Get() uint64 {
return atomic.LoadUint64(u.val)
}
+// Set sets the internal uint. This MUST NOT be called by multiple goroutines.
func (u *UintThreadsafe) Set(v uint64) {
atomic.StoreUint64(u.val, v)
}
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/peer/crstates.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/peer/crstates.go b/traffic_monitor/experimental/traffic_monitor/peer/crstates.go
index 83f7073..6458a9b 100644
--- a/traffic_monitor/experimental/traffic_monitor/peer/crstates.go
+++ b/traffic_monitor/experimental/traffic_monitor/peer/crstates.go
@@ -7,11 +7,14 @@ import (
"github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/enum"
)
+// Crstates includes availability data for caches and delivery services, as gathered and aggregated by this Traffic Monitor. It is designed to be served at an API endpoint primarily for Traffic Routers (Content Router) to consume.
+// TODO rename to `CRStates`
type Crstates struct {
Caches map[enum.CacheName]IsAvailable `json:"caches"`
Deliveryservice map[enum.DeliveryServiceName]Deliveryservice `json:"deliveryServices"`
}
+// NewCrstates creates a new CR states object, initializing pointer members.
func NewCrstates() Crstates {
return Crstates{
Caches: map[enum.CacheName]IsAvailable{},
@@ -19,6 +22,7 @@ func NewCrstates() Crstates {
}
}
+// Copy creates a deep copy of this object. It does not mutate, and is thus safe for multiple goroutines.
func (a Crstates) Copy() Crstates {
b := NewCrstates()
for k, v := range a.Caches {
@@ -30,6 +34,7 @@ func (a Crstates) Copy() Crstates {
return b
}
+// CopyDeliveryservices creates a deep copy of the delivery service availability data.. It does not mutate, and is thus safe for multiple goroutines.
func (a Crstates) CopyDeliveryservices() map[enum.DeliveryServiceName]Deliveryservice {
b := map[enum.DeliveryServiceName]Deliveryservice{}
for k, v := range a.Deliveryservice {
@@ -38,6 +43,7 @@ func (a Crstates) CopyDeliveryservices() map[enum.DeliveryServiceName]Deliveryse
return b
}
+// CopyCaches creates a deep copy of the cache availability data.. It does not mutate, and is thus safe for multiple goroutines.
func (a Crstates) CopyCaches() map[enum.CacheName]IsAvailable {
b := map[enum.CacheName]IsAvailable{}
for k, v := range a.Caches {
@@ -46,22 +52,25 @@ func (a Crstates) CopyCaches() map[enum.CacheName]IsAvailable {
return b
}
+// IsAvailable contains whether the given cache or delivery service is available. It is designed for JSON serialization, namely in the Traffic Monitor 1.0 API.
type IsAvailable struct {
IsAvailable bool `json:"isAvailable"`
}
+// Deliveryservice contains data about the availability of a particular delivery service, and which caches in that delivery service have been marked as unavailable.
type Deliveryservice struct {
DisabledLocations []enum.CacheName `json:"disabledLocations"`
IsAvailable bool `json:"isAvailable"`
}
+// CrstatesUnMarshall takes bytes of a JSON string, and unmarshals them into a Crstates object.
func CrstatesUnMarshall(body []byte) (Crstates, error) {
var crStates Crstates
-
err := json.Unmarshal(body, &crStates)
return crStates, err
}
+// CrstatesMarshall serializes the given Crstates into bytes.
func CrstatesMarshall(states Crstates) ([]byte, error) {
return json.Marshal(states)
}
@@ -74,6 +83,7 @@ type CRStatesThreadsafe struct {
m *sync.RWMutex
}
+// NewCRStatesThreadsafe creates a new CRStatesThreadsafe object safe for multiple goroutine readers and a single writer.
func NewCRStatesThreadsafe() CRStatesThreadsafe {
crs := NewCrstates()
return CRStatesThreadsafe{m: &sync.RWMutex{}, crStates: &crs}
@@ -95,54 +105,63 @@ func (t *CRStatesThreadsafe) GetDeliveryServices() map[enum.DeliveryServiceName]
return t.crStates.CopyDeliveryservices()
}
+// GetCache returns the availability data of the given cache. This does not mutate, and is thus safe for multiple goroutines to call.
func (t *CRStatesThreadsafe) GetCache(name enum.CacheName) IsAvailable {
t.m.RLock()
defer t.m.RUnlock()
return t.crStates.Caches[name]
}
+// GetCaches returns the availability data of all caches. This does not mutate, and is thus safe for multiple goroutines to call.
func (t *CRStatesThreadsafe) GetCaches() map[enum.CacheName]IsAvailable {
t.m.RLock()
defer t.m.RUnlock()
return t.crStates.CopyCaches()
}
+// GetDeliveryService returns the availability data of the given delivery service. This does not mutate, and is thus safe for multiple goroutines to call.
func (t *CRStatesThreadsafe) GetDeliveryService(name enum.DeliveryServiceName) Deliveryservice {
t.m.RLock()
defer t.m.RUnlock()
return t.crStates.Deliveryservice[name]
}
+// Set sets the internal Crstates data. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) Set(newCRStates Crstates) {
t.m.Lock()
*t.crStates = newCRStates
t.m.Unlock()
}
+// SetCache sets the internal availability data for a particular cache. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) SetCache(cacheName enum.CacheName, available IsAvailable) {
t.m.Lock()
t.crStates.Caches[cacheName] = available
t.m.Unlock()
}
+// DeleteCache deletes the given cache from the internal data. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) DeleteCache(name enum.CacheName) {
t.m.Lock()
delete(t.crStates.Caches, name)
t.m.Unlock()
}
+// SetDeliveryService sets the availability data for the given delivery service. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) SetDeliveryService(name enum.DeliveryServiceName, ds Deliveryservice) {
t.m.Lock()
t.crStates.Deliveryservice[name] = ds
t.m.Unlock()
}
+// SetDeliveryServices sets the availability data for all delivery service. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) SetDeliveryServices(deliveryServices map[enum.DeliveryServiceName]Deliveryservice) {
t.m.Lock()
t.crStates.Deliveryservice = deliveryServices
t.m.Unlock()
}
+// DeleteDeliveryService deletes the given delivery service from the internal data. This MUST NOT be called by multiple goroutines.
func (t *CRStatesThreadsafe) DeleteDeliveryService(name enum.DeliveryServiceName) {
t.m.Lock()
delete(t.crStates.Deliveryservice, name)
@@ -156,10 +175,12 @@ type CRStatesPeersThreadsafe struct {
m *sync.RWMutex
}
+// NewCRStatesPeersThreadsafe creates a new CRStatesPeers object safe for multiple goroutine readers and a single writer.
func NewCRStatesPeersThreadsafe() CRStatesPeersThreadsafe {
return CRStatesPeersThreadsafe{m: &sync.RWMutex{}, crStates: map[enum.TrafficMonitorName]Crstates{}}
}
+// Get returns the internal Traffic Monitor peer Crstates data. This MUST NOT be modified.
func (t *CRStatesPeersThreadsafe) Get() map[enum.TrafficMonitorName]Crstates {
t.m.RLock()
m := map[enum.TrafficMonitorName]Crstates{}
@@ -170,6 +191,7 @@ func (t *CRStatesPeersThreadsafe) Get() map[enum.TrafficMonitorName]Crstates {
return m
}
+// Set sets the internal Traffic Monitor peer Crstates data. This MUST NOT be called by multiple goroutines.
func (t *CRStatesPeersThreadsafe) Set(peerName enum.TrafficMonitorName, peerState Crstates) {
t.m.Lock()
t.crStates[peerName] = peerState
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/peer/peer.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/peer/peer.go b/traffic_monitor/experimental/traffic_monitor/peer/peer.go
index ae898eb..b6e9873 100644
--- a/traffic_monitor/experimental/traffic_monitor/peer/peer.go
+++ b/traffic_monitor/experimental/traffic_monitor/peer/peer.go
@@ -7,15 +7,18 @@ import (
"github.com/apache/incubator-trafficcontrol/traffic_monitor/experimental/traffic_monitor/enum"
)
+// Handler handles peer Traffic Monitor data, taking a raw reader, parsing the data, and passing a result object to the ResultChannel. This fulfills the common `Handler` interface.
type Handler struct {
ResultChannel chan Result
Notify int
}
+// NewHandler returns a new peer Handler.
func NewHandler() Handler {
return Handler{ResultChannel: make(chan Result)}
}
+// Result contains the data parsed from polling a peer Traffic Monitor.
type Result struct {
ID enum.TrafficMonitorName
Available bool
@@ -25,6 +28,7 @@ type Result struct {
PollFinished chan<- uint64
}
+// Handle handles a response from a polled Traffic Monitor peer, parsing the data and forwarding it to the ResultChannel.
func (handler Handler) Handle(id string, r io.Reader, err error, pollID uint64, pollFinished chan<- uint64) {
result := Result{
ID: enum.TrafficMonitorName(id),
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/srvhttp/srvhttp.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/srvhttp/srvhttp.go b/traffic_monitor/experimental/traffic_monitor/srvhttp/srvhttp.go
index 403b5a9..ebbad03 100644
--- a/traffic_monitor/experimental/traffic_monitor/srvhttp/srvhttp.go
+++ b/traffic_monitor/experimental/traffic_monitor/srvhttp/srvhttp.go
@@ -12,6 +12,7 @@ import (
"time"
)
+// GetCommonAPIData calculates and returns API data common to most endpoints
func GetCommonAPIData(params url.Values, t time.Time) CommonAPIData {
return CommonAPIData{
QueryParams: ParametersStr(params),
@@ -19,6 +20,7 @@ func GetCommonAPIData(params url.Values, t time.Time) CommonAPIData {
}
}
+// CommonAPIData contains generic data common to most endpoints.
type CommonAPIData struct {
QueryParams string `json:"pp"`
DateStr string `json:"date"`
@@ -33,7 +35,7 @@ type Server struct {
stoppableListenerWaitGroup sync.WaitGroup
}
-// Endpoints returns a map of HTTP paths to functions.
+// endpoints returns a map of HTTP paths to functions.
// This is a function because Go doesn't have constant map literals.
func (s Server) endpoints() (map[string]http.HandlerFunc, error) {
handleRoot, err := s.handleRootFunc()
@@ -143,29 +145,49 @@ func (s Server) Run(f GetDataFunc, addr string, readTimeout time.Duration, write
return nil
}
+// Type is the API request type which was received.
type Type int
const (
+ // TRConfig represents a data request for the Traffic Router config
TRConfig Type = (1 << iota)
+ // TRStateDerived represents a data request for the derived data, aggregated from all Traffic Monitor peers.
TRStateDerived
+ // TRStateSelf represents a data request for the cache health data only from this Traffic Monitor, not from its peers.
TRStateSelf
+ // CacheStats represents a data request for general cache stats
CacheStats
+ // DSStats represents a data request for delivery service stats
DSStats
+ // EventLog represents a data request for the event log
EventLog
+ // PeerStates represents a data request for the cache health data gathered from Traffic Monitor peers.
PeerStates
+ // StatSummary represents a data request for a summary of the gathered stats
StatSummary
+ // Stats represents a data request for stats
Stats
+ // ConfigDoc represents a data request for this app's configuration data.
ConfigDoc
+ // APICacheCount represents a data request for the total number of caches this Traffic Monitor polls, as received Traffic Ops.
APICacheCount
+ // APICacheAvailableCount represents a data request for the number of caches flagged as available by this Traffic Monitor
APICacheAvailableCount
+ // APICacheDownCount represents a data request for the number of caches flagged as unavailable by this Traffic Monitor
APICacheDownCount
+ // APIVersion represents a data request for this app's version
APIVersion
+ // APITrafficOpsURI represents a data request for the Traffic Ops URI this app is configured to query
APITrafficOpsURI
+ // APICacheStates represents a data request for a summary of the cache states
APICacheStates
+ // APIBandwidthKbps represents a data request for the total bandwidth of all caches polled
APIBandwidthKbps
+ // APIBandwidthCapacityKbps represents a data request for the total bandwidth capacity of all caches polled
APIBandwidthCapacityKbps
)
+// String returns a string representation of the API request type.
func (t Type) String() string {
switch t {
case TRConfig:
@@ -209,13 +231,17 @@ func (t Type) String() string {
}
}
+// Format is the format protocol the API response will be.
type Format int
const (
+ // XML represents that data should be serialized to XML
XML Format = (1 << iota)
+ // JSON represents that data should be serialized to JSON
JSON
)
+// DataRequest contains all the data about an API request necessary to form a response.
type DataRequest struct {
Type
Format
@@ -223,6 +249,7 @@ type DataRequest struct {
Parameters map[string][]string
}
+// GetDataFunc is a function which takes a DataRequest from a request made by a client, and returns the proper response to send to the client.
type GetDataFunc func(DataRequest) ([]byte, int)
// ParametersStr takes the URL query parameters, and returns a string as used by the Traffic Monitor 1.0 endpoints "pp" key.
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/traffic_monitor.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/traffic_monitor.go b/traffic_monitor/experimental/traffic_monitor/traffic_monitor.go
index 76cfdfc..3b810fa 100644
--- a/traffic_monitor/experimental/traffic_monitor/traffic_monitor.go
+++ b/traffic_monitor/experimental/traffic_monitor/traffic_monitor.go
@@ -19,7 +19,10 @@ import (
_ "github.com/davecheney/gmx"
)
+// GitRevision is the git revision of the app. The app SHOULD always be built with this set via the `-X` flag.
var GitRevision = "No Git Revision Specified. Please build with '-X main.GitRevision=${git rev-parse HEAD}'"
+
+// BuildTimestamp is the time the app was built. The app SHOULD always be built with this set via the `-X` flag.
var BuildTimestamp = "No Build Timestamp Specified. Please build with '-X main.BuildTimestamp=`date +'%Y-%M-%dT%H:%M:%S'`"
// getHostNameWithoutDomain returns the machine hostname, without domain information.
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/trafficopsdata/trafficopsdata.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/trafficopsdata/trafficopsdata.go b/traffic_monitor/experimental/traffic_monitor/trafficopsdata/trafficopsdata.go
index 0ca1238..1659ae1 100644
--- a/traffic_monitor/experimental/traffic_monitor/trafficopsdata/trafficopsdata.go
+++ b/traffic_monitor/experimental/traffic_monitor/trafficopsdata/trafficopsdata.go
@@ -41,10 +41,12 @@ func (d Regexes) DeliveryService(fqdn string) (enum.DeliveryServiceName, bool) {
return "", false
}
+// NewRegexes constructs a new Regexes object, initializing internal pointer members.
func NewRegexes() Regexes {
return Regexes{DirectMatches: map[string]enum.DeliveryServiceName{}, DotStartSlashDotFooSlashDotDotStar: map[string]enum.DeliveryServiceName{}, RegexMatch: map[*regexp.Regexp]enum.DeliveryServiceName{}}
}
+// TOData holds CDN data fetched from Traffic Ops.
type TOData struct {
DeliveryServiceServers map[enum.DeliveryServiceName][]enum.CacheName
ServerDeliveryServices map[enum.CacheName][]enum.DeliveryServiceName
@@ -54,6 +56,7 @@ type TOData struct {
ServerCachegroups map[enum.CacheName]enum.CacheGroupName
}
+// New returns a new empty TOData object, initializing pointer members.
func New() *TOData {
return &TOData{
DeliveryServiceServers: map[enum.DeliveryServiceName][]enum.CacheName{},
@@ -72,6 +75,7 @@ type TODataThreadsafe struct {
m *sync.RWMutex
}
+// NewThreadsafe returns a new TOData object, wrapped to be safe for multiple goroutine readers and a single writer.
func NewThreadsafe() TODataThreadsafe {
return TODataThreadsafe{m: &sync.RWMutex{}, toData: New()}
}
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/trafficopswrapper/trafficopswrapper.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/trafficopswrapper/trafficopswrapper.go b/traffic_monitor/experimental/traffic_monitor/trafficopswrapper/trafficopswrapper.go
index 110dd8f..246ef2f 100644
--- a/traffic_monitor/experimental/traffic_monitor/trafficopswrapper/trafficopswrapper.go
+++ b/traffic_monitor/experimental/traffic_monitor/trafficopswrapper/trafficopswrapper.go
@@ -7,21 +7,25 @@ import (
to "github.com/apache/incubator-trafficcontrol/traffic_ops/client"
)
+// ITrafficOpsSession provides an interface to the Traffic Ops client, so it may be wrapped or mocked.
type ITrafficOpsSession interface {
CRConfigRaw(cdn string) ([]byte, error)
TrafficMonitorConfigMap(cdn string) (*to.TrafficMonitorConfigMap, error)
Set(session *to.Session)
}
+// TrafficOpsSessionThreadsafe provides access to the Traffic Ops client safe for multiple goroutines. This fulfills the ITrafficOpsSession interface.
type TrafficOpsSessionThreadsafe struct {
session **to.Session // pointer-to-pointer, because we're given a pointer from the Traffic Ops package, and we don't want to copy it.
m *sync.Mutex
}
+// NewTrafficOpsSessionThreadsafe returns a new threadsafe TrafficOpsSessionThreadsafe wrapping the given `Session`.
func NewTrafficOpsSessionThreadsafe(s *to.Session) TrafficOpsSessionThreadsafe {
return TrafficOpsSessionThreadsafe{&s, &sync.Mutex{}}
}
+// CRConfigRaw returns the CRConfig from the Traffic Ops. This is safe for multiple goroutines.
func (s TrafficOpsSessionThreadsafe) CRConfigRaw(cdn string) ([]byte, error) {
s.m.Lock()
if s.session == nil || *s.session == nil {
@@ -32,6 +36,7 @@ func (s TrafficOpsSessionThreadsafe) CRConfigRaw(cdn string) ([]byte, error) {
return b, e
}
+// TrafficMonitorConfigMap returns the Traffic Monitor config map from the Traffic Ops. This is safe for multiple goroutines.
func (s TrafficOpsSessionThreadsafe) TrafficMonitorConfigMap(cdn string) (*to.TrafficMonitorConfigMap, error) {
s.m.Lock()
if s.session == nil || *s.session == nil {
@@ -42,6 +47,7 @@ func (s TrafficOpsSessionThreadsafe) TrafficMonitorConfigMap(cdn string) (*to.Tr
return d, e
}
+// Set sets the internal Traffic Ops session. This is safe for multiple goroutines, being aware they will race.
func (s TrafficOpsSessionThreadsafe) Set(session *to.Session) {
s.m.Lock()
*s.session = session
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol/blob/be2bb6b7/traffic_monitor/experimental/traffic_monitor/version.go
----------------------------------------------------------------------
diff --git a/traffic_monitor/experimental/traffic_monitor/version.go b/traffic_monitor/experimental/traffic_monitor/version.go
index bc6309a..caafcbc 100644
--- a/traffic_monitor/experimental/traffic_monitor/version.go
+++ b/traffic_monitor/experimental/traffic_monitor/version.go
@@ -1,3 +1,4 @@
package main
+// Version is the current version of the app, in string form.
var Version = "2.2"