디스코드 봇 만들기#25봇이 죽지 않게! 에러 핸들링·로깅 체계 잡기 (파이썬 예제)

DISCORD_TOKEN=여기에_봇_토큰
ERROR_LOG_CHANNEL_ID=123456789012345678

# utils/logger.py
import logging
from logging.handlers import RotatingFileHandler
from pathlib import Path

LOG_DIR = Path("logs")
LOG_DIR.mkdir(exist_ok=True)

def setup_logger() -> None:
    fmt = logging.Formatter(
        "[{asctime}] [{levelname:<8}] {name}: {message}",
        "%Y-%m-%d %H:%M:%S",
        style="{",
    )

    # 1) 파일 저장 (5MB씩 최대 5개 보관 후 오래된 것부터 삭제)
    file_handler = RotatingFileHandler(
        LOG_DIR / "bot.log",
        maxBytes=5 * 1024 * 1024,
        backupCount=5,
        encoding="utf-8",
    )
    file_handler.setFormatter(fmt)

    # 2) 터미널 출력
    stream_handler = logging.StreamHandler()
    stream_handler.setFormatter(fmt)

    root = logging.getLogger()
    root.setLevel(logging.INFO)
    root.addHandler(file_handler)
    root.addHandler(stream_handler)

    # discord 라이브러리 내부 로그는 조금 조용히
    logging.getLogger("discord.http").setLevel(logging.WARNING)

# cogs/error_handler.py
import logging
import os
import traceback

import discord
from discord import app_commands
from discord.ext import commands

log = logging.getLogger(__name__)

class ErrorHandler(commands.Cog):
    def __init__(self, bot: commands.Bot):
        self.bot = bot
        # 기존 핸들러를 백업해두고 우리 것으로 교체
        self._old_tree_error = bot.tree.on_error
        bot.tree.on_error = self.on_app_command_error

    async def cog_unload(self) -> None:
        # Cog를 언로드하면 원래 핸들러로 되돌려요 (핫리로드 대비)
        self.bot.tree.on_error = self._old_tree_error

    async def reply(self, interaction: discord.Interaction, msg: str, color: discord.Color):
        embed = discord.Embed(description=msg, color=color)
        # 이미 응답했거나 defer 했으면 followup으로 보내야 해요
        if interaction.response.is_done():
            await interaction.followup.send(embed=embed, ephemeral=True)
        else:
            await interaction.response.send_message(embed=embed, ephemeral=True)

    async def on_app_command_error(
        self,
        interaction: discord.Interaction,
        error: app_commands.AppCommandError,
    ) -> None:
        # ── ① 사용자 잘못: 친절하게 안내만 하고 끝 ──
        if isinstance(error, app_commands.CommandOnCooldown):
            await self.reply(
                interaction,
                f"⏳ 너무 자주 쓰고 있어요! **{error.retry_after:.1f}초** 뒤에 다시 시도해주세요.",
                discord.Color.orange(),
            )
            return

        if isinstance(error, app_commands.MissingPermissions):
            perms = ", ".join(error.missing_permissions)
            await self.reply(
                interaction,
                f"🚫 이 명령어를 쓰려면 **{perms}** 권한이 필요해요.",
                discord.Color.orange(),
            )
            return

        if isinstance(error, app_commands.BotMissingPermissions):
            perms = ", ".join(error.missing_permissions)
            await self.reply(
                interaction,
                f"🤖 봇에게 **{perms}** 권한이 없어요. 서버 관리자에게 요청해주세요!",
                discord.Color.orange(),
            )
            return

        if isinstance(error, app_commands.CheckFailure):
            await self.reply(
                interaction,
                "🚫 이 명령어를 사용할 수 있는 조건이 아니에요.",
                discord.Color.orange(),
            )
            return

        # ── ② 내 코드 잘못: 사용자에겐 사과, 나에겐 상세 리포트 ──
        await self.reply(
            interaction,
            "⚠️ 처리 중 문제가 생겼어요. 관리자에게 자동으로 전달했습니다!",
            discord.Color.red(),
        )

        command_name = interaction.command.name if interaction.command else "알 수 없음"
        log.exception("슬래시 명령어 '%s' 실행 중 에러", command_name, exc_info=error)
        await self.report_to_admin(interaction, error, command_name)

    async def report_to_admin(self, interaction, error, command_name: str) -> None:
        channel_id = os.getenv("ERROR_LOG_CHANNEL_ID")
        if not channel_id:
            return

        channel = self.bot.get_channel(int(channel_id))
        if channel is None:
            return

        tb = "".join(
            traceback.format_exception(type(error), error, error.__traceback__)
        )
        # 디스코드 메시지는 2000자 제한! 코드블록 여백까지 감안해 잘라줍니다
        tb = tb[-1800:]

        embed = discord.Embed(
            title="🔥 명령어 실행 에러",
            description=f"```py\n{tb}\n```",
            color=discord.Color.red(),
            timestamp=discord.utils.utcnow(),
        )
        embed.add_field(name="명령어", value=f"`/{command_name}`", inline=True)
        embed.add_field(name="사용자", value=f"{interaction.user} (`{interaction.user.id}`)", inline=True)
        guild_name = interaction.guild.name if interaction.guild else "DM"
        embed.add_field(name="서버", value=guild_name, inline=True)

        await channel.send(embed=embed)

    # ── ③ 이벤트 리스너에서 난 에러도 잡기 ──
    @commands.Cog.listener()
    async def on_error(self, event_method: str, *args, **kwargs) -> None:
        log.exception("이벤트 '%s' 처리 중 에러", event_method)

async def setup(bot: commands.Bot) -> None:
    await bot.add_cog(ErrorHandler(bot))

# bot.py — discord.py 2.x (2.7 기준) / Python 3.10+
import asyncio
import logging
import os

import discord
from discord.ext import commands
from dotenv import load_dotenv

from utils.logger import setup_logger

load_dotenv()
setup_logger()
log = logging.getLogger(__name__)

INITIAL_COGS = [
    "cogs.error_handler",   # 가장 먼저 올려두는 게 안전해요
    # "cogs.poll",
    # "cogs.automod",
]

class ServerBot(commands.Bot):
    def __init__(self):
        intents = discord.Intents.default()
        intents.message_content = True
        intents.members = True
        super().__init__(command_prefix="!", intents=intents)

    async def setup_hook(self) -> None:
        for cog in INITIAL_COGS:
            try:
                await self.load_extension(cog)
                log.info("Cog 로드 완료: %s", cog)
            except Exception:
                log.exception("Cog 로드 실패: %s", cog)
        await self.tree.sync()

    async def on_ready(self):
        log.info("로그인 성공: %s (ID: %s)", self.user, self.user.id)

async def main():
    token = os.getenv("DISCORD_TOKEN")
    if not token:
        raise RuntimeError(".env에 DISCORD_TOKEN이 없어요!")

    async with ServerBot() as bot:
        await bot.start(token)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        log.info("봇을 종료합니다.")

# cogs/debug.py
from discord import app_commands
from discord.ext import commands

class Debug(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @app_commands.command(name="에러테스트", description="일부러 에러를 발생시켜요")
    async def error_test(self, interaction):
        raise ValueError("이건 테스트용 에러예요!")

    @app_commands.command(name="쿨다운테스트", description="쿨다운을 확인해요")
    @app_commands.checks.cooldown(1, 10.0)
    async def cooldown_test(self, interaction):
        await interaction.response.send_message("성공! 10초 뒤에 다시 써보세요.")

async def setup(bot):
    await bot.add_cog(Debug(bot))