Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse is a real-time analytics platform that relies on a distributed architecture involving an API layer, background workers, Redis-backed queues, and a PostgreSQL database. Troubleshooting within Glimpse focuses on identifying points of failure in the event ingestion pipeline, geolocation resolution, and container orchestration.
This guide provides technical insights into diagnosing issues across the stack, from frontend SDK event firing to backend worker processing. For a high-level view of the system, refer to the Technical Architecture section.
Sources: PROJECT_OUTLINE.md:3-8, README.md:162-170
Service Connectivity and Health
The first step in troubleshooting is verifying the status of the core services. The API provides a health check endpoint and a debug route specifically for testing error reporting.
Health Check Endpoints
The Hono-based API includes a dedicated route to verify the service is running.
| Endpoint | Method | Purpose |
|---|---|---|
/check | GET | Returns { status: "ok" } to verify API availability. |
/ | GET | Returns client IP and headers to debug IP extraction. |
/debug-sentry | GET | Explicitly throws an error to test Sentry integration. |
Sources: app/api/app.ts:22-38, PROJECT_OUTLINE.md:195-207
Environment and Infrastructure
Common issues often stem from misconfigured environment variables or service dependencies (PostgreSQL and Redis).
This diagram illustrates the standard decision flow for diagnosing ingestion failures.
Sources: README.md:43-52, docker/docker-compose.yml:1-35
Event Pipeline Failures
Issues in the event pipeline typically occur between the ingestion at the API level and the processing within the eventWorker.
Geolocation Resolution Issues
If events are captured but location data (Country, City, Lat/Lon) is missing, the issue likely resides in the MaxMind GeoIP configuration. The system requires a valid GEOLITE_LICENSE_KEY and a local database update.
# Verify GeoIP database status
cd node_modules/geoip-lite && npm run updatedb license_key=YOUR_MAXMIND_LICENSE_KEY
Sources: README.md:126-135, app/workers/eventWorker.ts:98-106
Worker Processing and Buffering
The eventWorker utilizes an in-memory buffer (eventBuffer) to batch writes to the database. If the worker crashes before a flush, or if the flush interval is too high, data loss may occur.
| Component | Default Value | Troubleshooting Action |
|---|---|---|
MAX_BUFFER_SIZE | 100 events | Lower this value if DB writes are timing out. |
BUFFER_FLUSH_INTERVAL | 1000ms | Decrease to reduce latency in data visibility. |
Session TTL | 300s | Increase if sessions are expiring too quickly in Redis. |
Sources: app/workers/eventWorker.ts:21-23, PROJECT_OUTLINE.md:108-112
Database and Schema Errors
The database uses Prisma for migrations. Discrepancies between the TypeScript schemas and the actual PostgreSQL tables will cause the worker to fail during the flushEventBuffer operation.
Common Migration Commands
If the application logs show SQL errors or missing columns, re-running migrations is necessary:
bun run prisma:migrate: Applies pending migrations in development.bun run prisma:generate: Updates the Prisma Client to match the schema.
Sources: README.md:100-110, package.json:11-14
This sequence shows the interaction between the worker and the persistence layers, highlighting potential failure points in the batching process.
Sources: app/workers/eventWorker.ts:32-65, PROJECT_OUTLINE.md:144-165
Connectivity and CORS
The API is configured with a permissive CORS policy to allow events from various origins. If the frontend SDK fails to send events, verify the allowMethods and allowHeaders in the API initialization.
// app/api/app.ts:11-19
app.use("*", cors({
origin: (origin) => origin || "*",
allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
allowHeaders: ["Content-Type", "Authorization", "Accept"],
maxAge: 86400,
credentials: false,
}));
Sources: app/api/app.ts:11-19
Summary
Troubleshooting Glimpse requires monitoring the log output of individual Docker containers and verifying service connectivity to Redis and PostgreSQL. Key focus areas include the MaxMind GeoIP license for geolocation accuracy and the BullMQ worker status for reliable event ingestion. Using the test/fire_event.sh script is the recommended method for validating that the entire pipeline—from API to DB—is functioning correctly.
Sources: PROJECT_OUTLINE.md:181-190, README.md:139-146