Monitoring Timetagger with Vigilmon

Timetagger is a self-hosted time tracking tool built in Python with an ASGI backend, offering a web-based interface and a full REST API for syncing time records across devices. Because it runs as a single-process ASGI server, a crash takes down every feature simultaneously — the web UI, the sync API, and the report generation service all go dark at once. Vigilmon gives you fast, lightweight monitoring across all Timetagger's critical endpoints so you're alerted the moment the service goes down or degrades.

What You'll Set Up

• HTTP uptime monitor for the Timetagger web server (port 0080)
• REST API response time monitoring
• Time record synchronization endpoint health check
• Tag management endpoint monitoring
• Report generation service health probe
• User authentication endpoint monitoring

Prerequisites

• Timetagger running and accessible (typically on port 0080 or behind a reverse proxy)
• A free Vigilmon account

Step 1: Monitor the Timetagger Web Server

Timetagger's web interface is the primary user-facing surface. A simple uptime check confirms that the ASGI process is alive and the web server is serving pages.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Timetagger URL: https://timetagger.yourdomain.com (or http://your-server:8080).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If you run Timetagger behind nginx or Caddy, monitor the public URL to catch reverse proxy failures in addition to application crashes.

Step 2: Monitor the REST API

Timetagger's REST API handles all data operations — time record creation, updates, deletions, and sync. The API is what mobile apps and browser sync use; an API failure makes the app read-only at best, completely broken at worst.

Timetagger exposes API routes under /api/v2/. A lightweight availability probe:

1. URL: https://timetagger.yourdomain.com/api/v2/
2. Type: HTTP / HTTPS
3. Expected HTTP status: 200 or 404 (the API root may not have a handler, but the server should respond without a 500)
4. Check interval: 1 minute

For a more targeted check, probe the auth status endpoint which requires no credentials:

https://timetagger.yourdomain.com/api/v2/webtoken

A 401 or 403 response proves the API router is healthy. A 500 signals a server-side crash.

Step 3: Monitor the Time Record Synchronization Service

Timetagger's core feature is syncing time records across browser sessions and devices. The sync endpoint at /api/v2/records is hit every few minutes by active users. Sync failures mean lost time entries.

Add a monitor:

1. URL: https://timetagger.yourdomain.com/api/v2/records
2. Type: HTTP / HTTPS
3. Expected HTTP status: 401 (Unauthorized — proves the route exists and handles requests)
4. Check interval: 1 minute

If your Timetagger instance is publicly accessible and you want a more thorough check, you can use a monitoring API token and probe with authentication:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://timetagger.yourdomain.com/api/v2/records?timerange=1d"

Expected response: a JSON object with a records array and an HTTP 200.

Step 4: Monitor Tag Management

Timetagger uses tags as the primary organization mechanism for time entries. The tag endpoint handles both reading existing tags and creating new ones:

GET /api/v2/tags

Add a monitor:

1. URL: https://timetagger.yourdomain.com/api/v2/tags
2. Type: HTTP / HTTPS
3. Expected HTTP status: 401
4. Check interval: 2 minutes

Tag management failures are less immediately critical than sync failures, but they break the ability to create new time categories.

Step 5: Monitor Report Generation

Timetagger's report generation aggregates time records by tag, project, or date range. This is typically a synchronous request that hits the database and performs calculations server-side. Heavy reports can reveal performance degradation before it affects regular usage.

Add a monitor that probes the report endpoint:

1. URL: https://timetagger.yourdomain.com/api/v2/report
2. Type: HTTP / HTTPS
3. Expected HTTP status: 401
4. Check interval: 5 minutes

Configure a response time alert in Vigilmon: if the report endpoint takes more than 5 seconds to respond (even with a 401), it may signal database performance issues or memory pressure on the ASGI process.

Step 6: Monitor User Authentication

Timetagger uses web tokens for authentication. The authentication endpoint is the entry point for all user sessions — if it fails, no one can log in even if the rest of the API is healthy.

Add a monitor:

1. URL: https://timetagger.yourdomain.com/api/v2/webtoken
2. Type: HTTP / HTTPS
3. Expected HTTP status: 401 (expected when called without credentials)
4. Check interval: 2 minutes

You can also monitor the login page directly:

https://timetagger.yourdomain.com/login

Expect HTTP 200. A redirect or error here means the login flow is broken.

Step 7: Add a Custom Health Endpoint (Optional)

Timetagger is built in Python (ASGI with itemdb for storage). You can add a custom health endpoint by extending the ASGI app:

# In your timetagger app entrypoint or middleware
from asgineer import request_handler

@request_handler
async def health_handler(request):
    try:
        # Check database file accessibility
        import os
        db_path = os.environ.get("TIMETAGGER_DB_PATH", "~/.timetagger/db.db")
        db_ok = os.path.exists(os.path.expanduser(db_path))
    except Exception:
        db_ok = False

    status = "ok" if db_ok else "error"
    code = 200 if db_ok else 503
    return code, {"Content-Type": "application/json"}, f'{{"status": "{status}"}}'

Then mount it at /health and monitor it:

1. URL: https://timetagger.yourdomain.com/health
2. Expected HTTP status: 200
3. Check interval: 1 minute

Step 8: Configure Alerting

Configure Vigilmon alert channels to get notified immediately when Timetagger has issues:

1. Go to Alert Channels → add email, Slack, or a webhook.
2. For the web server and sync monitors: alert on 1 failure — sync loss is immediate data loss risk.
3. For the report and tag monitors: use 2 consecutive failures to avoid noise from transient hiccups.
4. For the auth endpoint: alert on 1 failure — a broken auth endpoint locks everyone out.
5. Enable response time alerts on the report endpoint with a threshold of 5 seconds.

Monitoring Checklist

| Service | Monitor Type | Check Interval | Alert Threshold | |---|---|---|---| | Timetagger web server | HTTP | 1 min | 1 failure | | REST API availability | HTTP | 1 min | 1 failure | | Time record sync endpoint | HTTP | 1 min | 1 failure | | Tag management endpoint | HTTP | 2 min | 2 failures | | Report generation endpoint | HTTP | 5 min | 2 failures + slow response | | Authentication endpoint | HTTP | 2 min | 1 failure | | Custom health endpoint | HTTP | 1 min | 1 failure |

Conclusion

Timetagger's simplicity is its strength — but that same simplicity means a single process crash takes everything down at once. With Vigilmon monitoring the web server, every API endpoint, and the authentication layer, you'll know about outages within a minute and can get the ASGI process restarted before anyone's time entry is lost. Set up these monitors in under 15 minutes and let Vigilmon watch Timetagger around the clock.

Start monitoring Timetagger with Vigilmon →