feat: add browsers telemetry set, status subcommands and simplify start/stop

archandatta · archandatta · commit 9e4ef958b640 · 2026-05-27T15:37:32.000-03:00
diff --git a/README.md b/README.md
@@ -211,7 +211,7 @@ Commands with JSON output support:
   - `--start-url <url>` - Initial page to open on launch
   - `--pool-id <id>` - Acquire a browser from the specified pool (mutually exclusive with --pool-name; ignores other session flags)
   - `--pool-name <name>` - Acquire a browser from the pool name (mutually exclusive with --pool-id; ignores other session flags)
-  - `--telemetry` - Enable telemetry capture on the new session (see `kernel browsers telemetry stream`)
+  - `--telemetry` - Enable telemetry capture on the new session (`enabled: true`)
   - `--output json`, `-o json` - Output raw JSON object
   - _Note: When a pool is specified, omit other session configuration flags—pool settings determine profile, proxy, viewport, etc._
 - `kernel browsers delete <id>` - Delete a browser
@@ -283,15 +283,20 @@ Commands with JSON output support:
 
 ### Browser Telemetry
 
+- `kernel browsers telemetry start <id>` - Start telemetry capture (`enabled: true`)
+  - `-o, --output json` - Output raw API response
+- `kernel browsers telemetry stop <id>` - Stop telemetry capture (`enabled: false`)
+  - `-o, --output json` - Output raw API response
+- `kernel browsers telemetry set <id>` - Set per-category telemetry config
+  - `--categories <assignments>` - Comma-separated `name=on|off` pairs, e.g. `network=on,page=off` (console, interaction, network, page)
+  - `-o, --output json` - Output raw API response
+- `kernel browsers telemetry status <id>` - Show current telemetry configuration
+  - `-o, --output json` - Output raw JSON telemetry config
 - `kernel browsers telemetry stream <id>` - Stream live telemetry events
   - `--categories <list>` - Filter by category (console,network,page,interaction,monitor)
   - `--types <list>` - Filter by event type (e.g. network_response,console_error)
   - `--seq <n>` - Resume stream from sequence number (Last-Event-ID)
   - `-o, --output json` - Output newline-delimited JSON envelopes
-- `kernel browsers telemetry start <id>` - Start telemetry capture on a running session
-  - `-o, --output json` - Output raw API response
-- `kernel browsers telemetry stop <id>` - Stop telemetry capture on a running session
-  - `-o, --output json` - Output raw API response
 
 ### Browser Process Control
 
diff --git a/cmd/browsers.go b/cmd/browsers.go
@@ -193,8 +193,8 @@ type BrowsersCreateInput struct {
 	StartURL           string
 	Extensions         []string
 	Viewport           string
-	TelemetryEnabled   bool
-	Output             string
+	TelemetryEnabled bool
+	Output           string
 }
 
 type BrowsersDeleteInput struct {
@@ -234,6 +234,17 @@ type BrowsersTelemetryStopInput struct {
 	Output     string
 }
 
+type BrowsersTelemetrySetInput struct {
+	Identifier string
+	Categories string // e.g. "network=on,page=off"
+	Output     string
+}
+
+type BrowsersTelemetryStatusInput struct {
+	Identifier string
+	Output     string
+}
+
 type BrowsersTelemetryStreamInput struct {
 	Identifier string
 	Categories []string
@@ -715,6 +726,78 @@ func (b BrowsersCmd) TelemetryStop(ctx context.Context, in BrowsersTelemetryStop
 	return nil
 }
 
+func (b BrowsersCmd) TelemetrySet(ctx context.Context, in BrowsersTelemetrySetInput) error {
+	if in.Output != "" && in.Output != "json" {
+		return fmt.Errorf("unsupported --output value: use 'json'")
+	}
+	p := kernel.BrowserTelemetryCategoriesConfigParam{}
+	for _, part := range strings.Split(in.Categories, ",") {
+		kv := strings.SplitN(strings.TrimSpace(part), "=", 2)
+		if len(kv) != 2 {
+			return fmt.Errorf("invalid category assignment %q: expected name=on or name=off", part)
+		}
+		name, val := strings.TrimSpace(kv[0]), strings.TrimSpace(kv[1])
+		var enabled bool
+		switch val {
+		case "on":
+			enabled = true
+		case "off":
+			enabled = false
+		default:
+			return fmt.Errorf("invalid value %q for category %q: must be 'on' or 'off'", val, name)
+		}
+		switch name {
+		case "console":
+			p.Console = kernel.BrowserTelemetryCategoryConfigParam{Enabled: kernel.Opt(enabled)}
+		case "interaction":
+			p.Interaction = kernel.BrowserTelemetryCategoryConfigParam{Enabled: kernel.Opt(enabled)}
+		case "network":
+			p.Network = kernel.BrowserTelemetryCategoryConfigParam{Enabled: kernel.Opt(enabled)}
+		case "page":
+			p.Page = kernel.BrowserTelemetryCategoryConfigParam{Enabled: kernel.Opt(enabled)}
+		default:
+			return fmt.Errorf("unknown category %q: must be one of console, interaction, network, page", name)
+		}
+	}
+	res, err := b.browsers.Update(ctx, in.Identifier, kernel.BrowserUpdateParams{
+		Telemetry: kernel.BrowserTelemetryRequestConfigParam{Browser: p},
+	})
+	if err != nil {
+		return util.CleanedUpSdkError{Err: err}
+	}
+	if in.Output == "json" {
+		return util.PrintPrettyJSON(res)
+	}
+	pterm.Success.Printf("Updated telemetry categories for browser %s\n", in.Identifier)
+	return nil
+}
+
+func (b BrowsersCmd) TelemetryStatus(ctx context.Context, in BrowsersTelemetryStatusInput) error {
+	if in.Output != "" && in.Output != "json" {
+		return fmt.Errorf("unsupported --output value: use 'json'")
+	}
+	browser, err := b.browsers.Get(ctx, in.Identifier, kernel.BrowserGetParams{})
+	if err != nil {
+		return util.CleanedUpSdkError{Err: err}
+	}
+	if in.Output == "json" {
+		return util.PrintPrettyJSON(browser.Telemetry)
+	}
+	cfg := browser.Telemetry.Browser
+	pterm.Printf("console:     %s\n", onOff(cfg.Console.Enabled))
+	pterm.Printf("interaction: %s\n", onOff(cfg.Interaction.Enabled))
+	pterm.Printf("network:     %s\n", onOff(cfg.Network.Enabled))
+	pterm.Printf("page:        %s\n", onOff(cfg.Page.Enabled))
+	return nil
+}
+
+func onOff(v bool) string {
+	if v {
+		return "on"
+	}
+	return "off"
+}
+
 // eventCategory derives the category prefix from a telemetry event type string.
 // e.g. "network_response" -> "network", "monitor_screenshot" -> "monitor".
 func eventCategory(eventType string) string {
@@ -2400,11 +2483,17 @@ func init() {
 	telemetryStream.Flags().StringSlice("types", []string{}, "Filter by event type (e.g. network_response,console_error)")
 	telemetryStream.Flags().Int64("seq", 0, "Resume stream from sequence number (Last-Event-ID)")
 	telemetryStream.Flags().StringP("output", "o", "", "Output format: json for newline-delimited JSON envelopes")
-	telemetryStart := &cobra.Command{Use: "start <id>", Short: "Start telemetry capture", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStart}
+	telemetryStart := &cobra.Command{Use: "start <id>", Short: "Start telemetry capture (enabled: true)", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStart}
 	telemetryStart.Flags().StringP("output", "o", "", "Output format: json for raw API response")
-	telemetryStop := &cobra.Command{Use: "stop <id>", Short: "Stop telemetry capture", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStop}
+	telemetryStop := &cobra.Command{Use: "stop <id>", Short: "Stop telemetry capture (enabled: false)", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStop}
 	telemetryStop.Flags().StringP("output", "o", "", "Output format: json for raw API response")
-	telemetryRoot.AddCommand(telemetryStream, telemetryStart, telemetryStop)
+	telemetrySet := &cobra.Command{Use: "set <id>", Short: "Set per-category telemetry config", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetrySet}
+	telemetrySet.Flags().String("categories", "", "Per-category assignments, e.g. network=on,page=off (console, interaction, network, page)")
+	_ = telemetrySet.MarkFlagRequired("categories")
+	telemetrySet.Flags().StringP("output", "o", "", "Output format: json for raw API response")
+	telemetryStatus := &cobra.Command{Use: "status <id>", Short: "Show current telemetry configuration", Args: cobra.ExactArgs(1), RunE: runBrowsersTelemetryStatus}
+	telemetryStatus.Flags().StringP("output", "o", "", "Output format: json for raw API response")
+	telemetryRoot.AddCommand(telemetryStream, telemetryStart, telemetryStop, telemetrySet, telemetryStatus)
 	browsersCmd.AddCommand(telemetryRoot)
 
 	// process
@@ -2636,7 +2725,7 @@ func init() {
 	browsersCreateCmd.Flags().Bool("viewport-interactive", false, "Interactively select viewport size from list")
 	browsersCreateCmd.Flags().String("pool-id", "", "Browser pool ID to acquire from (mutually exclusive with --pool-name)")
 	browsersCreateCmd.Flags().String("pool-name", "", "Browser pool name to acquire from (mutually exclusive with --pool-id)")
-	browsersCreateCmd.Flags().Bool("telemetry", false, "Enable telemetry capture on the new session")
+	browsersCreateCmd.Flags().Bool("telemetry", false, "Enable telemetry capture on the new session (enabled: true)")
 
 	// curl
 	curlCmd := &cobra.Command{
@@ -2816,8 +2905,8 @@ func runBrowsersCreate(cmd *cobra.Command, args []string) error {
 		StartURL:           startURL,
 		Extensions:         extensions,
 		Viewport:           viewport,
-		TelemetryEnabled:   telemetry,
-		Output:             output,
+		TelemetryEnabled: telemetry,
+		Output:           output,
 	}
 
 	svc := client.Browsers
@@ -2957,6 +3046,23 @@ func runBrowsersTelemetryStop(cmd *cobra.Command, args []string) error {
 	return b.TelemetryStop(cmd.Context(), BrowsersTelemetryStopInput{Identifier: args[0], Output: out})
 }
 
+func runBrowsersTelemetrySet(cmd *cobra.Command, args []string) error {
+	client := getKernelClient(cmd)
+	svc := client.Browsers
+	out, _ := cmd.Flags().GetString("output")
+	categories, _ := cmd.Flags().GetString("categories")
+	b := BrowsersCmd{browsers: &svc}
+	return b.TelemetrySet(cmd.Context(), BrowsersTelemetrySetInput{Identifier: args[0], Categories: categories, Output: out})
+}
+
+func runBrowsersTelemetryStatus(cmd *cobra.Command, args []string) error {
+	client := getKernelClient(cmd)
+	svc := client.Browsers
+	out, _ := cmd.Flags().GetString("output")
+	b := BrowsersCmd{browsers: &svc}
+	return b.TelemetryStatus(cmd.Context(), BrowsersTelemetryStatusInput{Identifier: args[0], Output: out})
+}
+
 func runBrowsersTelemetryStream(cmd *cobra.Command, args []string) error {
 	client := getKernelClient(cmd)
 	svc := client.Browsers
diff --git a/cmd/browsers_test.go b/cmd/browsers_test.go
@@ -1802,6 +1802,46 @@ func TestBrowsersTelemetryStop_SendsDisablePayload(t *testing.T) {
 	assert.Contains(t, outBuf.String(), "Stopped telemetry for browser session123")
 }
 
+func TestBrowsersTelemetrySet_PartialCategories(t *testing.T) {
+	setupStdoutCapture(t)
+	var captured kernel.BrowserUpdateParams
+	fake := &FakeBrowsersService{UpdateFunc: func(ctx context.Context, id string, body kernel.BrowserUpdateParams, opts ...option.RequestOption) (*kernel.BrowserUpdateResponse, error) {
+		captured = body
+		return &kernel.BrowserUpdateResponse{SessionID: id}, nil
+	}}
+	b := BrowsersCmd{browsers: fake}
+
+	err := b.TelemetrySet(context.Background(), BrowsersTelemetrySetInput{Identifier: "session123", Categories: "network=on,page=off"})
+
+	assert.NoError(t, err)
+	assert.False(t, captured.Telemetry.Enabled.Valid())
+	assert.True(t, captured.Telemetry.Browser.Network.Enabled.Valid())
+	assert.True(t, captured.Telemetry.Browser.Network.Enabled.Value)
+	assert.True(t, captured.Telemetry.Browser.Page.Enabled.Valid())
+	assert.False(t, captured.Telemetry.Browser.Page.Enabled.Value)
+	// Unspecified categories omitted — server retains their state
+	assert.False(t, captured.Telemetry.Browser.Console.Enabled.Valid())
+	assert.False(t, captured.Telemetry.Browser.Interaction.Enabled.Valid())
+}
+
+func TestBrowsersTelemetrySet_InvalidCategory(t *testing.T) {
+	b := BrowsersCmd{browsers: &FakeBrowsersService{}}
+
+	err := b.TelemetrySet(context.Background(), BrowsersTelemetrySetInput{Identifier: "session123", Categories: "foo=on"})
+
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "unknown category")
+}
+
+func TestBrowsersTelemetrySet_InvalidValue(t *testing.T) {
+	b := BrowsersCmd{browsers: &FakeBrowsersService{}}
+
+	err := b.TelemetrySet(context.Background(), BrowsersTelemetrySetInput{Identifier: "session123", Categories: "network=yes"})
+
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "must be 'on' or 'off'")
+}
+
 func TestBrowsersTelemetryStop_UnsupportedOutputErrors(t *testing.T) {
 	fake := &FakeBrowsersService{}
 	b := BrowsersCmd{browsers: fake}
@@ -1812,6 +1852,33 @@ func TestBrowsersTelemetryStop_UnsupportedOutputErrors(t *testing.T) {
 	assert.Contains(t, err.Error(), "unsupported --output value")
 }
 
+func TestBrowsersTelemetryStatus_PrintsCategories(t *testing.T) {
+	setupStdoutCapture(t)
+	fake := &FakeBrowsersService{GetFunc: func(ctx context.Context, id string, query kernel.BrowserGetParams, opts ...option.RequestOption) (*kernel.BrowserGetResponse, error) {
+		return &kernel.BrowserGetResponse{
+			SessionID: id,
+			Telemetry: kernel.BrowserTelemetryConfig{
+				Browser: kernel.BrowserTelemetryCategoriesConfig{
+					Console:     kernel.BrowserTelemetryCategoryConfig{Enabled: true},
+					Interaction: kernel.BrowserTelemetryCategoryConfig{Enabled: false},
+					Network:     kernel.BrowserTelemetryCategoryConfig{Enabled: true},
+					Page:        kernel.BrowserTelemetryCategoryConfig{Enabled: false},
+				},
+			},
+		}, nil
+	}}
+	b := BrowsersCmd{browsers: fake}
+
+	err := b.TelemetryStatus(context.Background(), BrowsersTelemetryStatusInput{Identifier: "session123"})
+
+	assert.NoError(t, err)
+	out := outBuf.String()
+	assert.Contains(t, out, "console:     on")
+	assert.Contains(t, out, "interaction: off")
+	assert.Contains(t, out, "network:     on")
+	assert.Contains(t, out, "page:        off")
+}
+
 func TestEventCategory(t *testing.T) {
 	cases := map[string]string{
 		"network_response":   "network",
