added agent load testing feature (#549)

* added agent load testing feature

* added nanpa changeset

* fix build errors

* fix(agentloadtestting): fixed false agentTrackSubscribed assignment

* feat(loadtesting): added alias for loadtesting commands

* feat(loadtesting): updated agents loadtesting readme

* Revert "feat(loadtesting): added alias for loadtesting commands"

This reverts commit cade835.

Author: s-hamdananwar

.nanpa/agent-load-testing.kdl

@@ -0,0 +1 @@
+minor type="added" "Added agent load testing feature"

README.md

@@ -333,6 +333,32 @@ You can customize various parameters of the test such as
 -   `--layout`: layout to simulate (speaker, 3x3, 4x4, or 5x5)
 -   `--simulate-speakers`: randomly rotate publishers to speak
 
+### Agent Load Testing
+
+The agent load testing utility allows you to dispatch a running agent to a number of rooms and simulate a user in each room that would echo whatever the agent says. 
+
+> **Note**: Before running the test, ensure that:
+> - Your agent is already running using `start` instead of `dev` with the specified `agent_name` configured
+> - The agent is configured to speak something first (e.g., a simple greeting)
+
+To start an agent load test:
+
+```shell
+lk agent-load-test \
+  --rooms 5 \
+  --agent-name test-agent \
+  --echo-speech-delay 10s \
+  --duration 5m
+```
+
+The above simulates 5 concurrent rooms, where each room has:
+- Your agent `test-agent` dispatched
+- An echo participant that receives and plays back the agent's audio
+- A 10-second delay in the echo response from the agent speech
+- The test runs for 5 minutes before automatically stopping
+
+Once the specified duration is over (or if the load test is manually stopped), the load test statistics will be displayed in the form of a table.
+
 <!--BEGIN_REPO_NAV-->
 <br/><table>
 <thead><tr><th colspan="2">LiveKit Ecosystem</th></tr></thead>

cmd/lk/agent_loadtest.go

@@ -0,0 +1,87 @@
+// Copyright 2021-2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/go-logr/logr"
+	"github.com/urfave/cli/v3"
+
+	"github.com/livekit/livekit-cli/v2/pkg/loadtester"
+	"github.com/livekit/protocol/logger"
+	lksdk "github.com/livekit/server-sdk-go/v2"
+)
+
+var AgentLoadTestCommands = []*cli.Command{
+	{
+		Name:   "agent-load-test",
+		Usage:  "Run load tests for a running agent",
+		Action: agentLoadTest,
+		Flags: []cli.Flag{
+			&cli.IntFlag{
+				Name:  "rooms",
+				Usage: "`NUMBER` of rooms to open",
+			},
+			&cli.StringFlag{
+				Name:  "agent-name",
+				Usage: "name of the running agent to dispatch to the rooom",
+			},
+			&cli.DurationFlag{
+				Name:  "echo-speech-delay",
+				Usage: "delay between when the echo track speaks and when the agent starts speaking (e.g. 5s, 1m)",
+				Value: 5 * time.Second,
+			},
+			&cli.DurationFlag{
+				Name:  "duration",
+				Usage: "`TIME` duration to run, 1m, 1h (by default will run until canceled)",
+				Value: 0,
+			},
+		},
+	},
+}
+
+func agentLoadTest(ctx context.Context, cmd *cli.Command) error {
+	pc, err := loadProjectDetails(cmd)
+	if err != nil {
+		return err
+	}
+
+	if !cmd.Bool("verbose") {
+		lksdk.SetLogger(logger.LogRLogger(logr.Discard()))
+	}
+	_ = raiseULimit()
+
+	params := loadtester.AgentLoadTestParams{
+		URL:             pc.URL,
+		APIKey:          pc.APIKey,
+		APISecret:       pc.APISecret,
+		Rooms:           int(cmd.Int("rooms")),
+		AgentName:       cmd.String("agent-name"),
+		EchoSpeechDelay: cmd.Duration("echo-speech-delay"),
+		Duration:        cmd.Duration("duration"),
+	}
+
+	test := loadtester.NewAgentLoadTest(params)
+
+	err = test.Run(ctx, params)
+	if err != nil {
+		log.Printf("Agent load test failed: %v", err)
+		return err
+	}
+	return nil
+}

cmd/lk/main.go

@@ -70,6 +70,7 @@ func main() {
 	app.Commands = append(app.Commands, SIPCommands...)
 	app.Commands = append(app.Commands, ReplayCommands...)
 	app.Commands = append(app.Commands, LoadTestCommands...)
+	app.Commands = append(app.Commands, AgentLoadTestCommands...)
 
 	// Register cleanup hook for SIGINT, SIGTERM, SIGQUIT
 	ctx, stop := signal.NotifyContext(

pkg/loadtester/agentloadtest.go

@@ -0,0 +1,66 @@
+// Copyright 2021-2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package loadtester
+
+import (
+	"context"
+	"log"
+	"time"
+)
+
+type AgentLoadTestParams struct {
+	Rooms           int
+	AgentName       string
+	EchoSpeechDelay time.Duration
+	Duration        time.Duration
+	URL             string
+	APIKey          string
+	APISecret       string
+}
+
+type AgentLoadTest struct {
+	Params AgentLoadTestParams
+}
+
+func NewAgentLoadTest(params AgentLoadTestParams) *AgentLoadTest {
+	l := &AgentLoadTest{
+		Params: params,
+	}
+	return l
+}
+
+func (t *AgentLoadTest) Run(ctx context.Context, params AgentLoadTestParams) error {
+	log.Printf("Starting agent load test with %d rooms", params.Rooms)
+	agentLoadTester := NewAgentLoadTester(params)
+
+	duration := params.Duration
+	if duration == 0 {
+		// a really long time
+		duration = 1000 * time.Hour
+	}
+	timeoutCtx, cancel := context.WithTimeout(ctx, duration)
+	defer cancel()
+
+	err := agentLoadTester.Start(timeoutCtx)
+	if err != nil {
+		log.Printf("Failed to start agent load tester: %v", err)
+		return err
+	}
+
+	<-timeoutCtx.Done()
+	agentLoadTester.Stop()
+	log.Printf("Test completed or timed out")
+	return nil
+}