Some cleanups + playground readme

0x19 · 0x19 · commit ad2f76194390 · 2025-05-03T13:19:38.000+02:00
diff --git a/playground/README.md b/playground/README.md
@@ -1,8 +1,82 @@
-# Playground
+# FDB Playground
 
-This directory is used for testing and playing around with different things. Idea is to have a place where we can spawn
-as many as possible nodes we want and see them in grafana dashboard how they behave. Behaviour include:
+The playground provides a flexible environment for testing and benchmarking the FDB P2P network under various conditions. It allows you to spawn multiple nodes with different roles and configurations, run predefined strategies against them, and monitor their behavior through observability tools like Grafana and OpenTelemetry.
 
-- Network, latencies and availability
-- RPC
-- Raw TCP and Capn Proto
+## Features
+
+- Spawn multiple P2P nodes with customizable roles and configurations
+- Monitor network latencies, throughput, and node availability
+- Test RPC communications between nodes
+- Evaluate raw TCP performance and CapnProto serialization
+- Benchmark write operations with configurable concurrency and data sizes
+- Track per-node metrics with enhanced observability
+- Automatic clean shutdown when tests complete
+
+## Usage
+
+### Basic Command Structure
+
+```bash
+# General syntax
+fdb playground [options] <strategy> [strategy-specific-options]
+
+# Examples
+fdb playground --nodes 5 --base-port 9000 write --workers 20 --data-size 100 --total-ops 5000
+```
+
+### Global Options
+
+- `--nodes <number>`: Number of nodes to create (default: 3)
+- `--base-port <port>`: Starting port number for node communication (default: 8000)
+- `--strategy <name>`: Name of the strategy to run (can also be specified as a command)
+- `--log-level <level>`: Logging level (debug, info, warn, error)
+
+### Available Strategies
+
+#### Write Strategy
+
+The write strategy tests write operations to the P2P network with configurable parameters:
+
+```bash
+fdb playground write [options]
+```
+
+Options:
+- `--target-node <index>`: Index of the node to send writes to (default: 0)
+- `--workers <number>`: Number of concurrent workers (default: 10)
+- `--data-size <kb>`: Size of data to write in KB (default: 10)
+- `--ops-per-sec <number>`: Target operations per second (default: 100)
+- `--total-ops <number>`: Total number of operations (default: 1000)
+
+## Observability
+
+Each node in the playground is assigned a unique identifier (e.g., `playground_peer_0`) that is included in:
+
+1. All log entries
+2. Metrics reported to Prometheus
+3. Traces exported to OpenTelemetry
+
+This allows for detailed per-node analysis in Grafana dashboards and other observability tools.
+
+## Examples
+
+### Run a Write Test with 5 Nodes
+
+```bash
+# Create 5 nodes and run a write test with 20 workers, 100KB data size, and 5000 total operations
+fdb playground --nodes 5 write --workers 20 --data-size 100 --total-ops 5000
+```
+
+### Custom Port Configuration
+
+```bash
+# Start with base port 9000 instead of default 8000
+fdb playground --base-port 9000 write
+```
+
+### Detailed Logging
+
+```bash
+# Enable debug-level logging
+fdb playground --log-level debug write
+```
diff --git a/playground/entrypoint.go b/playground/entrypoint.go
@@ -136,7 +136,7 @@ func Run(cliCtx *cli.Context, cfg Config) error {
 		}
 
 		// Parse CLI arguments using the strategy's argument mappings
-		args := strategies.ParseCliArgs(cliCtx, strategyInfo)
+		args := strategies.ParseArgs(cliCtx, strategyInfo)
 
 		// Create a channel to signal when the strategy is done
 		strategyCh := make(chan error, 1)
diff --git a/playground/strategies/strategies.go b/playground/strategies/strategies.go
@@ -10,8 +10,8 @@ import (
 
 // ArgMapping defines how CLI flags map to strategy parameters
 type ArgMapping struct {
-	// CliFlag is the name of the flag in the CLI (e.g. "data-size")
-	CliFlag string
+	// Flag is the name of the flag in the CLI (e.g. "data-size")
+	Flag string
 
 	// ParamKey is the key in the args map passed to the strategy (e.g. "data_size_kb")
 	ParamKey string
@@ -65,8 +65,8 @@ type Strategy interface {
 	CompletionCh() <-chan struct{}
 }
 
-// ParseCliArgs converts CLI context args to strategy args based on the mappings
-func ParseCliArgs(cliCtx *cli.Context, info Info) map[string]any {
+// ParseArgs converts CLI context args to strategy args based on the mappings
+func ParseArgs(cliCtx *cli.Context, info Info) map[string]any {
 	args := make(map[string]any)
 
 	// Add default values from DefaultArgs
@@ -76,20 +76,20 @@ func ParseCliArgs(cliCtx *cli.Context, info Info) map[string]any {
 
 	// Parse args from CLI flags based on the mappings
 	for _, mapping := range info.ArgMappings {
-		if cliCtx.IsSet(mapping.CliFlag) {
+		if cliCtx.IsSet(mapping.Flag) {
 			// Get the value based on type inference
 			switch mapping.DefaultValue.(type) {
 			case int:
-				args[mapping.ParamKey] = cliCtx.Int(mapping.CliFlag)
+				args[mapping.ParamKey] = cliCtx.Int(mapping.Flag)
 			case string:
-				args[mapping.ParamKey] = cliCtx.String(mapping.CliFlag)
+				args[mapping.ParamKey] = cliCtx.String(mapping.Flag)
 			case bool:
-				args[mapping.ParamKey] = cliCtx.Bool(mapping.CliFlag)
+				args[mapping.ParamKey] = cliCtx.Bool(mapping.Flag)
 			case float64:
-				args[mapping.ParamKey] = cliCtx.Float64(mapping.CliFlag)
+				args[mapping.ParamKey] = cliCtx.Float64(mapping.Flag)
 			default:
 				// For other types, just use the string value
-				args[mapping.ParamKey] = cliCtx.String(mapping.CliFlag)
+				args[mapping.ParamKey] = cliCtx.String(mapping.Flag)
 			}
 		}
 	}
diff --git a/playground/strategies/write.go b/playground/strategies/write.go
@@ -269,35 +269,35 @@ func (s *WriteStrategy) Info() Info {
 		},
 		ArgMappings: []ArgMapping{
 			{
-				CliFlag:      "target-node",
+				Flag:         "target-node",
 				ParamKey:     "target_node",
 				Description:  "Index of the node to send writes to (default 0 = first node)",
 				DefaultValue: 0,
 				Required:     false,
 			},
 			{
-				CliFlag:      "workers",
+				Flag:         "workers",
 				ParamKey:     "workers",
 				Description:  "Number of concurrent workers for write operations (optimized with XOR key distribution)",
 				DefaultValue: 10,
 				Required:     false,
 			},
 			{
-				CliFlag:      "data-size",
+				Flag:         "data-size",
 				ParamKey:     "data_size_kb",
 				Description:  "Size of data to write in KB (uses optimized TCP streaming with 128KB buffer)",
 				DefaultValue: 10,
 				Required:     false,
 			},
 			{
-				CliFlag:      "ops-per-sec",
+				Flag:         "ops-per-sec",
 				ParamKey:     "ops_per_sec",
 				Description:  "Target operations per second across all workers",
 				DefaultValue: 100,
 				Required:     false,
 			},
 			{
-				CliFlag:      "total-ops",
+				Flag:         "total-ops",
 				ParamKey:     "total_ops",
 				Description:  "Total number of operations to perform",
 				DefaultValue: 1000,

Original file line number	Diff line number	Diff line change
`@@ -136,7 +136,7 @@ func Run(cliCtx *cli.Context, cfg Config) error {`
`136`	`136`	`}`
`137`	`137`
`138`	`138`	`// Parse CLI arguments using the strategy's argument mappings`
`139`		`- args := strategies.ParseCliArgs(cliCtx, strategyInfo)`
	`139`	`+ args := strategies.ParseArgs(cliCtx, strategyInfo)`
`140`	`140`
`141`	`141`	`// Create a channel to signal when the strategy is done`
`142`	`142`	`strategyCh := make(chan error, 1)`