Logging

Configure logging through a single logging option on Stagehand.create(): a level, an output format, and a callback that receives each record. Use the language selector to see the exact shape your SDK accepts.

Quick start

Choose your logging setup based on your environment:

TypeScript
Python
Go

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

// Development: full debug output, human-readable
const development = { level: "debug", format: "pretty" } as const;

// Production: standard logging, machine-readable, forwarded to your platform
const production = {
  level: "info",
  format: "json",
  onLog: yourProductionLogger, // Send to Sentry, DataDog, or similar
} as const;

// Testing: warnings and errors only, no console noise
const testing = { level: "warn", onLog: yourTestLogger } as const;

// Create one instance with the configuration for this environment
const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: development,
  // restOfYourConfiguration...
});

from stagehand import Stagehand, local_browser

# Development: full debug output, human-readable
development = {"level": "debug", "format": "pretty"}

# Production: standard logging, machine-readable, forwarded to your platform
production = {
    "level": "info",
    "format": "json",
    "on_log": your_production_logger,  # Send to Sentry, DataDog, or similar
}

# Testing: warnings and errors only, no console noise
testing = {"level": "warn", "on_log": your_test_logger}

# Create one instance with the configuration for this environment
browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging=development,
    # rest_of_your_configuration...
)

// Development: full debug output, human-readable
development := &stagehand.StagehandClientLoggingConfig{
	Level:  stagehand.StagehandClientLogLevelDebug,
	Format: stagehand.StagehandClientLogFormatPretty,
}

// Production: standard logging, machine-readable, forwarded to your platform
production := &stagehand.StagehandClientLoggingConfig{
	Level:  stagehand.StagehandClientLogLevelInfo,
	Format: stagehand.StagehandClientLogFormatJSON,
	OnLog:  yourProductionLogger, // Send to Sentry, DataDog, or similar
}

// Testing: warnings and errors only, no console noise
testing := &stagehand.StagehandClientLoggingConfig{
	Level: stagehand.StagehandClientLogLevelWarn,
	OnLog: yourTestLogger,
}

// Pick the configuration that matches the environment you are running in
logging := development
switch os.Getenv("APP_ENV") {
case "production":
	logging = production
case "test":
	logging = testing
}

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, browser.Close(ctx)) }()

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: logging,
	// restOfYourConfiguration...
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Operational logging

Real-time event logging during automation execution.

Verbosity level

Control how much detail you see in logs. The level is always applied at the source, so the Stagehand runtime never generates or sends a record below your threshold. Every SDK sets that threshold the same way, and the default is info.

Level: debug
Level: info (default)
Level: error or off

Use for: Development, debugging specific issues

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser,
  logging: { level: "debug" }, // Maximum detail
  // restOfYourConfiguration...
});

stagehand = await Stagehand.create(
    browser=browser,
    logging={"level": "debug"},  # Maximum detail
    # rest_of_your_configuration...
)

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level: stagehand.StagehandClientLogLevelDebug, // Maximum detail
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Example output

[stagehand] DEBUG Capturing DOM snapshot {"pageId":"page-1"}
[stagehand] DEBUG DOM contains 847 elements {"count":847}
[stagehand] DEBUG LLM inference started {"category":"llm"}
[stagehand] DEBUG LLM response {"selector":"#btn-submit","method":"click"}
[stagehand] INFO act completed successfully {"category":"action"}

Use for: Standard operations, staging, production

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser,
  logging: { level: "info" }, // Default level
  // restOfYourConfiguration...
});

stagehand = await Stagehand.create(
    browser=browser,
    logging={"level": "info"},  # Default level
    # rest_of_your_configuration...
)

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level: stagehand.StagehandClientLogLevelInfo, // Default level
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Example output

[stagehand] INFO act started {"category":"action"}
[stagehand] INFO act completed successfully {"category":"action"}
[stagehand] INFO extract started {"category":"extraction"}
[stagehand] INFO extract completed {"category":"extraction"}

Use for: Production with external monitoring, minimal noise, or handling secrets

TypeScript
Python
Go

const errorsOnly = { level: "error" } as const; // Errors only
const silent = { level: "off" } as const; // Nothing at all

const stagehand = await Stagehand.create({
  browser,
  logging: errorsOnly,
  // restOfYourConfiguration...
});

errors_only = {"level": "error"}  # Errors only
silent = {"level": "off"}  # Nothing at all

stagehand = await Stagehand.create(
    browser=browser,
    logging=errors_only,
    # rest_of_your_configuration...
)

// Errors only
errorsOnly := &stagehand.StagehandClientLoggingConfig{
	Level: stagehand.StagehandClientLogLevelError,
}

// Nothing at all
silent := &stagehand.StagehandClientLoggingConfig{
	Level: stagehand.StagehandClientLogLevelOff,
}

// Pick the configuration that matches how much output you want
logging := errorsOnly
if os.Getenv("STAGEHAND_SILENT") == "1" {
	logging = silent
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: logging,
	// restOfYourConfiguration...
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

Example output

[stagehand] ERROR act failed: element not found {"category":"action"}
[stagehand] ERROR navigation timeout exceeded {"category":"navigation"}

Turning logging off suppresses the record callback as well as console output. Do this when handling passwords or other secrets.

Log destinations

Send logs to your console or through your own callback. The record callback drives every destination, so anything your own code can write to is a valid sink. To forward records to an observability platform, see External logging platforms.

Pretty (default)
JSON
Custom logger

Human-readable, single-line console output written to standard error.When to use: Development and interactive debugging

TypeScript
Python
Go

// Enabled by default: level "info", format "pretty"
const stagehand = await Stagehand.create({
  browser,
  logging: { level: "info", format: "pretty" },
  // restOfYourConfiguration...
});

# Enabled by default: level "info", format "pretty"
stagehand = await Stagehand.create(
    browser=browser,
    logging={"level": "info", "format": "pretty"},
    # rest_of_your_configuration...
)

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelInfo,
		Format: stagehand.StagehandClientLogFormatPretty,
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Output shape

Each line is [stagehand] LEVEL message {json data}, with the data object omitted when empty. Stagehand writes it to standard error so it never mixes with your program’s own standard output.

One JSON object per line, ready for log shippers and structured search.When to use: Containers, CI, or anywhere a collector tails standard error

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser,
  logging: { level: "info", format: "json" },
  // restOfYourConfiguration...
});

stagehand = await Stagehand.create(
    browser=browser,
    logging={"level": "info", "format": "json"},
    # rest_of_your_configuration...
)

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelInfo,
		Format: stagehand.StagehandClientLogFormatJSON,
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Output shape

{"level":"info","message":"act completed successfully","data":{"category":"action"}}

Your own callback receives every log record that passes the level filter, alongside the console output.When to use: Development, debugging, or when you don’t need querying capabilities.

Create a simple logger

TypeScript
Python
Go

// Simple logger without parsing (for basic console output)
// The callback receives a `StagehandLog`; see the reference below for the shape.
const simpleLogger = (log: {
  level: "debug" | "info" | "warn" | "error";
  message: string;
  data: Record<string, unknown>;
}) => {
  console.log(`[${log.level}] ${log.message}`);

  // Optional: log raw structured data
  if (Object.keys(log.data).length > 0) {
    console.log("  Context:", log.data);
  }
};

# Simple logger without parsing (for basic console output)
def simple_logger(log) -> None:
    print(f"[{log.level.value}] {log.message}")

    # Optional: log raw structured data
    data = log.data.model_dump(mode="json")
    if data:
        print("  Context:", data)

// Simple logger without parsing (for basic console output)
func simpleLogger(entry stagehand.StagehandLog) {
	fmt.Printf("[%s] %s\n", entry.Level, entry.Message)

	// Optional: log raw structured data
	if len(entry.Data) > 0 {
		fmt.Println("  Context:", entry.Data)
	}
}

Pass the logger in your Stagehand instance

Then pass the logger in your Stagehand instance:

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: {
    level: "info",
    onLog: simpleLogger,
  },
  // restOfYourConfiguration...
});

browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging={"level": "info", "on_log": simple_logger},
    # rest_of_your_configuration...
)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		OnLog: simpleLogger,
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

The callback receives every record that passes the level gate, so do any finer filtering inside it. It runs in addition to the console output rather than instead of it: the level gates both and off silences both. Keep the level at the lowest severity you want to receive, and redirect standard error if the console itself needs to stay quiet.

External logging platforms

The same log callback, pointed at an observability platform. When to use: Production with Sentry, DataDog, CloudWatch, or a custom observability platform for centralized monitoring and error alerting.

Sentry

Create a production logger

TypeScript
Python
Go

import * as Sentry from "@sentry/node";

const productionLogger = (log: {
  level: "debug" | "info" | "warn" | "error";
  message: string;
  data: Record<string, unknown>;
}) => {
  // Send errors to Sentry
  if (log.level === "error") {
    Sentry.captureMessage(log.message, {
      level: "error",
      extra: log.data,
    });
  }
};

import sentry_sdk

def production_logger(log) -> None:
    # Send errors to Sentry
    if log.level.value == "error":
        sentry_sdk.capture_message(
            log.message,
            level="error",
            extras=log.data.model_dump(mode="json"),
        )

func productionLogger(entry stagehand.StagehandLog) {
	// Send errors to Sentry
	if entry.Level != stagehand.StagehandLogLevelError {
		return
	}
	sentry.WithScope(func(scope *sentry.Scope) {
		// Data values are json.RawMessage. Pass them through so Sentry keeps each
		// field's JSON type instead of recording it as quoted text.
		for key, value := range entry.Data {
			scope.SetExtra(key, value)
		}
		scope.SetLevel(sentry.LevelError)
		sentry.CaptureMessage(entry.Message)
	})
}

Pass the logger in your Stagehand instance

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: {
    level: "info",
    format: "json",
    onLog: productionLogger,
  },
  // restOfYourConfiguration...
});

browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging={
        "level": "info",
        "format": "json",
        "on_log": production_logger,
    },
    # rest_of_your_configuration...
)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelInfo,
		Format: stagehand.StagehandClientLogFormatJSON,
		OnLog:  productionLogger,
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

DataDog

Create a production logger

TypeScript
Python
Go

import { datadogLogs } from "@datadog/browser-logs";

const productionLogger = (log: {
  level: "debug" | "info" | "warn" | "error";
  message: string;
  data: Record<string, unknown>;
}) => {
  // Send all logs to DataDog
  datadogLogs.logger.log(log.message, {
    status: log.level === "error" ? "error" : "info",
    service: "stagehand-automation",
    ...log.data,
  });
};

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.logs_api import LogsApi

logs_api = LogsApi(ApiClient(Configuration()))

def production_logger(log) -> None:
    # Send all logs to DataDog
    logs_api.submit_log(body=[{
        "message": log.message,
        "status": "error" if log.level.value == "error" else "info",
        "service": "stagehand-automation",
        **log.data.model_dump(mode="json"),
    }])

func productionLogger(entry stagehand.StagehandLog) {
	// Send all logs to DataDog
	status := "info"
	if entry.Level == stagehand.StagehandLogLevelError {
		status = "error"
	}
	payload := map[string]any{
		"message": entry.Message,
		"status":  status,
		"service": "stagehand-automation",
	}
	// Data values are json.RawMessage. Keep them raw so DataDog indexes numbers
	// as numbers and strings as strings.
	for key, value := range entry.Data {
		payload[key] = value
	}
	_ = submitDataDogLog(payload)
}

Pass the logger in your Stagehand instance

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: {
    level: "info",
    format: "json",
    onLog: productionLogger,
  },
  // restOfYourConfiguration...
});

browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging={
        "level": "info",
        "format": "json",
        "on_log": production_logger,
    },
    # rest_of_your_configuration...
)

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelInfo,
		Format: stagehand.StagehandClientLogFormatJSON,
		OnLog:  productionLogger,
	},
	// restOfYourConfiguration...
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Failures inside your callback are caught and reported on standard error, so a failing logger will not take down your automation. That covers exceptions and rejected promises in TypeScript and Python, and a panic in Go.

File-based session logging

Route the log callback to a file to get a durable, per-session record of every Stagehand operation: act, observe, extract, LLM inference, and browser events.

Setup

Pick a directory for your session logs and open a file per run:

TypeScript
Python
Go

import { createWriteStream } from "node:fs";
import { mkdirSync } from "node:fs";

mkdirSync("./stagehand-logs", { recursive: true });
const sessionId = new Date().toISOString().replace(/[:.]/g, "-");
const logFile = createWriteStream(`./stagehand-logs/${sessionId}.jsonl`, { flags: "a" });

from datetime import datetime, timezone
from pathlib import Path

Path("./stagehand-logs").mkdir(parents=True, exist_ok=True)
session_id = datetime.now(timezone.utc).isoformat().replace(":", "-").replace(".", "-")
log_file = open(f"./stagehand-logs/{session_id}.jsonl", "a", encoding="utf-8")

if err := os.MkdirAll("./stagehand-logs", 0o755); err != nil {
	return err
}
startedAt := time.Now().UTC()
sessionID := strings.NewReplacer(":", "-", ".", "-").Replace(startedAt.Format(time.RFC3339Nano))
logFile, err := os.OpenFile(
	fmt.Sprintf("./stagehand-logs/%s.jsonl", sessionID),
	os.O_APPEND|os.O_CREATE|os.O_WRONLY,
	0o600,
)
if err != nil {
	return err
}
fmt.Fprintf(os.Stderr, "writing Stagehand logs to %s\n", logFile.Name())

Usage

Write each record as one JSON line, then run your Stagehand script as normal:

TypeScript
Python
Go

import { finished } from "node:stream/promises";
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";

const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: {
    level: "debug",
    format: "pretty",
    onLog(log) {
      logFile.write(`${JSON.stringify(log)}\n`);
    },
  },
});

try {
  // ... your automation
} finally {
  await stagehand.close();
  logFile.end();
  await finished(logFile);
}

from stagehand import Stagehand, local_browser

browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging={
        "level": "debug",
        "format": "pretty",
        "on_log": lambda log: print(log.model_dump_json(), file=log_file),
    },
)

try:
    ...  # your automation
finally:
    await stagehand.close()
    log_file.close()

defer func() { err = errors.Join(err, logFile.Close()) }()

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelDebug,
		Format: stagehand.StagehandClientLogFormatPretty,
		OnLog: func(log stagehand.StagehandLog) {
			_ = json.NewEncoder(logFile).Encode(log)
		},
	},
})
if err != nil {
	return err
}
defer func() { err = errors.Join(err, client.Close(ctx)) }()

// ... your automation

Viewing logs

Real-time monitoring
Chronological review
Historical sessions

Follow all logs as they happen:

tail -f ./stagehand-logs/*.jsonl

Or filter by category as they stream:

# LLM requests and responses only
tail -f ./stagehand-logs/*.jsonl | jq 'select(.data.category == "llm")'

# Action events only
tail -f ./stagehand-logs/*.jsonl | jq 'select(.data.category == "action")'

View unified output across every session file:

cat ./stagehand-logs/*.jsonl | jq -r '"\(.level)\t\(.message)"'

Browse previous session logs:

ls ./stagehand-logs/
# Output: 2026-01-06T14-30-45-000Z.jsonl  2026-01-06T15-45-12-000Z.jsonl

jq -r 'select(.level == "error")' ./stagehand-logs/2026-01-06T14-30-45-000Z.jsonl

Log files

Because you own the sink, you decide how records are split. A common layout is one file per concern, keyed off the log category:

File	Contents
`llm_events.jsonl`	LLM requests and responses for act, extract, and observe operations
`browser_events.jsonl`	Navigation, snapshot, and page lifecycle events
`stagehand.jsonl`	Every record, unfiltered

This is especially useful for debugging long workflows where you need to trace the full sequence of LLM decisions and browser actions after the fact.

LLM inference debugging

Development only - Produces large volumes of output and contains page content. Do not use in production.

Run at the debug level to see the complete inference path: the snapshot that was captured, the prompt category, the model’s chosen element, and the token counts for each call.

TypeScript
Python
Go

const stagehand = await Stagehand.create({
  browser: await localBrowser.launch(),
  logging: {
    level: "debug",
    format: "json",
    onLog(log) {
      // Persist only the LLM records for offline analysis
      if (log.data.category === "llm") {
        inferenceFile.write(`${JSON.stringify(log)}\n`);
      }
    },
  },
});

def capture_inference(log) -> None:
    # Persist only the LLM records for offline analysis
    data = log.data.model_dump(mode="json")
    if data.get("category") == "llm":
        print(log.model_dump_json(), file=inference_file)

browser = await local_browser.launch()

stagehand = await Stagehand.create(
    browser=browser,
    logging={
        "level": "debug",
        "format": "json",
        "on_log": capture_inference,
    },
)

func captureInference(inferenceFile *os.File) func(stagehand.StagehandLog) {
	return func(entry stagehand.StagehandLog) {
		// Persist only the LLM records for offline analysis
		if category, ok := entry.Data["category"]; ok && string(category) == `"llm"` {
			_ = json.NewEncoder(inferenceFile).Encode(entry)
		}
	}
}

browser, err := stagehand.LaunchLocalBrowser(ctx, &stagehand.LocalBrowserLaunchOptions{})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level: stagehand.StagehandClientLogLevelDebug,
		OnLog: captureInference(inferenceFile),
	},
})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Debug-level records include:

Inference request

Emitted before each LLM call, carrying the operation and prompt metadata:

{
  "level": "debug",
  "message": "inference started",
  "data": {
    "category": "llm",
    "operation": "act",
    "model": "openai/gpt-5.4-mini"
  }
}

Inference response

Emitted when the model returns, carrying the selected element:

{
  "level": "debug",
  "message": "inference completed",
  "data": {
    "category": "llm",
    "operation": "act",
    "elementId": "0-1183",
    "method": "click"
  }
}

Usage summary

Emitted once per operation with the token and latency accounting:

{
  "level": "debug",
  "message": "act inference usage",
  "data": {
    "category": "llm",
    "promptTokens": 3451,
    "completionTokens": 45,
    "inferenceTimeMs": 951
  }
}

Token counters are also aggregated across the whole session. See Observability for the cumulative view.

Reference

Logging configuration

Pass all logging options as a single object to Stagehand.create():

TypeScript
Python
Go

// The shape of the `logging` value in the Stagehand.create() options.
type StagehandClientLoggingConfig = {
  level?: "off" | "error" | "warn" | "info" | "debug"; // default: "info"
  format?: "pretty" | "json"; // default: "pretty"
  onLog?: (log: StagehandLog) => void | Promise<void>; // default: undefined
};

stagehand = await Stagehand.create(
    browser=browser,
    # ... your other configurations (browser, model, etc.)
    logging={
        "level": "info",  # "off" | "error" | "warn" | "info" | "debug"
        "format": "pretty",  # "pretty" | "json"
        "on_log": None,  # Callable[[StagehandLog], None | Awaitable[None]]
    },
)

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Logging: &stagehand.StagehandClientLoggingConfig{
		Level:  stagehand.StagehandClientLogLevelInfo,
		Format: stagehand.StagehandClientLogFormatPretty,
		OnLog:  func(entry stagehand.StagehandLog) {},
	},
	// ... your other configurations (Browser, Model, etc.)

})
if err != nil {
	return err
}

defer func() { err = errors.Join(err, client.Close(ctx)) }()

Option	Default	Description
level	`info`	Minimum level to emit: `off`, `error`, `warn`, `info`, or `debug`
format	`pretty`	Console rendering: human-readable lines or one JSON object per line
log callback	none	Receives every record that passes the level filter, alongside the console output

The level is also forwarded to the Stagehand runtime, so suppressed records are never generated or sent over the wire. Raising it to debug increases both log volume and message traffic.

Log structure

Each log entry follows a structured format:

TypeScript
Python
Go

interface StagehandLog {
  level: "debug" | "info" | "warn" | "error"; // Severity
  message: string;                            // "act completed successfully"
  data: Record<string, unknown>;              // Structured metadata, JSON-serializable
}

class StagehandLog(BaseModel):
    level: StagehandLogLevel  # "debug" | "info" | "warn" | "error"
    message: str              # "act completed successfully"
    data: StagehandLogData    # Structured metadata, JSON-serializable

type StagehandLog struct {
	Level   StagehandLogLevel // "debug" | "info" | "warn" | "error"
	Message string            // "act completed successfully"
	Data    StagehandLogData  // map[string]json.RawMessage
}

Unlike v3’s LogLine, data is a flat JSON object: values are already typed, so there is no { value, type } wrapper to parse. Fields such as category and timestamp appear inside data when the emitting operation provides them.

Log examples

Successful action
LLM inference
Error

{
  "level": "info",
  "message": "act completed successfully",
  "data": {
    "category": "action",
    "selector": "xpath=/html[1]/body[1]/button[1]",
    "executionTimeMs": 1250
  }
}

{
  "level": "debug",
  "message": "inference completed",
  "data": {
    "category": "llm",
    "model": "openai/gpt-5.4-mini",
    "promptTokens": 3451,
    "completionTokens": 45
  }
}

{
  "level": "error",
  "message": "action failed: element not found",
  "data": {
    "category": "action",
    "selector": "#missing-btn",
    "url": "https://example.com/form"
  }
}

Next steps

Now that you have logging configured, explore additional debugging and monitoring tools in the Observability guide:

Tracing

Export OpenTelemetry spans for every Stagehand operation to your own collector, with trace context propagated across the SDK and runtime boundary.

Metrics API

Monitor token usage and performance in real-time. Track costs per operation, identify expensive calls, and optimize resource usage.

LLM inference debugging

Run at the debug level to see exactly what Stagehand sent to the model and why the model chose each action.

Browserbase session monitoring

Watch your automation visually with session recordings, network monitoring, and real-time browser inspection (Browserbase only).

First steps

The basics

Configuration

Best practices

Migration guide

SDK reference

Quick start

Operational logging

Verbosity level

Log destinations

External logging platforms

Sentry

DataDog

File-based session logging

Setup

Usage

Viewing logs

Log files

LLM inference debugging

Reference

Logging configuration

Log structure

Next steps

Tracing

Metrics API

LLM inference debugging

Browserbase session monitoring

​Quick start

​Operational logging

​Verbosity level

​Log destinations

​External logging platforms

​Sentry

​DataDog

​File-based session logging

​Setup

​Usage

​Viewing logs

​Log files

​LLM inference debugging

​Reference

​Logging configuration

​Log structure

​Next steps

Tracing

Metrics API

LLM inference debugging

Browserbase session monitoring

Quick start

Operational logging

Verbosity level

Log destinations

External logging platforms

Sentry

DataDog

File-based session logging

Setup

Usage

Viewing logs

Log files

LLM inference debugging

Reference

Logging configuration

Log structure

Next steps