개요#
파일 전송 작업과 기기 상태 변화를 Prometheus로 전송하여 모니터링하려면 Prometheus 연동을 설정할 수 있습니다.
Prometheus는 기본적으로 대상을 수집(Pull)하는 방식이지만, 본 연동은 Prometheus의 Remote Write Receiver로 데이터를 전송(Push)하는 방식입니다.
연동을 완료하면 전송이 시작(Transfer Started), 완료(Transfer Completed) 되거나 기기가 연결(Device Connected), 해제(Device Disconnected) 되는 등 지정한 이벤트가 발생할 때마다 Prometheus로 데이터가 전송됩니다.
전체 과정은 ① Prometheus Remote Write Receiver 준비 → ② 제품에서 연동 설정 두 단계로 진행됩니다.
준비 사항#
시작하기 전에 다음 사항을 확인하세요.
| 항목 | 설명 |
|---|---|
| Prometheus 서버 | Remote Write Receiver를 활성화할 수 있는 Prometheus 서버와 관리 권한이 필요합니다. |
| Prometheus Endpoint | 데이터를 수신할 Prometheus Endpoint(기본 포트 9090)를 확인합니다. |
| 네트워크 | 제품이 설치된 환경에서 Prometheus Endpoint(기본 9090)로 네트워크 접근이 가능해야 합니다. |
Prometheus Remote Write Receiver 준비#
제품이 Prometheus로 데이터를 전송하려면 Remote Write Receiver를 활성화하고 Endpoint 및 인증 정보를 확인합니다.
Step 1. Remote Write Receiver 활성화#
Prometheus를 --web.enable-remote-write-receiver 옵션과 함께 실행합니다.
Remote Write Receiver의 수신 경로는 다음과 같습니다.
/api/v1/writeℹ️ 이 기능이 활성화되지 않은 경우 데이터 전송 시
404 Not Found오류와 함께 remote write receiver needs to be enabled 메시지가 표시됩니다.
Step 2. Endpoint 및 인증 정보 확인#
Prometheus Endpoint를 확인합니다.
예)
http://localhost:9090인증이 필요한 경우 리버스 프록시(nginx 등) 또는 Prometheus 웹 설정에서 Bearer Token 인증을 구성하고 해당 Token을 준비합니다.
내부망에서 인증 없이 사용하는 경우 Auth Token은 입력하지 않아도 됩니다.
ℹ️ Auth Token은 비밀번호와 동일한 권한을 가지므로 공개 저장소나 외부 문서에 노출되지 않도록 주의합니다.
확인 사항#
- ✔ Remote Write Receiver가 활성화되었습니다.
- ✔ Prometheus Endpoint를 확인했습니다.
- ✔ 필요한 경우 Auth Token을 준비했습니다.
Prometheus 연동 설정#
확인한 Endpoint와 인증 정보를 제품에 입력합니다.
Monitoring 설정 창을 열면 아래와 같은 화면이 표시됩니다.
Step 1. Prometheus Endpoint 입력#
Prometheus Endpoint 항목에 Endpoint를 입력합니다.
예)
http://localhost:9090Step 2. Auth Token 입력#
인증을 사용하는 경우 Auth Token을 입력합니다.
인증을 사용하지 않는 경우에는 비워 둡니다.
Step 3. 이벤트 선택#
Events 항목에서 모니터링할 이벤트를 선택합니다.
여러 개를 선택할 수 있으며 선택한 이벤트가 발생할 때만 Prometheus로 전송됩니다.
| 이벤트 | 발생 시점 |
|---|---|
| Transfer Started | 전송 작업이 시작되었을 때 |
| Transfer Completed | 전송 작업이 정상적으로 완료되었을 때 |
| Transfer Paused | 전송 작업이 일시 중지되었을 때 |
| Transfer Recovered | 중단 또는 오류 후 전송이 자동 복구되어 재개되었을 때 |
| Device Connected | 기기가 연결되었을 때 |
| Device Disconnected | 기기 연결이 해제되었을 때 |
Step 4. 설정 저장#
입력을 완료한 후 Add를 클릭하여 연동을 저장합니다.
확인 사항#
- ✔ Prometheus Endpoint가 입력되었습니다.
- ✔ 필요한 경우 Auth Token이 입력되었습니다.
- ✔ 모니터링할 이벤트가 선택되었습니다.
연동 확인#
설정이 정상적으로 동작하는지 확인합니다.
Step 1. 테스트 이벤트 발생#
실제 전송 작업을 실행하거나 선택한 이벤트를 발생시킵니다.
Step 2. Prometheus 확인#
Prometheus UI에서 전송된 메트릭이 정상적으로 수집되었는지 확인합니다.
확인 사항#
- ✔ Prometheus에 메트릭이 수집되었습니다.
- ✔ 발생한 이벤트가 정상적으로 전달되었습니다.
설정 완료#
설정을 저장하면 연동이 적용됩니다.
이후 선택한 이벤트가 발생할 때마다 Prometheus로 데이터가 자동으로 전송됩니다.
문제 해결 (Troubleshooting)#
| 문제 | 확인 사항 |
|---|---|
| 데이터가 수집되지 않음 | Prometheus Endpoint와 Auth Token이 정확한지, 앞뒤 공백이나 누락이 없는지 확인 |
404 Not Found 오류가 발생함 |
Prometheus가 --web.enable-remote-write-receiver 옵션으로 실행되었는지 확인 |
| 인증 오류(401/403)가 발생함 | Auth Token이 올바른지, 리버스 프록시 또는 인증 설정과 일치하는지 확인 |
| 접속에 실패함 | Prometheus Endpoint와 포트(기본 9090)가 정확한지, 방화벽 또는 네트워크 정책에서 접근이 허용되는지 확인 |