Merge pull request #11 from samcm/chore/comments

chore: Add missing comments

cmd/root.go

@@ -48,20 +48,13 @@ func Execute() {
 }
 
 func init() {
-	// Here you will define your flags and configuration settings.
-	// Cobra supports persistent flags, which, if defined here,
-	// will be global for your application.
-
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.ethereum-metrics-exporter.yaml)")
-
 	rootCmd.PersistentFlags().IntVarP(&metricsPort, "metrics-port", "", 9090, "Port to serve Prometheus metrics on")
 	rootCmd.PersistentFlags().StringVarP(&executionUrl, "execution-url", "", "", "(optional) URL to the execution node")
 	rootCmd.PersistentFlags().StringVarP(&consensusUrl, "consensus-url", "", "", "(optional) URL to the consensus node")
 	rootCmd.PersistentFlags().StringSliceVarP(&monitoredDirectories, "monitored-directories", "", []string{}, "(optional) directories to monitor for disk usage")
 	rootCmd.PersistentFlags().StringSliceVarP(&executionModules, "execution-modules", "", []string{}, "(optional) execution modules that are enabled on the node")
 
-	// Cobra also supports local flags, which will only run
-	// when this action is called directly.
 	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
 }
 

pkg/exporter/consensus/consensus.go

@@ -10,11 +10,17 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Node represents a single consensus node in the ethereum network.
 type Node interface {
+	// Name returns the name of the node.
 	Name() string
+	// URL returns the url of the node.
 	URL() string
+	// Bootstrapped returns whether the node has been bootstrapped and is ready to be used.
 	Bootstrapped() bool
+	// Bootstrap attempts to bootstrap the node (i.e. configuring clients)
 	Bootstrap(ctx context.Context) error
+	// StartMetrics starts the metrics collection.
 	StartMetrics(ctx context.Context)
 }
 
@@ -27,7 +33,8 @@ type node struct {
 	metrics   Metrics
 }
 
-func NewConsensusNode(ctx context.Context, log logrus.FieldLogger, namespace string, name string, url string) (*node, error) {
+// NewConsensusNode returns a new Node instance.
+func NewConsensusNode(ctx context.Context, log logrus.FieldLogger, namespace string, name string, url string) (Node, error) {
 	node := &node{
 		name:      name,
 		url:       url,

pkg/exporter/consensus/jobs/forks.go

@@ -13,6 +13,7 @@ import (
 	eth2client "github.com/attestantio/go-eth2-client"
 )
 
+// Forks reports the state of any forks (previous, active or upcoming).
 type Forks struct {
 	MetricExporter
 	Epochs              prometheus.GaugeVec
@@ -27,6 +28,7 @@ const (
 	NameFork = "fork"
 )
 
+// NewForksJob returns a new Forks instance.
 func NewForksJob(client eth2client.Service, log logrus.FieldLogger, namespace string, constLabels map[string]string) Forks {
 	constLabels["module"] = NameFork
 	namespace = namespace + "_fork"

pkg/exporter/consensus/jobs/general.go

@@ -11,6 +11,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// General reports general information about the node.
 type General struct {
 	MetricExporter
 	client      eth2client.Service
@@ -26,6 +27,7 @@ const (
 	NameGeneral = "general"
 )
 
+// NewGeneral creates a new General instance.
 func NewGeneralJob(client eth2client.Service, log logrus.FieldLogger, namespace string, constLabels map[string]string) General {
 	constLabels["module"] = NameGeneral
 	return General{

pkg/exporter/consensus/jobs/job.go

@@ -1,5 +1,6 @@
 package jobs
 
+// MetricExporter defines a consensus metric job.
 type MetricExporter interface {
 	// Name returns the name of the job.
 	Name() string

pkg/exporter/consensus/jobs/spec.go

@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cast"
 )
 
+// Spec reports metrics about the configured consensus spec.
 type Spec struct {
 	MetricExporter
 	client                           eth2client.Service
@@ -47,6 +48,7 @@ const (
 	NameSpec = "spec"
 )
 
+// NewSpecJob returns a new Spec instance.
 func NewSpecJob(client eth2client.Service, log logrus.FieldLogger, namespace string, constLabels map[string]string) Spec {
 	constLabels["module"] = NameSpec
 	namespace = namespace + "_spec"

pkg/exporter/consensus/jobs/syncstatus.go

@@ -10,6 +10,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Sync reports metrics on the sync status of the node.
 type Sync struct {
 	MetricExporter
 	client               eth2client.Service
@@ -25,6 +26,7 @@ const (
 	NameSync = "sync"
 )
 
+// NewSyncJob returns a new Sync instance.
 func NewSyncJob(client eth2client.Service, log logrus.FieldLogger, namespace string, constLabels map[string]string) Sync {
 	constLabels["module"] = NameSync
 	namespace = namespace + "_sync"

pkg/exporter/consensus/metrics.go

@@ -9,7 +9,9 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Metrics defines a set of metrics for an ethereum consensus node.
 type Metrics interface {
+	// StartAsync starts the metrics exporter.
 	StartAsync(ctx context.Context)
 }
 
@@ -22,6 +24,7 @@ type metrics struct {
 	forkMetrics    jobs.Forks
 }
 
+// NewMetrics returns a new metrics object.
 func NewMetrics(client eth2client.Service, log logrus.FieldLogger, nodeName, namespace string) Metrics {
 	constLabels := make(prometheus.Labels)
 	constLabels["ethereum_role"] = "consensus"

pkg/exporter/disk/disk.go

@@ -8,8 +8,11 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// DiskUsage reports disk usage metrics
 type DiskUsage interface {
+	// StartAsync starts the disk usage metrics collection.
 	StartAsync(ctx context.Context)
+	// GetUsage returns the usage of the directories.
 	GetUsage(ctx context.Context, directories []string) ([]DiskUsed, error)
 }
 
@@ -19,6 +22,7 @@ type diskUsage struct {
 	directories []string
 }
 
+// NewDiskUsage returns a new DiskUsage instance.
 func NewDiskUsage(ctx context.Context, log logrus.FieldLogger, namespace string, directories []string) (DiskUsage, error) {
 	return &diskUsage{
 		log:         log,

pkg/exporter/disk/metrics.go

@@ -5,7 +5,9 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Metrics defines the interface for reporting disk usage metrics.
 type Metrics interface {
+	// ObserveDiskUsage reports the disk usage for the directory.
 	ObserveDiskUsage(disk DiskUsed)
 }
 
@@ -14,6 +16,7 @@ type metrics struct {
 	diskUsage *prometheus.GaugeVec
 }
 
+// NewMetrics returns a new Metrics instance.
 func NewMetrics(log logrus.FieldLogger, namespace string) Metrics {
 	constLabels := make(prometheus.Labels)
 

pkg/exporter/disk/usage.go

@@ -1,5 +1,6 @@
 package disk
 
+// DiskUsed contains usage information for a single directory.
 type DiskUsed struct {
 	Directory  string
 	UsageBytes int64

pkg/exporter/execution/api/api.go

@@ -16,10 +16,15 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// ExecutionClient is an interface for executing RPC calls to the Ethereum node.
 type ExecutionClient interface {
+	// AdminNodeInfo returns information about the node.
 	AdminNodeInfo(ctx context.Context) (*types.NodeInfo, error)
+	// AdminPeers returns information about the peers.
 	AdminPeers(ctx context.Context) ([]*p2p.PeerInfo, error)
+	// TXPoolStatus returns information about the transaction pool.
 	TXPoolStatus(ctx context.Context) (*types.TXPoolStatus, error)
+	// NetPeerCount returns the number of peers.
 	NetPeerCount(ctx context.Context) (int, error)
 }
 
@@ -29,6 +34,7 @@ type executionClient struct {
 	client http.Client
 }
 
+// NewExecutionClient creates a new ExecutionClient.
 func NewExecutionClient(ctx context.Context, log logrus.FieldLogger, url string) *executionClient {
 	client := http.Client{
 		Timeout: time.Second * 10,

pkg/exporter/execution/api/types/admin.go

@@ -8,6 +8,7 @@ import (
 	"github.com/ethereum/go-ethereum/common/hexutil"
 )
 
+// NodeInfo is the information about the node.
 type NodeInfo struct {
 	Enode      string `json:"enode"`
 	ID         string `json:"id"`
@@ -23,13 +24,16 @@ type NodeInfo struct {
 	} `json:"protocols"`
 }
 
+// EthProtocol is the information about the eth protocol.
 type EthProtocol struct {
 	Difficulty *big.Int    `json:"difficulty"`
 	Genesis    common.Hash `json:"genesis"`
 	Head       common.Hash `json:"head"`
 	NetworkID  int         `json:"networkID"`
 }
 
+// UnmarshalJSON implements the json.Unmarshaler interface, overriding to handle
+// clients returning difficulty as a number or string prefixed with 0x.
 func (e *EthProtocol) UnmarshalJSON(data []byte) error {
 	var v struct {
 		Difficulty *big.Int    `json:"difficulty"`
@@ -67,6 +71,7 @@ func (e *EthProtocol) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// Difficulty returns the difficulty.
 func (n *NodeInfo) Difficulty() *big.Int {
 	return n.Protocols.Eth.Difficulty
 }

pkg/exporter/execution/api/types/txpool.go

@@ -2,6 +2,7 @@ package types
 
 import "github.com/ethereum/go-ethereum/common/hexutil"
 
+// TXPoolStatus is the information about the transaction pool.
 type TXPoolStatus struct {
 	Pending hexutil.Uint64 `json:"pending"`
 	Queued  hexutil.Uint64 `json:"queued"`

pkg/exporter/execution/execution.go

@@ -9,11 +9,17 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Node represents an execution node.
 type Node interface {
+	// Name returns the name of the node.
 	Name() string
+	// URL returns the url of the node.
 	URL() string
+	// Bootstrapped returns whether the node has been bootstrapped and is ready to be used.
 	Bootstrapped() bool
+	// Bootstrap attempts to bootstrap the node (i.e. configuring clients)
 	Bootstrap(ctx context.Context) error
+	// StartMetrics starts the metrics collection.
 	StartMetrics(ctx context.Context)
 }
 
@@ -26,7 +32,8 @@ type node struct {
 	metrics     Metrics
 }
 
-func NewExecutionNode(ctx context.Context, log logrus.FieldLogger, namespace string, nodeName string, url string, enabledModules []string) (*node, error) {
+// NewExecutionNode returns a new execution node.
+func NewExecutionNode(ctx context.Context, log logrus.FieldLogger, namespace string, nodeName string, url string, enabledModules []string) (Node, error) {
 	internalApi := api.NewExecutionClient(ctx, log, url)
 	client, _ := ethclient.Dial(url)
 	metrics := NewMetrics(client, internalApi, log, nodeName, namespace, enabledModules)

pkg/exporter/execution/jobs/admin.go

@@ -13,6 +13,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Admin exposes metrics defined by the admin module.
 type Admin struct {
 	MetricExporter
 	client                   *ethclient.Client
@@ -37,6 +38,7 @@ func (t *Admin) RequiredModules() []string {
 	return []string{"admin"}
 }
 
+// NewAdmin returns a new Admin instance.
 func NewAdmin(client *ethclient.Client, internalApi api.ExecutionClient, log logrus.FieldLogger, namespace string, constLabels map[string]string) Admin {
 	namespace = namespace + "_admin"
 	constLabels["module"] = NameAdmin

pkg/exporter/execution/jobs/general.go

@@ -10,6 +10,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// GeneralMetrics exposes metrics that otherwise don't fit in to a specific module.
 type GeneralMetrics struct {
 	MetricExporter
 	client                *ethclient.Client
@@ -33,6 +34,7 @@ func (g *GeneralMetrics) RequiredModules() []string {
 	return []string{"eth", "net"}
 }
 
+// NewGeneralMetrics returns a new General metrics instance.
 func NewGeneralMetrics(client *ethclient.Client, internalApi api.ExecutionClient, log logrus.FieldLogger, namespace string, constLabels map[string]string) GeneralMetrics {
 	constLabels["module"] = NameGeneral
 	return GeneralMetrics{

pkg/exporter/execution/jobs/job.go

@@ -19,6 +19,7 @@ func contains(slice []string, item string) bool {
 	return ok
 }
 
+// ExporterCanRun returns true if the job can run with the enabled modules.
 func ExporterCanRun(enabledModules []string, requiredModules []string) bool {
 	for _, module := range requiredModules {
 		if !contains(enabledModules, module) {

pkg/exporter/execution/jobs/syncstatus.go

@@ -10,6 +10,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// SyncStatus exposes metrics about the sync status of the node.
 type SyncStatus struct {
 	MetricExporter
 	client        *ethclient.Client
@@ -49,6 +50,7 @@ func (s *syncingStatus) Percent() float64 {
 	return float64(s.CurrentBlock) / float64(s.HighestBlock) * 100
 }
 
+// NewSyncStatus returns a new SyncStatus instance.
 func NewSyncStatus(client *ethclient.Client, internalApi api.ExecutionClient, log logrus.FieldLogger, namespace string, constLabels map[string]string) SyncStatus {
 	constLabels["module"] = NameSyncStatus
 	namespace = namespace + "_sync"

pkg/exporter/execution/jobs/txpool.go

@@ -10,6 +10,7 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// TXPool collects metrics around the transaction pool.
 type TXPool struct {
 	MetricExporter
 	client       *ethclient.Client
@@ -30,6 +31,7 @@ func (t *TXPool) RequiredModules() []string {
 	return []string{"txpool"}
 }
 
+// NewTXPool creates a new TXPool instance.
 func NewTXPool(client *ethclient.Client, internalApi api.ExecutionClient, log logrus.FieldLogger, namespace string, constLabels map[string]string) TXPool {
 	constLabels["module"] = NameTxPool
 	namespace = namespace + "_txpool"

pkg/exporter/execution/metrics.go

@@ -10,7 +10,9 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Metrics exposes Execution layer metrics
 type Metrics interface {
+	// StartAsync starts all the metrics jobs
 	StartAsync(ctx context.Context)
 }
 
@@ -24,6 +26,7 @@ type metrics struct {
 	enabledJobs map[string]bool
 }
 
+// NewMetrics creates a new execution Metrics instance
 func NewMetrics(client *ethclient.Client, internalApi api.ExecutionClient, log logrus.FieldLogger, nodeName, namespace string, enabledModules []string) Metrics {
 	constLabels := make(prometheus.Labels)
 	constLabels["ethereum_role"] = "execution"

pkg/exporter/exporter.go

@@ -13,12 +13,17 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
+// Exporter defines the Ethereum Metrics Exporter interface
 type Exporter interface {
+	// Init initialises the exporter
 	Init(ctx context.Context) error
+	// Config returns the configuration of the exporter
 	Config(ctx context.Context) *Config
+	// Serve starts the metrics server
 	Serve(ctx context.Context, port int) error
 }
 
+// NewExporter returns a new Exporter instance
 func NewExporter(log logrus.FieldLogger, conf *Config) Exporter {
 	return &exporter{
 		log:    log.WithField("component", "exporter"),