discord-insight 0.0.1

A zero-config, real-time analytics dashboard for discord.py bots with MongoDB support.

📊 Discord Insight

Discord Insight is a zero-config, real-time analytics dashboard for discord.py bots. Drop one line of code into your bot, and instantly get a beautiful, local web dashboard tracking your bot's growth, errors, and performance with MongoDB Atlas persistence.

---

✨ Features

• 🚀 Zero-Configuration: No massive setups. Pass your bot object and MongoDB URI, and it just works.
• 📈 Real-Time Dashboard: A sleek, responsive (Dark/Light mode) web UI powered by Tailwind CSS and Chart.js.
• 👥 Daily Active Users (DAU): Accurately track how many unique users interact with your bot daily without leaking memory.
• 🔥 Command Heatmap & Distribution: Know exactly when and how your commands are being used.
• 🛡️ Live Error Tracebacks: Catch exceptions as they happen. View detailed error tracebacks right from your browser.
• 💻 System Metrics: Monitor your host machine's CPU usage, RAM utilization, and Discord API latency (Ping).
• ☁️ MongoDB Persistence: All stats survive bot restarts and host migrations thanks to MongoDB Atlas integration.

---

📦 Installation

Install discord-insight and python-dotenv (for secure credentials) via pip:

pip install discord-insight python-dotenv

Note: Ensure you are using Python 3.8+ and have discord.py installed.

---

🚀 Quick Start

1. Setup your .env file

Never hardcode your secrets! Create a .env file in your bot's root directory:

DISCORD_TOKEN=your_bot_token_here
MONGO_URI=mongodb+srv://username:[e-mail]/?retryWrites=true&w=majority

2. Add Insight to your Bot

import os
import discord
from discord.ext import commands
from dotenv import load_dotenv
from discord_insight import Insight

# Load secrets from .env
load_dotenv()
TOKEN = os.getenv("DISCORD_TOKEN")
MONGO_URL = os.getenv("MONGO_URI")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix="!", intents=intents)

# Initialize Discord Insight (This one line does all the heavy lifting!)
Insight(
    bot=bot,
    mongo_uri=MONGO_URL,
    dashboard=True,
    host="127.0.0.1",
    port=8080,
    password="admin"  # Protects your dashboard
)

@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}!")
    print("Dashboard live at: http://127.0.0.1:8080")

@bot.command()
async def ping(ctx):
    await ctx.send(f"Pong! {round(bot.latency * 1000)}ms")

bot.run(TOKEN)

3. View your Analytics

Run your bot, then open your web browser and navigate to:

👉 http://127.0.0.1:8080

(Login with the username admin and the password you set in the initialization).

---

⚙️ Configuration Options

The Insight class accepts the following parameters:

Parameter Type Default Description bot discord.Client Required Your discord.py bot instance. mongo_uri str Required Your MongoDB Atlas connection string. dashboard bool True Whether to launch the local web dashboard. host str "127.0.0.1" The IP address to host the dashboard on. Use "0.0.0.0" for external access. port int 8080 The port for the web dashboard. password str None Set a password to lock the dashboard behind Basic Auth.

---

🛠️ Troubleshooting Android/Termux Users

If you are hosting your bot on Termux (Android) and get a PermissionError: /etc/resolv.conf, you need to configure your DNS resolver before importing Insight. Add this to the very top of your main file:

import dns.resolver
dns.resolver.default_resolver = dns.resolver.Resolver(configure=False)
dns.resolver.default_resolver.nameservers = ['8.8.8.8', '8.8.4.4']

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

---

📝 License

This project is MIT licensed.