> ## Documentation Index
> Fetch the complete documentation index at: https://uncoded.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring — Spotting Issues Before They're Crises

> What to watch, where to watch it, and what 'normal' looks like. Building the situational awareness that catches problems early.

<Info>
  **Monitoring is the layer that turns 'something seems off' from intuition into actionable signal.** The Dashboard surfaces every metric you need, but you have to know what to watch and what 'normal' looks like to spot deviation. This page tells you what.
</Info>

## What to monitor — the priority list

<CardGroup cols={2}>
  <Card title="1. Connection state" icon="signal">
    Is the TradingBot connected to every active venue? Is the database reachable? Are all containers healthy?

    First-priority because nothing else matters if connections are down.
  </Card>

  <Card title="2. Kill switch state" icon="power-off">
    Is the kill switch in the expected state? Accidentally-flipped switches are a real source of "why isn't the bot trading" confusion.
  </Card>

  <Card title="3. Trade frequency vs expectation" icon="clock">
    Is the bot producing trades at the rate your mode/symbol pairing predicted? Sudden silence or sudden flood are flags.
  </Card>

  <Card title="4. Win rate trend" icon="trophy">
    Is the win rate trending stable, up, or down? Sustained downward trend over 2+ weeks suggests regime mismatch.
  </Card>

  <Card title="5. Drawdown character" icon="chart-line-down">
    Is the current drawdown within backtest expectations? Beyond expectations is a flag.
  </Card>

  <Card title="6. Per-pair P&L" icon="boxes-stacked">
    Are some pairs dragging? Some pairs carrying the rest? Asymmetric performance is information.
  </Card>

  <Card title="7. Log error rate" icon="circle-exclamation">
    Recurring errors in the Logs panel — rare = OK, frequent = investigate.
  </Card>

  <Card title="8. API key audit log" icon="key">
    The venue's audit log. Monthly review for unfamiliar activity.
  </Card>
</CardGroup>

## Where to watch — the surfaces

<AccordionGroup>
  <Accordion title="Dashboard — the primary surface" icon="gauge">
    Live trades, positions, modes, pairs, kill switch, log stream, analytics. The hub.

    Check daily for `2–5` minutes; weekly for `30` minutes structured review.
  </Accordion>

  <Accordion title="Telegram chat — the firehose" icon="paper-plane">
    Every closed trade. Running totals. Quick scan during the day for "is everything closing as expected?"

    Mute notifications during sleep hours; review the chat in the morning.
  </Accordion>

  <Accordion title="Logs panel (in Dashboard)" icon="terminal">
    Live stream of TradingBot output. Use during:

    * First hour after any change (new pair, mode, key rotation).
    * Investigations (why did this trade not fire?).
    * Confidence checks (is the bot actually doing anything?).
  </Accordion>

  <Accordion title="Venue's API audit log" icon="building-columns">
    Each exchange's API management page has audit logs. Monthly review for anomalies.
  </Accordion>

  <Accordion title="VPS-level monitoring" icon="server">
    Disk space, memory, CPU. The bot is robust to occasional resource pressure but monitoring catches issues early.

    Tools: standard VPS monitoring (Netdata, Prometheus + Grafana, or your provider's built-in). Most operators use the simple solution: occasional `top`, `df`, `free` commands.
  </Accordion>

  <Accordion title="External monitoring (optional)" icon="globe">
    UptimeRobot, Better Uptime, or similar can ping your reverse-proxy endpoints periodically and alert if down.

    Worth setting up for `dashboard` and (if applicable) `signals.yourdomain.com`.
  </Accordion>
</AccordionGroup>

## What "normal" looks like — building intuition

<AccordionGroup>
  <Accordion title="BasicMode on BTCUSDT — typical day" icon="seedling">
    With `$20,000` capital:

    * `2-6` round-trips per day on average.
    * Per-trade P\&L ranging `$5-$200` (most clustered around `$10-$50`).
    * Average hold time: hours.
    * Win rate: `~75-85%`.
    * Drawdown character: small dips into `-2% to -5%`, recovering within hours.
  </Accordion>

  <Accordion title="When that pattern becomes abnormal" icon="circle-exclamation">
    Flags worth investigating:

    * Zero trades for `24+` hours when typically `5+` per day. (Buy conditions not triggering, or kill switch on.)
    * `50+` trades in a single day when typically `5`. (Overtrading; check trigger configuration.)
    * Drawdown reaching `-15%` when typical max is `-5%`. (Regime shift; consider kill switch.)
    * Sudden win-rate drop to `<50%`. (Regime mismatch.)
  </Accordion>

  <Accordion title="Multi-pair operations — typical" icon="boxes-stacked">
    Running `BTCUSDT`, `ETHUSDT`, `SOLUSDT` on BasicMode:

    * `5-15` trades per day combined.
    * One pair often leads daily; rotation across the week.
    * Aggregate drawdown character similar to single-pair.
  </Accordion>

  <Accordion title="Per-mode behaviors differ" icon="puzzle-piece">
    * **BasicMode**: high-frequency, small per-trade.
    * **FullBullMarket**: medium-frequency, medium per-trade, longer hold times.
    * **LongTimeLong**: low-frequency, large per-trade, multi-day holds.
    * **Tsl2Sell**: variable based on trends.

    Calibrate your "normal" expectation to the mode you're running.
  </Accordion>
</AccordionGroup>

## Anomaly response — the decision tree

<Steps>
  <Step title="Anomaly observed">
    Something looks off. Could be unusual trade rate, drawdown, error pattern, connection issue.
  </Step>

  <Step title="Step 1: is it within historical range?">
    Compare to backtest expectations. If within range → likely just normal regime variation. Continue monitoring; don't act.
  </Step>

  <Step title="Step 2: is the connection healthy?">
    If connection issues: investigate (network, exchange, IP allowlist). Repair before evaluating performance.
  </Step>

  <Step title="Step 3: is the configuration as expected?">
    Did you (or someone) accidentally change something? Review recent operator log; check Modes panel.
  </Step>

  <Step title="Step 4: is the regime shift the cause?">
    If yes: decide whether to ride through (BasicMode handles regime shifts OK), kill-switch off (Tsl2Sell may be hurting), or change modes (deliberate move).
  </Step>

  <Step title="Step 5: kill switch off if uncertain">
    When in doubt, kill switch ON. Investigate without active risk. Re-enable when you're clear.
  </Step>

  <Step title="Step 6: document the incident">
    Operator log entry: what happened, what you observed, what you did, what the resolution was. Future-you benefits.
  </Step>
</Steps>

## Common anomalies and what they mean

<AccordionGroup>
  <Accordion title="Bot stopped trading suddenly" icon="circle-pause">
    Most common causes:

    1. Kill switch ON (most common).
    2. Exchange-side outage.
    3. Rate limit being hit.
    4. Min-notional rejections (capital too small for splits).
    5. Insufficient balance.
    6. API key revoked at venue.

    Dashboard logs surface every refusal-to-trade with a clear reason.
  </Accordion>

  <Accordion title="Bot trading much more than usual" icon="bolt">
    Most common causes:

    1. SignalEditor strategy with wrong trigger mode (`once_per_minute` instead of `once_per_bar_close`).
    2. New volatility regime triggering more buy signals.
    3. Symbol added without recognizing its characteristics.

    Investigate the trigger frequency in Logs.
  </Accordion>

  <Accordion title="Win rate dropped substantially" icon="trophy">
    Most common causes:

    1. Regime shift — mode is now mismatched.
    2. New symbol added that doesn't fit the mode.
    3. Stop-loss triggering more frequently due to volatility.

    Per-pair analytics often pinpoint which pair is the drag.
  </Accordion>

  <Accordion title="Drawdown beyond historical range" icon="chart-line-down">
    Most common causes:

    1. Black-swan-style market event.
    2. Regime mismatch with mode.
    3. Concentration on a struggling pair.

    Decide:

    * Kill switch ON to halt new buying.
    * Hold existing positions through (if drawdown is recovery-likely).
    * Manually close (if you've lost confidence).

    Don't impulse-close at the bottom.
  </Accordion>

  <Accordion title="Connection state intermittent" icon="wifi">
    Most common causes:

    1. VPS network issues.
    2. Exchange-side instability.
    3. DNS issues.

    Brief intermittents are normal. Persistent intermittent (every few minutes) is investigation-worthy.
  </Accordion>

  <Accordion title="Telegram running total disagrees with Dashboard" icon="balance-scale">
    Most common causes:

    1. Bot was offline during a trade (Telegram missed).
    2. Database restored from backup, resetting the running total.
    3. Manual close not reflected in one of the surfaces.

    Dashboard's analytics are the source of truth. Telegram running total is a convenience.
  </Accordion>
</AccordionGroup>

## Setting up external alerting

<AccordionGroup>
  <Accordion title="Why external alerting" icon="bell">
    External monitoring catches things you might not see in your daily routine:

    * Dashboard down (TLS expired? Container crashed?).
    * SignalsBot down (webhooks failing).
    * VPS down (provider issue).

    Push notifications when something is wrong = faster operator response.
  </Accordion>

  <Accordion title="UptimeRobot — free tier, simple setup" icon="clock">
    Sign up at UptimeRobot. Add monitors for:

    * `https://dashboard.yourdomain.com/api/health` (or appropriate health endpoint).
    * `https://signals.yourdomain.com/health`.

    Configure email/SMS notifications. Most operators get an alert in under a minute when something goes down.
  </Accordion>

  <Accordion title="Better Uptime — paid, more features" icon="chart-line">
    More sophisticated alerting (escalation policies, on-call rotation, status pages). For operators running larger setups or wanting professional-grade monitoring.
  </Accordion>

  <Accordion title="Custom Telegram alerts" icon="paper-plane">
    For operators comfortable with scripting: a small custom monitor that pings your endpoints and sends Telegram messages on failure.

    Cheap, no third-party dependency, integrates with your existing Telegram channel.
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  * ✅ **Daily 5-minute Dashboard scan** to build intuition for normal.
  * ✅ **Weekly 30-minute structured review** to catch trends.
  * ✅ **External monitoring** (UptimeRobot or similar) for uptime alerts.
  * ✅ **Match expectations to your mode** — BasicMode normal differs from LongTimeLong normal.
  * ✅ **Investigate anomalies before reacting** — most are noise, some are signal.
  * ✅ **Use kill switch when uncertain** — false alarms are free.
  * ✅ **Document incidents in operator log** — pattern recognition improves over time.
  * ✅ **Don't over-react to single-day variance** — hold-period thinking matters.
  * ✅ **Don't under-react to multi-day patterns** — sustained anomalies are signal.
  * ✅ **Set up alerting before you need it** — operators reach for monitoring during their first crisis, then realize they didn't have it.
</Tip>

## What's next

<CardGroup cols={2}>
  <Card title="Daily operations" icon="calendar-day" href="/operations/daily-operations">
    The routines that keep monitoring sustainable.
  </Card>

  <Card title="Common issues" icon="circle-exclamation" href="/troubleshooting/common-issues">
    Specific problems and their fixes.
  </Card>

  <Card title="Connection problems" icon="wifi" href="/troubleshooting/connection-problems">
    What to do when bot loses connectivity.
  </Card>

  <Card title="Risk overview" icon="shield" href="/risk-management/overview">
    Monitoring fits into the broader risk framework.
  </Card>

  <Card title="Dashboard module" icon="gauge" href="/modules/dashboard">
    The primary monitoring surface.
  </Card>

  <Card title="Support" icon="life-ring" href="/operations/support">
    When monitoring catches something you can't fix.
  </Card>
</CardGroup>