85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# Logging & debugging errors
|
|
|
|
## Where errors are logged
|
|
|
|
### 1. **Log file** (JSON lines)
|
|
|
|
- **Path:** `LOG_FILE` env var, or **`/tmp/mis-control-tower.log`** if unset.
|
|
- **Contents:** JSON lines for `requireSession.error`, `getOverviewData.error`, `OverviewPage.getOverviewData.error`, plus any `logLine(...)` usage (e.g. health, signup).
|
|
|
|
**View recent entries:**
|
|
```bash
|
|
tail -f /tmp/mis-control-tower.log
|
|
```
|
|
|
|
**Or with a custom path:**
|
|
```bashls -la
|
|
export LOG_FILE=/var/log/mis-control-tower.log
|
|
# then start the app; tail that path
|
|
tail -f /var/log/mis-control-tower.log
|
|
```
|
|
|
|
### 2. **Process stdout / stderr**
|
|
|
|
- **`console.error`** and **`console.log`** go to the process that runs Next.js.
|
|
- **Dev:** terminal where you run `npm run dev`.
|
|
- **Production:** PM2 logs (`pm2 logs`), Docker (`docker logs ...`), systemd (`journalctl -u your-service -f`), etc.
|
|
|
|
### 3. **Debug logs API** (optional)
|
|
|
|
- **URL:** `GET /api/debug/logs?key=YOUR_DEBUG_LOGS_KEY`
|
|
- **Purpose:** Returns the last 100 lines of the log file as JSON.
|
|
- **Setup:** Add to `.env`:
|
|
```
|
|
DEBUG_LOGS_KEY=your-secret-string
|
|
```
|
|
- **Usage:**
|
|
`curl "https://mis.maliountech.com.mx/api/debug/logs?key=your-secret-string"`
|
|
- If `DEBUG_LOGS_KEY` is unset or the `key` param is wrong, the route returns 401.
|
|
|
|
## Error events we log
|
|
|
|
| Event | When |
|
|
|-------|------|
|
|
| `requireSession.error` | Session lookup (cookies / DB) fails |
|
|
| `getOverviewData.error` | Overview data fetch (DB) fails |
|
|
| `OverviewPage.getOverviewData.error` | Overview page catch-around fetch fails |
|
|
|
|
Each includes `message` and `stack` when available.
|
|
|
|
## Quick checks when you see "Internal Server Error"
|
|
|
|
1. **Tail the log file:**
|
|
`tail -f /tmp/mis-control-tower.log`
|
|
(or `$LOG_FILE` if you set it.)
|
|
|
|
2. **Check process logs:**
|
|
Wherever `next start` or `npm run dev` runs (PM2, Docker, systemd). Look for `[requireSession]`, `[getOverviewData]`, `[OverviewPage]`, or `[middleware]`.
|
|
|
|
3. **Call the debug API** (if configured):
|
|
`curl "https://your-domain/api/debug/logs?key=YOUR_DEBUG_LOGS_KEY"`
|
|
and inspect the `entries` array for recent errors.
|
|
|
|
## KPI quality trace (Node-RED vs processing)
|
|
|
|
Use this when `Quality` is shown as `0` and you need to see exactly what was received and saved.
|
|
|
|
1. Enable trace logging:
|
|
`TRACE_KPI_INGEST=1`
|
|
|
|
2. Send KPI payloads as usual from Node-RED.
|
|
|
|
3. Inspect logs:
|
|
`tail -f /tmp/mis-control-tower.log`
|
|
or:
|
|
`curl "https://your-domain/api/debug/logs?key=YOUR_DEBUG_LOGS_KEY"`
|
|
|
|
4. Look for event `ingest.kpi.trace`, which includes:
|
|
`trace.rawQualityCandidates` (raw payload values found at multiple paths),
|
|
`trace.normalizedQuality` (post-normalization),
|
|
`trace.persistedQuality` (value written to DB).
|
|
|
|
Optional one-shot trace without env var:
|
|
- Send header `x-debug-ingest: 1` on a KPI request.
|
|
- The response will include a `trace` object with the same quality details.
|