Merge pull request #5406 from ethereum-optimism/jg/metrics_docs

op-node/doc: Document op-batcher & op-proposer metrics

op-batcher/batcher/batch_submitter.go

@@ -12,6 +12,7 @@ import (
 	gethrpc "github.com/ethereum/go-ethereum/rpc"
 	"github.com/urfave/cli"
 
+	"github.com/ethereum-optimism/optimism/op-batcher/flags"
 	"github.com/ethereum-optimism/optimism/op-batcher/metrics"
 	"github.com/ethereum-optimism/optimism/op-batcher/rpc"
 	oplog "github.com/ethereum-optimism/optimism/op-service/log"
@@ -30,6 +31,9 @@ const (
 // of a closure allows the parameters bound to the top-level main package, e.g.
 // GitVersion, to be captured and used once the function is executed.
 func Main(version string, cliCtx *cli.Context) error {
+	if err := flags.CheckRequired(cliCtx); err != nil {
+		return err
+	}
 	cfg := NewConfig(cliCtx)
 	if err := cfg.Check(); err != nil {
 		return fmt.Errorf("invalid CLI flags: %w", err)

op-batcher/cmd/doc/cmd.go

@@ -0,0 +1,54 @@
+package doc
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/ethereum-optimism/optimism/op-batcher/metrics"
+	"github.com/olekukonko/tablewriter"
+	"github.com/urfave/cli"
+)
+
+var Subcommands = cli.Commands{
+	{
+		Name:  "metrics",
+		Usage: "Dumps a list of supported metrics to stdout",
+		Flags: []cli.Flag{
+			cli.StringFlag{
+				Name:  "format",
+				Value: "markdown",
+				Usage: "Output format (json|markdown)",
+			},
+		},
+		Action: func(ctx *cli.Context) error {
+			m := metrics.NewMetrics("default")
+			supportedMetrics := m.Document()
+			format := ctx.String("format")
+
+			if format != "markdown" && format != "json" {
+				return fmt.Errorf("invalid format: %s", format)
+			}
+
+			if format == "json" {
+				enc := json.NewEncoder(os.Stdout)
+				return enc.Encode(supportedMetrics)
+			}
+
+			table := tablewriter.NewWriter(os.Stdout)
+			table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false})
+			table.SetCenterSeparator("|")
+			table.SetAutoWrapText(false)
+			table.SetHeader([]string{"Metric", "Description", "Labels", "Type"})
+			var data [][]string
+			for _, metric := range supportedMetrics {
+				labels := strings.Join(metric.Labels, ",")
+				data = append(data, []string{metric.Name, metric.Help, labels, metric.Type})
+			}
+			table.AppendBulk(data)
+			table.Render()
+			return nil
+		},
+	},
+}

op-batcher/cmd/main.go

@@ -7,6 +7,7 @@ import (
 	"github.com/urfave/cli"
 
 	"github.com/ethereum-optimism/optimism/op-batcher/batcher"
+	"github.com/ethereum-optimism/optimism/op-batcher/cmd/doc"
 	"github.com/ethereum-optimism/optimism/op-batcher/flags"
 	oplog "github.com/ethereum-optimism/optimism/op-service/log"
 	"github.com/ethereum/go-ethereum/log"
@@ -26,10 +27,15 @@ func main() {
 	app.Version = fmt.Sprintf("%s-%s-%s", Version, GitCommit, GitDate)
 	app.Name = "op-batcher"
 	app.Usage = "Batch Submitter Service"
-	app.Description = "Service for generating and submitting L2 tx batches " +
-		"to L1"
-
+	app.Description = "Service for generating and submitting L2 tx batches to L1"
 	app.Action = curryMain(Version)
+	app.Commands = []cli.Command{
+		{
+			Name:        "doc",
+			Subcommands: doc.Subcommands,
+		},
+	}
+
 	err := app.Run(os.Args)
 	if err != nil {
 		log.Crit("Application failed", "message", err)

op-batcher/flags/flags.go

@@ -1,6 +1,8 @@
 package flags
 
 import (
+	"fmt"
+
 	"github.com/urfave/cli"
 
 	"github.com/ethereum-optimism/optimism/op-batcher/rpc"
@@ -17,37 +19,32 @@ const envVarPrefix = "OP_BATCHER"
 var (
 	// Required flags
 	L1EthRpcFlag = cli.StringFlag{
-		Name:     "l1-eth-rpc",
-		Usage:    "HTTP provider URL for L1",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "L1_ETH_RPC"),
+		Name:   "l1-eth-rpc",
+		Usage:  "HTTP provider URL for L1",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "L1_ETH_RPC"),
 	}
 	L2EthRpcFlag = cli.StringFlag{
-		Name:     "l2-eth-rpc",
-		Usage:    "HTTP provider URL for L2 execution engine",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "L2_ETH_RPC"),
+		Name:   "l2-eth-rpc",
+		Usage:  "HTTP provider URL for L2 execution engine",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "L2_ETH_RPC"),
 	}
 	RollupRpcFlag = cli.StringFlag{
-		Name:     "rollup-rpc",
-		Usage:    "HTTP provider URL for Rollup node",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "ROLLUP_RPC"),
+		Name:   "rollup-rpc",
+		Usage:  "HTTP provider URL for Rollup node",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "ROLLUP_RPC"),
 	}
 	SubSafetyMarginFlag = cli.Uint64Flag{
 		Name: "sub-safety-margin",
 		Usage: "The batcher tx submission safety margin (in #L1-blocks) to subtract " +
 			"from a channel's timeout and sequencing window, to guarantee safe inclusion " +
 			"of a channel on L1.",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "SUB_SAFETY_MARGIN"),
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "SUB_SAFETY_MARGIN"),
 	}
 	PollIntervalFlag = cli.DurationFlag{
 		Name: "poll-interval",
 		Usage: "Delay between querying L2 for more transactions and " +
 			"creating a new batch",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "POLL_INTERVAL"),
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "POLL_INTERVAL"),
 	}
 
 	// Optional flags
@@ -108,8 +105,7 @@ var optionalFlags = []cli.Flag{
 }
 
 func init() {
-	requiredFlags = append(requiredFlags, oprpc.CLIFlags(envVarPrefix)...)
-
+	optionalFlags = append(optionalFlags, oprpc.CLIFlags(envVarPrefix)...)
 	optionalFlags = append(optionalFlags, oplog.CLIFlags(envVarPrefix)...)
 	optionalFlags = append(optionalFlags, opmetrics.CLIFlags(envVarPrefix)...)
 	optionalFlags = append(optionalFlags, oppprof.CLIFlags(envVarPrefix)...)
@@ -121,3 +117,12 @@ func init() {
 
 // Flags contains the list of configuration options available to the binary.
 var Flags []cli.Flag
+
+func CheckRequired(ctx *cli.Context) error {
+	for _, f := range requiredFlags {
+		if !ctx.GlobalIsSet(f.GetName()) {
+			return fmt.Errorf("flag %s is required", f.GetName())
+		}
+	}
+	return nil
+}

op-node/flags/flags.go

@@ -256,28 +256,10 @@ func init() {
 }
 
 func CheckRequired(ctx *cli.Context) error {
-	l1NodeAddr := ctx.GlobalString(L1NodeAddr.Name)
-	if l1NodeAddr == "" {
-		return fmt.Errorf("flag %s is required", L1NodeAddr.Name)
-	}
-	l2EngineAddr := ctx.GlobalString(L2EngineAddr.Name)
-	if l2EngineAddr == "" {
-		return fmt.Errorf("flag %s is required", L2EngineAddr.Name)
-	}
-	rollupConfig := ctx.GlobalString(RollupConfig.Name)
-	network := ctx.GlobalString(Network.Name)
-	if rollupConfig == "" && network == "" {
-		return fmt.Errorf("flag %s or %s is required", RollupConfig.Name, Network.Name)
-	}
-	if rollupConfig != "" && network != "" {
-		return fmt.Errorf("cannot specify both %s and %s", RollupConfig.Name, Network.Name)
-	}
-	rpcListenAddr := ctx.GlobalString(RPCListenAddr.Name)
-	if rpcListenAddr == "" {
-		return fmt.Errorf("flag %s is required", RPCListenAddr.Name)
-	}
-	if !ctx.GlobalIsSet(RPCListenPort.Name) {
-		return fmt.Errorf("flag %s is required", RPCListenPort.Name)
+	for _, f := range requiredFlags {
+		if !ctx.GlobalIsSet(f.GetName()) {
+			return fmt.Errorf("flag %s is required", f.GetName())
+		}
 	}
 	return nil
 }

op-proposer/cmd/doc/cmd.go

@@ -0,0 +1,54 @@
+package doc
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/ethereum-optimism/optimism/op-proposer/metrics"
+	"github.com/olekukonko/tablewriter"
+	"github.com/urfave/cli"
+)
+
+var Subcommands = cli.Commands{
+	{
+		Name:  "metrics",
+		Usage: "Dumps a list of supported metrics to stdout",
+		Flags: []cli.Flag{
+			cli.StringFlag{
+				Name:  "format",
+				Value: "markdown",
+				Usage: "Output format (json|markdown)",
+			},
+		},
+		Action: func(ctx *cli.Context) error {
+			m := metrics.NewMetrics("default")
+			supportedMetrics := m.Document()
+			format := ctx.String("format")
+
+			if format != "markdown" && format != "json" {
+				return fmt.Errorf("invalid format: %s", format)
+			}
+
+			if format == "json" {
+				enc := json.NewEncoder(os.Stdout)
+				return enc.Encode(supportedMetrics)
+			}
+
+			table := tablewriter.NewWriter(os.Stdout)
+			table.SetBorders(tablewriter.Border{Left: true, Top: false, Right: true, Bottom: false})
+			table.SetCenterSeparator("|")
+			table.SetAutoWrapText(false)
+			table.SetHeader([]string{"Metric", "Description", "Labels", "Type"})
+			var data [][]string
+			for _, metric := range supportedMetrics {
+				labels := strings.Join(metric.Labels, ",")
+				data = append(data, []string{metric.Name, metric.Help, labels, metric.Type})
+			}
+			table.AppendBulk(data)
+			table.Render()
+			return nil
+		},
+	},
+}

op-proposer/cmd/main.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/urfave/cli"
 
+	"github.com/ethereum-optimism/optimism/op-proposer/cmd/doc"
 	"github.com/ethereum-optimism/optimism/op-proposer/flags"
 	"github.com/ethereum-optimism/optimism/op-proposer/proposer"
 	oplog "github.com/ethereum-optimism/optimism/op-service/log"
@@ -27,8 +28,14 @@ func main() {
 	app.Name = "op-proposer"
 	app.Usage = "L2Output Submitter"
 	app.Description = "Service for generating and submitting L2 Output checkpoints to the L2OutputOracle contract"
-
 	app.Action = curryMain(Version)
+	app.Commands = []cli.Command{
+		{
+			Name:        "doc",
+			Subcommands: doc.Subcommands,
+		},
+	}
+
 	err := app.Run(os.Args)
 	if err != nil {
 		log.Crit("Application failed", "message", err)

op-proposer/flags/flags.go

@@ -1,6 +1,8 @@
 package flags
 
 import (
+	"fmt"
+
 	"github.com/urfave/cli"
 
 	opservice "github.com/ethereum-optimism/optimism/op-service"
@@ -16,29 +18,25 @@ const envVarPrefix = "OP_PROPOSER"
 var (
 	// Required Flags
 	L1EthRpcFlag = cli.StringFlag{
-		Name:     "l1-eth-rpc",
-		Usage:    "HTTP provider URL for L1",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "L1_ETH_RPC"),
+		Name:   "l1-eth-rpc",
+		Usage:  "HTTP provider URL for L1",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "L1_ETH_RPC"),
 	}
 	RollupRpcFlag = cli.StringFlag{
-		Name:     "rollup-rpc",
-		Usage:    "HTTP provider URL for the rollup node",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "ROLLUP_RPC"),
+		Name:   "rollup-rpc",
+		Usage:  "HTTP provider URL for the rollup node",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "ROLLUP_RPC"),
 	}
 	L2OOAddressFlag = cli.StringFlag{
-		Name:     "l2oo-address",
-		Usage:    "Address of the L2OutputOracle contract",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "L2OO_ADDRESS"),
+		Name:   "l2oo-address",
+		Usage:  "Address of the L2OutputOracle contract",
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "L2OO_ADDRESS"),
 	}
 	PollIntervalFlag = cli.DurationFlag{
 		Name: "poll-interval",
 		Usage: "Delay between querying L2 for more transactions and " +
 			"creating a new batch",
-		Required: true,
-		EnvVar:   opservice.PrefixEnvVar(envVarPrefix, "POLL_INTERVAL"),
+		EnvVar: opservice.PrefixEnvVar(envVarPrefix, "POLL_INTERVAL"),
 	}
 	// Optional flags
 	AllowNonFinalizedFlag = cli.BoolFlag{
@@ -74,3 +72,12 @@ func init() {
 
 // Flags contains the list of configuration options available to the binary.
 var Flags []cli.Flag
+
+func CheckRequired(ctx *cli.Context) error {
+	for _, f := range requiredFlags {
+		if !ctx.GlobalIsSet(f.GetName()) {
+			return fmt.Errorf("flag %s is required", f.GetName())
+		}
+	}
+	return nil
+}

op-proposer/metrics/metrics.go

@@ -104,3 +104,7 @@ const (
 func (m *Metrics) RecordL2BlocksProposed(l2ref eth.L2BlockRef) {
 	m.RecordL2Ref(BlockProposed, l2ref)
 }
+
+func (m *Metrics) Document() []opmetrics.DocumentedMetric {
+	return m.factory.Document()
+}

op-service/txmgr/metrics/tx_metrics.go

@@ -85,15 +85,15 @@ func MakeTxMetrics(ns string, factory metrics.Factory) TxMetrics {
 		txPublishError: factory.NewCounterVec(prometheus.CounterOpts{
 			Namespace: ns,
 			Name:      "tx_publish_error_count",
-			Help:      "Count of publish errors. Labells are sanitized error strings",
+			Help:      "Count of publish errors. Labels are sanitized error strings",
 			Subsystem: "txmgr",
 		}, []string{"error"}),
 		confirmEvent: metrics.NewEventVec(factory, ns, "txmgr", "confirm", "tx confirm", []string{"status"}),
 		publishEvent: metrics.NewEvent(factory, ns, "txmgr", "publish", "tx publish"),
 		rpcError: factory.NewCounter(prometheus.CounterOpts{
 			Namespace: ns,
 			Name:      "rpc_error_count",
-			Help:      "Temporrary: Count of RPC errors (like timeouts) that have occurrred",
+			Help:      "Temporary: Count of RPC errors (like timeouts) that have occurred",
 			Subsystem: "txmgr",
 		}),
 	}