# Monitoring & Logs

# Monitoring & Logs

Monitor your server with activity logs, player statistics, and detailed performance metrics.

## Activity Log

The Activity Log tracks all significant events on your server.

### Accessing the Log

Navigate to **Activity** in the sidebar to view the activity log.

### Event Categories

| Category | Events Tracked |
|----------|----------------|
| **Player** | Joins, leaves, kicks, bans |
| **Server** | Start, stop, restart, crashes |
| **Backup** | Creation, restoration, deletion |
| **Config** | Settings changes, file edits |
| **Mod** | Install, update, remove |
| **User** | Panel user actions |
| **System** | System events, updates |

### Filtering

1. Click the **Filter** dropdown
2. Select one or more categories
3. Log updates to show matching entries

### Log Entry Information

Each entry shows:
- **Timestamp** - When the event occurred
- **Category** - Event type (color-coded)
- **User** - Who performed the action
- **Details** - Description of what happened
- **Status** - Success/failure indicator

### Clearing the Log

Users with `activity.manage` permission can clear the log:
1. Click **Clear Log**
2. Confirm the action
3. All entries are removed

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/management/activity` | Get activity log |
| POST | `/api/management/activity/clear` | Clear activity log |

### Permissions

| Permission | Description |
|------------|-------------|
| `activity.view` | View activity log |
| `activity.manage` | Clear activity log |

---

## Statistics Dashboard

View comprehensive player and server statistics.

### Accessing Statistics

Navigate to **Statistics** in the sidebar.

### Player Statistics

| Metric | Description |
|--------|-------------|
| **Total Players** | All-time unique players |
| **Peak Online Today** | Highest concurrent today |
| **Active Players (7d)** | Players active in last week |
| **New Players (7d)** | First-time joins this week |

### Playtime Statistics

| Metric | Description |
|--------|-------------|
| **Total Playtime** | Sum of all player time |
| **Average Playtime** | Per player average |
| **Sessions per Player** | Average login count |

### Weekly Activity Chart

A visual chart showing:
- Daily unique player counts
- 7-day trend visualization
- Peak day indicators

### Top Players

List of most active players:
- Player name
- Total playtime
- Session count
- Last seen

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/scheduler/statistics/players` | Player statistics |
| GET | `/api/scheduler/statistics/activity` | Daily activity data |

---

## Performance Monitoring

Real-time server performance monitoring with detailed metrics.

### Accessing Performance

Navigate to **Performance** in the sidebar.

### Live Metrics

The dashboard shows real-time values for:
- **CPU Usage** - Percentage (process and system)
- **Memory Usage** - Heap and non-heap
- **TPS** - Ticks per second (target: 20)
- **Players** - Current online count
- **Status** - Server state

### Performance Graphs

Four real-time graphs display:
1. **CPU Usage** - 60-point history
2. **Memory Usage** - Heap allocation over time
3. **Players** - Online player count history
4. **TPS** - Server performance trend

### TPS Thresholds

| TPS Range | Status | Indicator |
|-----------|--------|-----------|
| 19+ TPS | Good | Green |
| 15-18 TPS | Warning | Yellow |
| Below 15 TPS | Critical | Red |

### Prometheus Integration

For detailed metrics, install the **ApexHosting:PrometheusExporter** plugin.

#### JVM Metrics

| Metric | Description |
|--------|-------------|
| Heap Memory | Used, committed, max |
| Non-Heap Memory | Metaspace, code cache |
| Memory Pools | Eden, Survivor, Old Gen |

#### Thread Metrics

| Metric | Description |
|--------|-------------|
| Current Threads | Active thread count |
| Daemon Threads | Background threads |
| Peak Threads | Maximum reached |

#### Server Metrics

| Metric | Description |
|--------|-------------|
| Sessions | Join/leave counts |
| Worlds Loaded | Number of active worlds |
| Players per World | Distribution by world |
| GC Statistics | Garbage collection data |

### Performance API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/server/memory` | JVM memory stats |
| GET | `/api/server/tps-metrics` | TPS from Prometheus |
| GET | `/api/server/prometheus` | Full Prometheus metrics |
| GET | `/api/management/stats/history` | Historical statistics |

### Permissions

| Permission | Description |
|------------|-------------|
| `performance.view` | View performance metrics |

---

## Whitelist & Ban Management

Dedicated interface for managing server access.

### Accessing

Navigate to **Whitelist** in the sidebar.

### Whitelist Tab

#### Enable Whitelist

1. Toggle the **Enable Whitelist** switch
2. Only whitelisted players can join

#### Adding Players

1. Enter player name in the input field
2. Click **Add**
3. Player appears in the list

#### Removing Players

1. Find the player in the list
2. Click the **Remove** (X) button
3. Player is removed from whitelist

### Bans Tab

#### Banning Players

1. Switch to **Bans** tab
2. Enter player name
3. Optionally add a reason
4. Click **Ban**

#### Unbanning Players

1. Find the player in the ban list
2. Click **Unban**
3. Player can rejoin the server

### Search

Both lists support search:
1. Type in the search field
2. List filters in real-time

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/management/whitelist` | Get whitelist status |
| PUT | `/api/management/whitelist` | Update whitelist settings |
| POST | `/api/management/whitelist/:player` | Add to whitelist |
| DELETE | `/api/management/whitelist/:player` | Remove from whitelist |
| GET | `/api/management/bans` | Get ban list |
| POST | `/api/management/bans` | Ban a player |
| DELETE | `/api/management/bans/:player` | Unban a player |

### Permissions

| Permission | Description |
|------------|-------------|
| `players.whitelist` | Manage whitelist |
| `players.ban` | Ban players |
| `players.unban` | Unban players |