Skip to content

cloudthinker-ai/CloudSkills / skills/connections/managing-better-stack

managing-better-stack

Unverified

Use when working with Better Stack — better Stack (formerly Logtail) for log search, uptime monitoring, incident management, on-call scheduling, and status page management. Covers log querying, monitor configuration, heartbeat checks, escalation policies, and team management. Use when searching logs, managing uptime monitors, handling incidents, or configuring on-call schedules via Better Stack API.

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 jq to 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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/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 errorAssumed 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_page and cursor-based pagination — check pagination.next for 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-pages endpoint — link monitors to status page resources
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall