justinzeus/scholarr
1
0
Fork 0
Code Issues 1 Pull requests 18 Projects Releases Packages Wiki Activity Actions

docs: rebuild documentation from scratch with clean IA

Browse source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Justin Visser 2026-02-27 09:39:27 +01:00
parent 6c31b331f7
commit 0c5b199b76
30 changed files with 1647 additions and 649 deletions
Download patch file Download diff file Expand all files Collapse all files

88
docs/operations/scrape-safety-runbook.md
View file

@ -1,74 +1,76 @@
---
title: Scrape Safety Runbook
sidebar_position: 4
---
# Scrape Safety Runbook
This runbook covers operational handling for scrape safety cooldowns, threshold alerts, and blocked-IP events.
Operational handling for scrape safety cooldowns, threshold alerts, and blocked-IP events.
## Key Signals
Use structured log `event` fields (recommended with `LOG_FORMAT=json`):
- `ingestion.safety_policy_blocked_run_start`
- `ingestion.safety_cooldown_entered`
- `ingestion.safety_cooldown_cleared`
- `ingestion.alert_blocked_failure_threshold_exceeded`
- `ingestion.alert_network_failure_threshold_exceeded`
- `ingestion.alert_retry_scheduled_threshold_exceeded`
- `api.runs.manual_blocked_policy`
- `api.runs.manual_blocked_safety`
- `scheduler.run_skipped_safety_cooldown`
- `scheduler.run_skipped_safety_cooldown_precheck`
- `scheduler.queue_item_deferred_safety_cooldown`
| Event | Description |
|-------|-------------|
| `ingestion.safety_policy_blocked_run_start` | Run blocked by safety policy |
| `ingestion.safety_cooldown_entered` | Cooldown activated |
| `ingestion.safety_cooldown_cleared` | Cooldown expired |
| `ingestion.alert_blocked_failure_threshold_exceeded` | Blocked failure threshold tripped |
| `ingestion.alert_network_failure_threshold_exceeded` | Network failure threshold tripped |
| `ingestion.alert_retry_scheduled_threshold_exceeded` | Retry threshold tripped |
| `api.runs.manual_blocked_policy` | Manual run blocked by policy |
| `api.runs.manual_blocked_safety` | Manual run blocked by safety cooldown |
| `scheduler.run_skipped_safety_cooldown` | Scheduled run skipped due to cooldown |
| `scheduler.run_skipped_safety_cooldown_precheck` | Scheduler precheck blocked |
| `scheduler.queue_item_deferred_safety_cooldown` | Queue item deferred due to cooldown |
Each event includes metric-style fields (`metric_name`, `metric_value`) for straightforward log-based alert rules.
Each event includes metric-style fields (`metric_name`, `metric_value`) for log-based alert rules.
## Recommended Alert Rules
- Cooldown enters:
- Trigger on `event=ingestion.safety_cooldown_entered`.
- Repeated start blocks:
- Trigger on high rate of `event=api.runs.manual_blocked_safety`.
- Threshold trips:
- Trigger on any of:
- `ingestion.alert_blocked_failure_threshold_exceeded`
- `ingestion.alert_network_failure_threshold_exceeded`
- `ingestion.alert_retry_scheduled_threshold_exceeded`
- Scheduler pressure:
- Trigger on sustained `scheduler.queue_item_deferred_safety_cooldown`.
- **Cooldown enters**: Trigger on `event=ingestion.safety_cooldown_entered`
- **Repeated start blocks**: High rate of `event=api.runs.manual_blocked_safety`
- **Threshold trips**: Any of the `*_threshold_exceeded` events
- **Scheduler pressure**: Sustained `scheduler.queue_item_deferred_safety_cooldown`
## If Your IP Appears Blocked
Symptoms:
### Symptoms
- cooldown reason `blocked_failure_threshold_exceeded`
- parse state `blocked_or_captcha`
- redirects toward Google account sign-in flows
- Cooldown reason: `blocked_failure_threshold_exceeded`
- Parse state: `blocked_or_captcha`
- Redirects toward Google account sign-in flows
Actions:
### Actions
1. Stop manual retries immediately.
2. Let cooldown expire; do not spam retriggers.
3. Increase `INGESTION_MIN_REQUEST_DELAY_SECONDS` and user request delay values.
4. Reduce concurrency pressure (keep one scheduler instance).
5. Keep name-search disabled/WIP for now if login-gated responses persist.
5. Keep name-search disabled if login-gated responses persist.
6. Resume with a small monitored run and verify blocked rate drops.
Avoid:
### Avoid
- aggressive rapid retries
- rotating through risky scraping patterns that increase challenge rates
- bypass/captcha-solving workflows that may violate source platform rules
- Aggressive rapid retries
- Rotating through risky scraping patterns that increase challenge rates
- Bypass/CAPTCHA-solving workflows that may violate source platform rules
## Environment Controls
Policy floors and safety controls:
- `INGESTION_MIN_REQUEST_DELAY_SECONDS`
- `INGESTION_MIN_RUN_INTERVAL_MINUTES`
- `INGESTION_ALERT_BLOCKED_FAILURE_THRESHOLD`
- `INGESTION_ALERT_NETWORK_FAILURE_THRESHOLD`
- `INGESTION_ALERT_RETRY_SCHEDULED_THRESHOLD`
- `INGESTION_SAFETY_COOLDOWN_BLOCKED_SECONDS`
- `INGESTION_SAFETY_COOLDOWN_NETWORK_SECONDS`
- `INGESTION_MANUAL_RUN_ALLOWED`
- `INGESTION_AUTOMATION_ALLOWED`
| Variable | Default | Description |
|----------|---------|-------------|
| `INGESTION_MIN_REQUEST_DELAY_SECONDS` | `2` | Floor delay between requests |
| `INGESTION_MIN_RUN_INTERVAL_MINUTES` | `15` | Minimum time between runs |
| `INGESTION_ALERT_BLOCKED_FAILURE_THRESHOLD` | `1` | Blocked failures before alert |
| `INGESTION_ALERT_NETWORK_FAILURE_THRESHOLD` | `2` | Network failures before alert |
| `INGESTION_ALERT_RETRY_SCHEDULED_THRESHOLD` | `3` | Retries before alert |
| `INGESTION_SAFETY_COOLDOWN_BLOCKED_SECONDS` | `1800` | Cooldown after blocked threshold (30 min) |
| `INGESTION_SAFETY_COOLDOWN_NETWORK_SECONDS` | `900` | Cooldown after network threshold (15 min) |
| `INGESTION_MANUAL_RUN_ALLOWED` | `1` | Enable manual runs |
| `INGESTION_AUTOMATION_ALLOWED` | `1` | Enable automated runs |
Apply stricter values first, then relax slowly only after sustained healthy runs.