# iClock Logging & Monitoring Guide

## Overview
Comprehensive logging has been added to all device POST endpoints to help analyze incoming data from biometric devices.

## Logging Locations

### 1. **Dedicated iClock Log** (Recommended)
```
storage/logs/iclock.log
```
- **Rotates daily** (keeps 30 days of logs)
- **Contains all device interactions**
- **Includes:** Handshakes, registry, data records, and errors

### 2. **Main Application Log** (Fallback)
```
storage/logs/laravel.log
```
- Contains all application logs
- Mix of iClock and other application events

## What Gets Logged

### Handshake (`GET /iclock/cdata`)
```json
{
  "sn": "NYU7255000824",
  "option": "...",
  "content_length": 150,
  "all_inputs": {...},
  "user_agent": "iClock Proxy/1.09",
  "ip": "172.69.166.111"
}
```

### Device Registry (`POST /iclock/registry`)
```json
{
  "sn": "NYU7255000824",
  "content_length": 200,
  "user_agent": "iClock Proxy/1.09",
  "ip": "172.69.166.111",
  "raw_content_preview": "..."
}
```

### Receive Records (`POST /iclock/cdata`)
```json
{
  "sn": "NYU7255000824",
  "table": "ATTLOG",
  "stamp": 9999,
  "content_length": 5000,
  "raw_content_preview": "...",
  "total_records": 500,
  "records_processed": 500
}
```

### Error Logging
All exceptions are logged with:
- Device serial number (SN)
- Error message
- Full stack trace
- Timestamp

## Viewing Logs

### Real-time Log Tail
```bash
cd /var/www/html/adms/adms-server
tail -f storage/logs/iclock.log
```

### View Last 50 Lines
```bash
tail -50 storage/logs/iclock.log
```

### Search for Specific Device
```bash
grep "NYU7255000824" storage/logs/iclock.log
```

### View Today's Errors Only
```bash
grep "ERROR\|Exception" storage/logs/iclock.log
```

### Count Records Processed by Device
```bash
grep "Attendance records processed successfully" storage/logs/iclock.log | grep "NYU7255000824"
```

### View Invalid Record Formats
```bash
grep "Invalid record format" storage/logs/iclock.log
```

### Check Device Registry Events
```bash
grep "DEVICE REGISTRY\|Device registered successfully" storage/logs/iclock.log
```

## Log Format Structure

Each log entry contains:
- **Timestamp**: When the event occurred
- **Level**: INFO, DEBUG, WARNING, ERROR
- **Message**: What happened
- **Context**: Array of relevant data (SN, employee_id, timestamps, etc.)

Example:
```
[2026-06-01 10:30:45] development.INFO: Attendance records processed successfully {"sn":"NYU7255000824","total_records":150,"table":"ATTLOG"}
```

## Database vs Logs

| Data Stored | Location | Purpose |
|-------------|----------|---------|
| **Parsed attendance data** | `attendances` table | Business analytics |
| **Raw POST data** | `finger_log` table | Audit trail |
| **Device communication** | `device_log` table | Device status history |
| **Error messages** | `error_log` table | Debugging |
| **Complete request data** | `iclock.log` file | Forensic analysis |

## Troubleshooting with Logs

### Issue: Data not being saved
1. Check for 404 errors: `grep "404" storage/logs/iclock.log`
2. Check for parsing errors: `grep "Invalid record format\|Error processing" storage/logs/iclock.log`
3. Verify SN is correct: `grep "SN=YOUR_DEVICE_SN" storage/logs/iclock.log`

### Issue: Device not registering
1. Check registry logs: `grep "DEVICE REGISTRY" storage/logs/iclock.log`
2. Verify handshake: `grep "DEVICE HANDSHAKE" storage/logs/iclock.log`

### Issue: Wrong data format
1. View raw content preview: `grep "raw_content_preview" storage/logs/iclock.log`
2. Check line format issues: `grep "Invalid record format\|field_count" storage/logs/iclock.log`

## Log Cleanup

Logs are automatically rotated and kept for 30 days.

To manually clean old logs:
```bash
# Remove logs older than 30 days
find storage/logs/iclock.log* -mtime +30 -delete
```

## Configuration

Edit `config/logging.php` to adjust:
- **Log level**: Change `'level' => env('LOG_LEVEL', 'debug')`
- **Retention days**: Change `'days' => 30`
- **Log path**: Change `storage_path('logs/iclock.log')`

## Analyzing Data Patterns

### Check Average Records Per Upload
```bash
grep "Attendance records processed successfully" storage/logs/iclock.log | awk -F'"total_records":' '{sum+=$2; count++} END {print "Total uploads:", count; print "Total records:", sum; print "Avg per upload:", sum/count}'
```

### Find Uploads with Errors
```bash
grep "Error processing records\|Invalid record format" storage/logs/iclock.log
```

### Monitor Device Activity
```bash
grep "Device registered successfully\|Handshake response sent" storage/logs/iclock.log | tail -20
```