FiveM Log Management System

An open-source, easily expandable logging foundation designed to provide deep structural insights for FiveM servers.

Features • Showcase • Architecture • Getting Started • Documentation • Contributing

---

Overview

The FiveM Log Management System provides administrators and developers with real-time insights into server events. Built around Elasticsearch for fast querying and Next.js for a modern admin dashboard, it serves as a solid, developer-friendly starting point that you can easily fork, expand, and tailor to your server's exact needs.

Stop relying on slow, unsearchable Discord webhook logs. Take control of your server's data with advanced filtering and weapon/vehicle statistics aggregations.

Features

• High-Throughput Ingestion: Custom Node.js backend handles thousands of events per second via optimized async bulk processing.
• Elasticsearch Powered: Full-text search, pagination, and millisecond-level aggregations over millions of rows.
• Secure OAuth2 Auth: Seamless staff login using Discord. Automated server-access resolution via Discord Guild membership.
• Rich Analytics: Automated statistical tracking of weapons used, vehicles spawned, and economic transactions.
• Modern Dashboard: Next.js App Router, shadcn/ui, and Tailwind CSS combined for a flawless, snappy user experience.
• Plug & Play Lua: A lightweight, non-blocking FiveM resource utilizing standard exports to drop straight into your existing frameworks (QBCore, ESX, or Custom).

Showcase

Browse the current UI and dashboard flow in the dedicated Showcase gallery.

Showcase Preview

Architecture

The system operates on an event-driven decoupled model optimized for speed:

1. Ingest (Node.js): A lightweight API that blindly accepts massive batches of JSON logs from your game server.
2. Storage (Elasticsearch): Acts as the timeseries database for billions of logs, capable of instant aggregations and full-text searches.
3. Storage (MySQL): Used exclusively for managing relational configuration data (like servers and users).
4. Dashboard (Next.js): The proxy layer. It verifies Discord credentials via MySQL before securely querying Elasticsearch on the user's behalf.

For a deeper dive into the system design, please review the full Architecture Overview.

Repository Structure

fivem-log-system/
├── backend/               # Node.js Ingest REST API & Elasticsearch mapping
├── dashboard/             # Next.js 14 Web Application (UI & Auth)
├── docs/                  # Extensive technical documentation
├── ARCHITECTURE.md        # Deep dive into distributed architecture
└── CONTRIBUTING.md        # Guidelines for pull requests and community

Getting Started

Getting your logging infrastructure up and running involves three main components: the database, the ingest backend, and the dashboard.

For the most comprehensive guide, please refer to our Full Setup Guide.

Quick Start Summary

1. Requirements

Ensure you have installed: Node.js 22+, MySQL 8.0+, and Elasticsearch 9.0+. You will also need a registered Discord Developer App for OAuth2.

2. Backend & Ingest Server

cd backend
npm install
cp env.example .env

# Edit .env with your configuration
npm run dev

3. Frontend Dashboard

cd dashboard
npm install
cp env.example .env.local

# Edit .env.local (Discord IDs, etc)
npm run dev

4. Lua Integration

Move the fivem-logging.lua into your FiveM Server's resource folder and add the appropriate API keys to your server.cfg. Read the Integration Docs for details.

Documentation

We believe in making powerful tools easy to use through exceptional documentation. Dive deeper into the specific areas of the exact systems you wish to explore:

• Architecture Overview: Understand the flow of data from game server to Elasticsearch.
• Installation & Setup: Step-by-step instructions from a blank VPS to a production-ready application.
• API Reference: Connect external tools or write your own custom log ingesters using the REST API.
• FiveM Integration: Implement Lua exports directly into your existing scripts.

Roadmap & Upcoming Features

Because this is a growing foundation, several advanced features are planned for future iterations to make it even more capable:

• Role-Based Access Control (RBAC): Granular channel and event access limits based on specific Discord Roles (so local-moderators can only see assigned logs).
• Expanded Aggregations: More detailed charts and graphs for economy tracking natively in the dashboard.
• Enhanced Lua Exports: Even more pre-configured exports for popular unified frameworks.

Contributing

This project is built by the community, for the community. Contributions, issues, and feature requests are always welcome!

Please read our Contributing Guidelines to learn how to open a PR, report issues, and follow our code structuring standards.

License

This project is open-sourced under the MIT License. You are free to modify, distribute, and utilize this software commercially.