Discord 알림을 Embed 형식으로 전환해 가시성 개선

Discord 알림 시스템의 메시지 가시성을 개선하기 위해 사이트 온보딩과 메타 체크 두 모듈의 알림을 일반 텍스트 포맷에서 discord_embed 형식으로 전환했다.

왜 Embed 형식이 필요했나

처음엔 Discord로 보내는 대부분의 알림이 단순 텍스트 메시지였다. 길이가 길어지거나 정보가 많아지면 읽기 힘들어지는 건 물론, 구조가 없어서 핵심 정보를 한눈에 파악하기 어려웠다. 특히 팀원들이 많은 Slack/Discord 채널을 모니터링하는 상황에서 중요한 알림이 흘러가기 쉬웠다.

Embed 형식은 제목, 본문, 필드, 컬러 등을 구조화된 방식으로 표현할 수 있어서:
- 색깔로 우선순위나 상태를 시각화 (성공/경고/에러)
- 필드로 정보를 정렬해서 읽기 쉽게
- 메시지가 더 "격식 있게" 보여서 중요도를 올려주는 효과

당연히 사용자 경험 관점에서 큰 차이가 난다.

영향받은 두 모듈

site_onboard.py와 meta-check.py 모두 내부 모니터링이나 운영 알림을 Discord로 전송하는 역할을 한다. 사이트 온보딩은 새로운 사이트 추가 같은 주요 이벤트를 알려주고, 메타 체크는 정기적으로 메타데이터 상태를 감시하다 문제가 생기면 보고한다. 이런 서로 다른 목적의 모듈들이 각각 비슷한 형태로 Discord 메시지를 만들고 있었고, 결국 포맷 개선이 필요했을 때 두 곳 모두 손을 봐야 했다.

이런 상황에서 나는 두 가지를 고민했다:

이번엔 두 모듈만 해당하고 향후 유사 모듈이 늘어날 가능성이 있어서, 공통 유틸로 빼내는 방향을 선택했다. 그렇게 해야 세 번째, 네 번째 모듈이 생길 때 "이전처럼 복붙하지 말고 유틸 써" 라고 리뷰할 수 있으니까.

리팩토링할 때 주의한 점

Discord Embed로 전환하면서 기존 메시지의 정보량이 줄어들지 않도록 신경 썼다. Embed의 필드 구조를 활용해 원래 텍스트에 있던 모든 정보를 담되, 더 명확하게 분류했다. 예를 들어:

# Before (일반 텍스트)
"site_onboard: 새 사이트 추가됨. 사이트명=ABC Corp, ID=12345, 상태=pending"

# After (discord_embed)
{
  "title": "새 사이트 온보딩 완료",
  "color": 3066993,
  "fields": [
    {"name": "사이트명", "value": "ABC Corp"},
    {"name": "사이트ID", "value": "12345"},
    {"name": "상태", "value": "pending"}
  ]
}

이렇게 구조화하니 정보 검색성도 올라가고, 향후 필드를 추가할 때도 깔끔하게 확장할 수 있는 기반이 생겼다.

배운 점과 다음 단계

이 작업을 통해 "포맷 개선"이 단순한 UI 개선을 넘어 팀 커뮤니케이션과 운영 효율성에 영향을 미친다는 걸 다시 한 번 느꼈다. 개발팀이 아닌 운영팀이나 사업팀도 Discord를 보고 중요한 의사결정을 하는데, 우리가 보내는 알림의 명확성이 그 결정 속도에 영향을 준다.

앞으로 비슷한 알림 포맷이 생길 때마다 "이번엔 처음부터 embed로" 하는 습관을 팀에 심어주고 싶다. 아직 일반 텍스트로 보내는 다른 모듈들도 있으니까.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.