“복잡한 Zabbix 운영을 더 효율적으로 만들고 싶다면,
블로그의 핵심 내용을 집대성한 『Zabbix 엔터프라이즈 최적화 핸드북(PDF)』을 확인해보세요.”

https://jikimy.gumroad.com/l/zabbix-master

---

관련 글 :

모니터링 지표에 대한 고찰 : 다섯번째 대상 MongoDB

(베어메탈 / Kubernetes Pod 환경 완전 지원, Agent2 플러그인 기반)

Zabbix 7.4에서 MongoDB 모니터링은 더 이상 사용자 스크립트를 추가할 필요가 없다. Zabbix Agent2에 내장된 MongoDB 플러그인만 있으면 WiredTiger, Replication, Connection 등 대부분 지표를 자동으로 가져온다. 다만 실제 운영 환경은 두 가지로 나뉜다.

• ① MongoDB가 베어메탈(물리/VM) 서버에서 구동
• ② MongoDB가 Kubernetes Pod에서 Service를 통해 노출되어 구동

두 환경의 네트워크 구조가 완전히 다르기 때문에 Agent2 설정 방식도 각기 다르다. 이 글은 그 모든 차이를 Zabbix 7.4 기준으로 정리한 실무 가이드다.

---

1. 지원 버전

Zabbix

• Zabbix Server/Proxy 7.4 이상 (6.x에서도 동작은 가능하지만 플러그인 버전 호환성 고려)
• Zabbix Agent2 MongoDB 플러그인 활성화

MongoDB 엔진

• MongoDB 4.x ~ 7.x
  

---

✅ ReplicaSet 모니터링을 위한 Zabbix 구성 (Node 세션 기반)

ReplicaSet 환경을 Zabbix에서 정확하게 모니터링하려면 반드시 다음 두 요소가 충족되어야 한다.

• 각 노드의 성능 지표(WiredTiger, Cursor, Connections 등)
• ReplicaSet 전체 상태(rs.status 기반 종합 정보)

그러나 이 두 가지를 하나의 Host로 통합하는 것은 불가능하다.
따라서 ReplicaSet = Node 기준으로 각각 Host를 만들고 개별 성능 지표를 수집하는 방식이 정답이다.

※ 여기서 주의할 점은:
Zabbix는 ReplicaSet 전용 “Cluster 템플릿”을 제공하지 않는다.
(MongoDB cluster by Zabbix agent 2 템플릿은 샤딩 클러스터 mongos 전용이므로 ReplicaSet과 무관함)

즉, ReplicaSet을 모니터링할 때는 아래 가이드를 따르는 것이 가장 정확하다.

---

▶ Kubernetes 환경 vs Bare-Metal 환경의 구조적 차이

■ Kubernetes 환경에서는 가능한 이유

Kubernetes에서는 MongoDB Pod가 어느 노드에 떠 있든 간에,
Zabbix Agent2가 설치된 노드 OS에서 Service ClusterIP / LoadBalancer IP 를
통해 모든 MongoDB Pod에 접근할 수 있다.

즉:

• Agent2 = host node
• MongoDB = Pod
• 통신 = CNI 네트워크가 자동 보장

➡ 그래서 ReplicaSet이라도 Agent2 내에서 여러 Session을 구성하여 모니터링하는 것이 가능하다.

---

■ Bare-Metal 환경에서는 노드마다 Agent2를
설치하는 것이 정석

반면 물리 서버(또는 VM) 기반 ReplicaSet 구성에서는 구조가 다르다.

mongo01 서버 ↔ mongo01의 Agent2  
mongo02 서버 ↔ mongo02의 Agent2  
mongo03 서버 ↔ mongo03의 Agent2

각 MongoDB는 해당 서버에 설치된 Agent2와 1:1이어야 하며,
다른 서버의 MongoDB로 Session을 구성해도 성능 지표를 완전히 수집하는데
어려움이 있을 수 있다.

➡ 따라서 Bare-Metal ReplicaSet에서는
모든 노드에 Agent2를 설치하는 것이 올바른 방법이며, 권고하는 바이다

---

▶ Agent2의 mongodb.conf — 세션(Name Session) 정의

ReplicaSet의 각 노드로 접근하기 위한 세션을 이렇게 구성한다.

■ ReplicaSet 3노드 세션 구성

Plugins.Mongodb.Sessions.rs01.Uri=tcp://mongo01_IP:27017
Plugins.Mongodb.Sessions.rs01.User=zbx_monitor
Plugins.Mongodb.Sessions.rs01.Password=<password>

Plugins.Mongodb.Sessions.rs02.Uri=tcp://mongo02_IP:27017
Plugins.Mongodb.Sessions.rs02.User=zbx_monitor
Plugins.Mongodb.Sessions.rs02.Password=<password>

Plugins.Mongodb.Sessions.rs03.Uri=tcp://mongo03_IP:27017
Plugins.Mongodb.Sessions.rs03.User=zbx_monitor
Plugins.Mongodb.Sessions.rs03.Password=<password>

➡ 여기까지가 ReplicaSet 환경에서 필요한 전부다.

---

▶ Zabbix Web UI — Host 구성

■ ReplicaSet 개별 노드 모니터링 Host 3개

ReplicaSet의 각 노드는 독립된 Host로 등록해야 한다.

Host	설정할 매크로
mongo01	{$MONGODB.CONNSTRING}=rs01
mongo02	{$MONGODB.CONNSTRING}=rs02
mongo03	{$MONGODB.CONNSTRING}=rs03

각 Host에는 다음 템플릿을 적용한다:

MongoDB node by Zabbix agent 2

→ WiredTiger, Cursor, Cache, Connection 등 노드 단위 성능을 정확히 수집한다.

※ 환경별 주의사항

• Bare-Metal: 각 물리 서버에 Agent2가 반드시 있어야 함
• Kubernetes: Node OS에 설치된 Agent2 하나로 여러 Pod 접근 가능

---

▶ Cluster 템플릿은 언제 사용하는가?

ReplicaSet에서는 사용하지 않는다.

Cluster 템플릿의 용도는 다음 하나뿐이다:

몽고DB 샤딩 클러스터(mongos 기반)에서 전체 샤드 상태를 모니터링할 때만 사용한다.

즉:

• mongos 라우터에 적용
• mongos가 get_shards 명령으로 샤드 노드를 발견
• 발견된 mongod 노드에 Node 템플릿을 자동 연결

➡ ReplicaSet에는 mongos가 없으므로 Cluster 템플릿을 적용할 수 없다.

정리하면:

ReplicaSet = Node 템플릿만 사용
Sharded Cluster = Cluster + Node 템플릿 조합 사용

이게 Zabbix 공식 구조에 맞는 올바른 방식이다.

---

▶ 전체 구성 요약

[mongo01] —— Node 템플릿 —— rs01
[mongo02] —— Node 템플릿 —— rs02
[mongo03] —— Node 템플릿 —— rs03

ReplicaSet 모니터링 핵심:

• Node 템플릿 = 각 노드 성능 지표
• Kubernetes = Agent2 하나로 여러 Session 접근 가능
• Bare-Metal = 노드별 Agent2 필요
• Cluster 템플릿 = ReplicaSet과 무관 (샤딩 전용)

---

▶ 다음 설치 가이드 방향(Standalone 기준)

이후 이어지는 실전 가이드에서는
ReplicaSet이 아닌 단일 MongoDB 노드를 기준으로 설정 방법을 설명한다.
여러 노드를 기준으로 설정하고자 한다면 이 가이드를 바탕으로 조금의 응용만
필요할 뿐이다.

• 템플릿: MongoDB Node by Zabbix agent 2
• URI: 단일 노드
• Session: 하나만 구성

---

2. MongoDB 모니터링 계정 생성 (공통)

MongoDB 인증을 사용하는 경우 모니터링 전용 사용자를 만들어 두는 것이 좋다. 아래는 최소 권한 예시다.

- admin 전환
use admin

- 모니터링 계정 생성
db.createUser({ user: "zbx_monitor", pwd: "<password>", roles: [ { role: "clusterMonitor", db: "admin" }, { role: "read", db: "local" } ] })

- 계정 정상적으로 생성되었는지 확인
db.getUser("zbx_monitor")      

clusterMonitor 권한은 상태 정보를 조회하는 데 필요하고, read 권한은 local DB의 복제 지연 정보를 읽는 데 사용된다.

---

3. Agent2 플러그인 설치 경로 확인

Agent2 측에 MongoDB 플러그인이 미리 설치·활성화되어 있어야 하며, 정상적으로
설치가 되었다면 아래와 같은 경로에 설치 된다.

---

4. 템플릿 매크로 방식 vs Agent2 세션 방식

두 방식 모두 동작하지만 성격이 다르다

✔ 템플릿 매크로 방식

Zabbix UI에서 매크로를 정의하여 Agent2 설정을 덮어쓰는 방식이다.

{$MONGODB.CONNSTRING} = tcp://192.168.117.5:27017
{$MONGODB.USER}      = zbx_monitor
{$MONGODB.PASSWORD}  = <password>

장점: 플러그인 설정 파일을 수정하지 않고도 UI에서 빠르게 수정할 수 있다.
단점: 암호가 Zabbix UI에 노출된다.

✔ Agent2 세션 방식 (권장)

대상 호스트에 Zabbix Agent2를 설치하고 mongodb.conf 파일을 수정한 뒤 재시작한다.

# 기본값
Plugins.Mongodb.Sessions.*.Uri=
Plugins.Mongodb.Sessions.*.User=
Plugins.Mongodb.Sessions.*.Password=

# 수정값
Plugins.Mongodb.Sessions.example_mongodb.Uri=tcp://192.168.117.5:27017
Plugins.Mongodb.Sessions.example_mongodb.User=zbx_monitor
Plugins.Mongodb.Sessions.example_mongodb.Password=<password>

Zabbix 웹 UI의 템플릿 매크로에는 아래와 같이 세션 이름을 넣으면 된다.

{$MONGODB.CONNSTRING} = example_mongodb

플러그인 설정 팁

• (A 방식) Default 값만 사용하는 단일 MongoDB 모니터링
  MongoDB 인스턴스가 한 개뿐이면 Plugins.Mongodb.Default 섹션을 사용하면 된다.
  Plugins.Mongodb.Default.Uri=tcp://192.168.117.5:27017 Plugins.Mongodb.Default.User=zbx_monitor Plugins.Mongodb.Default.Password=<password>
  Zabbix 웹에서 매크로는 비워두거나 기본값으로 둔다.
• (B 방식) Sessions 구조를 사용하는 멀티 인스턴스 모니터링 (단일 인스턴스도 가능)
  여러 DB 또는 여러 세션을 모니터링할 때 적합하다. 각 세션별로 이름을 주고 위와 같이 정의하면 된다.
  
  

---

5. Kubernetes Pod MongoDB 모니터링 구성

Agent2는 호스트(OS)에서 실행되고 MongoDB는 Pod 안에서 실행되는 환경을 고려해야 한다. Pod의 ClusterIP는 외부에서 접근할 수 없으므로 반드시 Service(NodePort 또는 LoadBalancer)를 통해 접근한다.

가장 실무적인 방법은 다음과 같다.

LoadBalancer External IP 기반 모니터링

● K8s 구조

Agent2 (Host) → Service External IP → MongoDB Pod

● External IP 예

192.168.117.90:27017

● mongodb.conf 설정

Plugins.Mongodb.Sessions.K8s.Uri=tcp://192.168.117.90:27017
Plugins.Mongodb.Sessions.K8s.User=zbx_monitor
Plugins.Mongodb.Sessions.K8s.Password=<password>

Zabbix 웹 UI의 매크로:

{$MONGODB.CONNSTRING} = K8s

---

6. 지표 : 주요 수집 아이템

MongoDB 플러그인은 다음과 같은 핵심 지표를 수집한다.

• Connections
  현재 연결 수, 최대 연결 대비 사용률 (트리거 매크로: {$MONGODB.CONNS.PCT.USED.MAX.WARN})
• Cursors
  열린 커서 수, 타임아웃 비율 ({$MONGODB.CURSOR.TIMEOUT.MAX.WARN}, {$MONGODB.CURSOR.OPEN.MAX.WARN})
• WiredTiger
  읽기/쓰기 티켓 가용성 ({$MONGODB.WIRED_TIGER.TICKETS.AVAILABLE.MIN.WARN})

---

7. 트러블슈팅 체크리스트

1) 베어메탈 환경

• URI 오타 – tcp://를 빼먹거나 포트를 잘못 지정하면 연결 실패의 주된 원인이 된다.
• 바인드 주소 – MongoDB 설정(mongod.conf)에서 bindIp가 127.0.0.1로 되어 있으면 외부 접근이 불가능하다. 0.0.0.0으로 변경하거나 필요한 IP를 추가한다.
• Firewall – OS 방화벽 또는 클라우드 보안 그룹에서 27017 포트가 차단되어 있는지 확인한다.
• SELinux/AppArmor 차단 – 보안 모듈이 Agent2의 접속을 막을 수 있으므로 해당 정책을 조정 또는 비활성화

2) Kubernetes 환경

• NetworkPolicy 차단 – 네임스페이스에 적용된 NetworkPolicy가 Zabbix Agent2로부터 들어오는 Ingress 트래픽을 허용하는지 확인한다.
• Service External IP 변경 – LoadBalancer를 재생성하거나 노드를 재시작하면 External IP가 변경될 수 있다. Zabbix 호스트 매크로도 함께 수정해야 한다
• Readiness Probe 실패 – MongoDB Pod가 Running 상태라도 Readiness Probe가 실패하면 Service의 Endpoints 목록에서 제외되어 접근이 차단된다.

---

8. 결론

Zabbix 7.4 환경에서 MongoDB 모니터링은 다음 한 문장으로 요약할 수 있다.

Agent2가 MongoDB와 연결할 수 있는 URI만 정확히 지정하면, 나머지는 모두 자동으로 해결된다.

• 플러그인 경로는 /etc/zabbix/zabbix_agent2.d/plugins.d/
• UserParameter는 6.0 이후 필요 없다
• K8S Pod 모니터링 시 External IP 를 이용하면 된다.
• 세션 방식이 가장 안정적·보안적·확장성이 좋다

운영 환경이 베어메탈이든 Pod든 중요하지 않다. URI 구성이 정확하다면 Zabbix는 환경에 구애받지 않는 강력한 MongoDB 모니터링 플랫폼이 될 것이다.

🛠 마지막 수정일: 2025.12.09