cloudthinker-ai Better Stack Management Skill
Manage logs, uptime monitoring, and incidents using the Better Stack API.
API Conventions
Authentication
Better Stack API uses Bearer token — injected by connection. Never hardcode tokens.
Base URLs
- Uptime API:
https://uptime.betterstack.com/api/v2/ - Logs API:
https://logs.betterstack.com/api/v2/ - Use connection-injected
BETTERSTACK_BASE_URL.
Output Rules
- TOKEN EFFICIENCY: Target <=50 lines per output
- Use
jqto extract relevant monitor and log fields - NEVER dump full API responses — always filter and summarize
Core Helper Function
#!/bin/bash
bs_uptime_api() {
local method="$1"
local endpoint="$2"
local data="${3:-}"
if [ -n "$data" ]; then
curl -s -X "$method" \
-H "Authorization: Bearer ${BETTERSTACK_API_TOKEN}" \
-H "Content-Type: application/json" \
"https://uptime.betterstack.com/api/v2${endpoint}" \
-d "$data"
else
curl -s -X "$method" \
-H "Authorization: Bearer ${BETTERSTACK_API_TOKEN}" \
"https://uptime.betterstack.com/api/v2${endpoint}"
fi
}
bs_logs_api() {
local method="$1"
local endpoint="$2"
local data="${3:-}"
if [ -n "$data" ]; then
curl -s -X "$method" \
-H "Authorization: Bearer ${BETTERSTACK_API_TOKEN}" \
-H "Content-Type: application/json" \
"https://logs.betterstack.com/api/v2${endpoint}" \
-d "$data"
else
curl -s -X "$method" \
-H "Authorization: Bearer ${BETTERSTACK_API_TOKEN}" \
"https://logs.betterstack.com/api/v2${endpoint}"
fi
}
Parallel Execution
{
bs_uptime_api GET "/monitors" &
bs_uptime_api GET "/incidents" &
bs_uptime_api GET "/heartbeats" &
bs_uptime_api GET "/on-call-calendars" &
}
wait
Anti-Hallucination Rules
NEVER assume monitor IDs, source names, or team IDs. ALWAYS discover first.
Phase 1: Discovery
#!/bin/bash
echo "=== Uptime Monitors ==="
bs_uptime_api GET "/monitors" \
| jq -r '.data[] | "\(.id)\t\(.attributes.monitor_type)\t\(.attributes.status)\t\(.attributes.url // .attributes.ip)"' | head -20
echo ""
echo "=== Log Sources ==="
bs_logs_api GET "/sources" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)\t\(.attributes.platform)"' | head -15
echo ""
echo "=== On-Call Calendars ==="
bs_uptime_api GET "/on-call-calendars" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)"' | head -10
echo ""
echo "=== Monitor Groups ==="
bs_uptime_api GET "/monitor-groups" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)"' | head -10
Common Operations
Log Search
#!/bin/bash
echo "=== Recent Logs ==="
bs_logs_api POST "/query" \
'{"query":"level:error","from":"now-1h","to":"now","batch_size":20}' \
| jq -r '.data[:20][] | "\(.attributes.timestamp[0:19])\t\(.attributes.level // "info")\t\(.attributes.message[0:80])"'
echo ""
echo "=== Log Volume by Source ==="
bs_logs_api GET "/sources" \
| jq -r '.data[] | "\(.attributes.name)\t\(.attributes.logs_count // 0) total logs\t\(.attributes.platform)"' | head -15
Uptime Monitor Management
#!/bin/bash
echo "=== Monitor Status Overview ==="
MONITORS=$(bs_uptime_api GET "/monitors")
echo "$MONITORS" | jq '{
total: (.data | length),
up: [.data[] | select(.attributes.status == "up")] | length,
down: [.data[] | select(.attributes.status == "down")] | length,
paused: [.data[] | select(.attributes.paused == true)] | length
}'
echo ""
echo "=== Down Monitors ==="
echo "$MONITORS" | jq -r '.data[] | select(.attributes.status == "down") | "\(.attributes.pronounceable_name)\t\(.attributes.url // .attributes.ip)\tdown_since:\(.attributes.last_checked_at)"'
echo ""
echo "=== Monitor Response Times ==="
echo "$MONITORS" | jq -r '.data[] | select(.attributes.status == "up") | "\(.attributes.pronounceable_name)\t\(.attributes.last_response_time // "N/A")ms"' \
| sort -t$'\t' -k2 -rn | head -15
Incident Management
#!/bin/bash
echo "=== Open Incidents ==="
bs_uptime_api GET "/incidents?per_page=20" \
| jq -r '.data[] | select(.attributes.resolved_at == null) | "\(.id)\t\(.attributes.started_at[0:16])\t\(.attributes.cause)\t\(.attributes.name[0:50])"' | head -15
echo ""
echo "=== Recent Resolved Incidents ==="
bs_uptime_api GET "/incidents?per_page=20" \
| jq -r '.data[] | select(.attributes.resolved_at != null) | "\(.attributes.resolved_at[0:10])\t\(.attributes.duration)s\t\(.attributes.name[0:50])"' | head -10
echo ""
echo "=== Incident Summary ==="
bs_uptime_api GET "/incidents?per_page=100" \
| jq '{
total: (.data | length),
open: [.data[] | select(.attributes.resolved_at == null)] | length,
resolved: [.data[] | select(.attributes.resolved_at != null)] | length,
avg_duration_s: ([.data[] | select(.attributes.duration != null) | .attributes.duration] | if length > 0 then add / length | round else 0 end)
}'
Heartbeat Monitoring
#!/bin/bash
echo "=== Heartbeat Monitors ==="
bs_uptime_api GET "/heartbeats" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)\t\(.attributes.status)\t\(.attributes.period)s interval"' | head -15
echo ""
echo "=== Failing Heartbeats ==="
bs_uptime_api GET "/heartbeats" \
| jq -r '.data[] | select(.attributes.status == "down") | "\(.attributes.name)\tlast_beat:\(.attributes.last_checked_at // "never")"'
On-Call & Escalation
#!/bin/bash
echo "=== On-Call Calendars ==="
bs_uptime_api GET "/on-call-calendars" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)\t\(.attributes.default_calendar)"'
echo ""
echo "=== Escalation Policies ==="
bs_uptime_api GET "/escalation-policies" \
| jq -r '.data[] | "\(.id)\t\(.attributes.name)\tsteps:\(.attributes.steps | length)"' | head -10
echo ""
echo "=== Policy Details ==="
bs_uptime_api GET "/escalation-policies" \
| jq -r '.data[] | "\(.attributes.name):", (.attributes.steps[] | " Step \(.step_number): wait \(.wait_before)s -> \(.targets | length) targets")'
Output Format
Present results as a structured report:
Managing Better Stack Report
════════════════════════════
Resources discovered: [count]
Resource Status Key Metric Issues
──────────────────────────────────────────────
[name] [ok/warn] [value] [findings]
Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]
Target ≤50 lines of output. Use tables for multi-resource comparisons.
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|---|---|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |
Common Pitfalls
- Dual APIs: Uptime and Logs have separate base URLs — use the correct one for each resource type
- Monitor types:
status,expected_status_code,keyword,keyword_absence,ping,tcp,udp,smtp,pop,imap - Pagination: Uses
per_pageand cursor-based pagination — checkpagination.nextfor more pages - Rate limits: 250 requests/minute — stagger parallel calls for bulk operations
- Source tokens: Log sources have individual source tokens for ingestion — different from API token
- Incident lifecycle: Incidents auto-created by monitors — acknowledge or resolve via API
- Heartbeat URL: Each heartbeat has a unique URL for pinging — GET request to URL records a heartbeat
- Status pages: Managed separately via
/status-pagesendpoint — link monitors to status page resources