brd-browser-debug

Name: brd-browser-debug
Author: brightdata

171installs32forks

How to install brd-browser-debug?

brightdata/skills/brd-browser-debug

$npx -y skills add brightdata/skills --skill brd-browser-debug

Installs into the current project.

Summary

Debug Bright Data Scraping Browser sessions using the Browser Sessions API. Use this skill when the user encounters a Bright Data browser session error, puppeteer stack trace, failed scraper run, or asks about session bandwidth, duration, captchas, or connection issues. Also use

Files · 1

View on GitHub

SKILL.md

1	# Bright Data — Browser Session Debugger
2
3	Diagnose Bright Data Scraping Browser sessions using the Browser Sessions API. Fetches live session data and performs smart triage: error diagnosis, bandwidth analysis, captcha reporting, and pattern detection across recent sessions.
4
5	## Setup
6
7	Set your API key:
8	```bash
9	export BRIGHTDATA_API_KEY="your-api-key"
10	```
11
12	Get a key from [Bright Data Dashboard → API Tokens](https://brightdata.com/cp/setting/users).
13
14	No zone configuration needed — zone is returned as a field in session data.
15
16	## Usage
17
18	### List & triage recent sessions
19
20	Invoked as `/brd-browser-debug` with no arguments.
21
22	API reference: [GET /browser_sessions](https://docs.brightdata.com/api-reference/browser-api/get-sessions)
23
24	#### Fetching sessions
25
26	Start with a single call using `limit=100` (the maximum) sorted by most recent:
27	```
28	GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
29	Authorization: Bearer $BRIGHTDATA_API_KEY
30	```
31
32	Pagination: The response includes `total`, `has_more`, and `next_offset`. If `has_more` is true and the analysis requires more data (e.g. bandwidth outlier detection needs a larger sample), fetch the next page using `offset=<next_offset>`. Continue until you have enough data or `has_more` is false.
33
34	Available filters — apply when the user specifies a scope:
35	- `status=failed\|finished\|running` — narrow to a specific session state
36	- `api_name=<zone>` — filter to a specific Bright Data zone
37	- `target_url=<domain>` — filter by target domain (e.g. `ksp.co.il`)
38	- `start_date` / `end_date` — ISO 8601 datetime range
39	- `sort=timestamp\|duration\|bandwidth` with `order=asc\|desc`
40
41	If the user asks about a specific zone, date range, or domain — apply the relevant filter rather than fetching all sessions and filtering client-side.
42
43	#### Triage steps
44
45	1. Present a health summary: `total` from the response, counts of finished / failed / running.
46	2. Most recent session — always highlight it regardless of status (same detail level as single-session mode).
47	3. Failed sessions — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the Diagnosing Failed Sessions section below.
48	4. Pattern detection — if 3+ sessions share the same `error.code`, call it a systemic issue:
49	> "3 sessions failed with `custom_headers` — you are overriding a header Bright Data forbids. Remove `page.setExtraHTTPHeaders()` from your code."
50	5. Bandwidth outliers — group sessions by `target_url` domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any session whose bandwidth exceeds 2× the median for that domain as an outlier, and note if it was a failed session that burned unusually high bandwidth before dying.
51	6. Captcha activity — report how many sessions hit captchas and whether they were solved.
52	7. Close with a one-line verdict: the most important finding and the most impactful fix.
53
54	### Inspect a single session
55
56	Invoked as `/brd-browser-debug <session_id>`.
57
58	API reference: [GET /browser_sessions/{session_id}](https://docs.brightdata.com/api-reference/browser-api/get-session)
59
60	1. Call:
61	```
62	GET https://api.brightdata.com/browser_sessions/<session_id>
63	Authorization: Bearer $BRIGHTDATA_API_KEY
64	```
65	Returns 404 if the session ID is not found — tell the user and stop.
66
67	2. Present a deep-dive using the response fields:
68	- Status (`status`): `running` / `finished` / `failed`
69	- Zone (`api_name`): the Bright Data zone that handled the session
70	- Timestamp (`timestamp`): ISO 8601 — show in local-friendly format
71	- Duration (`duration`): seconds (nullable) — flag if < 2 s on failure (session barely started)
72	- Bandwidth (`bandwidth`): convert bytes → MB
73	- Navigations (`navigations`): flag if 0 (nothing was loaded)
74	- Captcha (`captcha`): one of `solved` / `none` / `detected` / `failed` — `d

People who liked this also viewed

6 picks

Type

brd-browser-debug

171installs32forks

View on GitHub

How to install brd-browser-debug?

brightdata/skills/brd-browser-debug

$npx -y skills add brightdata/skills --skill brd-browser-debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Bright Data — Browser Session Debugger
2
3	Diagnose Bright Data Scraping Browser sessions using the Browser Sessions API. Fetches live session data and performs smart triage: error diagnosis, bandwidth analysis, captcha reporting, and pattern detection across recent sessions.
4
5	## Setup
6
7	Set your API key:
8	```bash
9	export BRIGHTDATA_API_KEY="your-api-key"
10	```
11
12	Get a key from [Bright Data Dashboard → API Tokens](https://brightdata.com/cp/setting/users).
13
14	No zone configuration needed — zone is returned as a field in session data.
15
16	## Usage
17
18	### List & triage recent sessions
19
20	Invoked as `/brd-browser-debug` with no arguments.
21
22	API reference: [GET /browser_sessions](https://docs.brightdata.com/api-reference/browser-api/get-sessions)
23
24	#### Fetching sessions
25
26	Start with a single call using `limit=100` (the maximum) sorted by most recent:
27	```
28	GET https://api.brightdata.com/browser_sessions?limit=100&sort=timestamp&order=desc
29	Authorization: Bearer $BRIGHTDATA_API_KEY
30	```
31
32	Pagination: The response includes `total`, `has_more`, and `next_offset`. If `has_more` is true and the analysis requires more data (e.g. bandwidth outlier detection needs a larger sample), fetch the next page using `offset=<next_offset>`. Continue until you have enough data or `has_more` is false.
33
34	Available filters — apply when the user specifies a scope:
35	- `status=failed\|finished\|running` — narrow to a specific session state
36	- `api_name=<zone>` — filter to a specific Bright Data zone
37	- `target_url=<domain>` — filter by target domain (e.g. `ksp.co.il`)
38	- `start_date` / `end_date` — ISO 8601 datetime range
39	- `sort=timestamp\|duration\|bandwidth` with `order=asc\|desc`
40
41	If the user asks about a specific zone, date range, or domain — apply the relevant filter rather than fetching all sessions and filtering client-side.
42
43	#### Triage steps
44
45	1. Present a health summary: `total` from the response, counts of finished / failed / running.
46	2. Most recent session — always highlight it regardless of status (same detail level as single-session mode).
47	3. Failed sessions — for each failure: session ID, timestamp, duration, bandwidth, then reason about the cause using the signals in the Diagnosing Failed Sessions section below.
48	4. Pattern detection — if 3+ sessions share the same `error.code`, call it a systemic issue:
49	> "3 sessions failed with `custom_headers` — you are overriding a header Bright Data forbids. Remove `page.setExtraHTTPHeaders()` from your code."
50	5. Bandwidth outliers — group sessions by `target_url` domain. For each domain with 3+ sessions, calculate the median bandwidth. Flag any session whose bandwidth exceeds 2× the median for that domain as an outlier, and note if it was a failed session that burned unusually high bandwidth before dying.
51	6. Captcha activity — report how many sessions hit captchas and whether they were solved.
52	7. Close with a one-line verdict: the most important finding and the most impactful fix.
53
54	### Inspect a single session
55
56	Invoked as `/brd-browser-debug <session_id>`.
57
58	API reference: [GET /browser_sessions/{session_id}](https://docs.brightdata.com/api-reference/browser-api/get-session)
59
60	1. Call:
61	```
62	GET https://api.brightdata.com/browser_sessions/<session_id>
63	Authorization: Bearer $BRIGHTDATA_API_KEY
64	```
65	Returns 404 if the session ID is not found — tell the user and stop.
66
67	2. Present a deep-dive using the response fields:
68	- Status (`status`): `running` / `finished` / `failed`
69	- Zone (`api_name`): the Bright Data zone that handled the session
70	- Timestamp (`timestamp`): ISO 8601 — show in local-friendly format
71	- Duration (`duration`): seconds (nullable) — flag if < 2 s on failure (session barely started)
72	- Bandwidth (`bandwidth`): convert bytes → MB
73	- Navigations (`navigations`): flag if 0 (nothing was loaded)
74	- Captcha (`captcha`): one of `solved` / `none` / `detected` / `failed` — `d

People who liked this also viewed

6 picks

Type