개요#
파일 전송 작업과 기기 상태 변화를 Elasticsearch로 색인(Index)하여 모니터링하려면 Elastic Stack 연동을 설정할 수 있습니다.
연동을 완료하면 전송이 시작(Transfer Started), 완료(Transfer Completed) 되거나 기기가 연결(Device Connected), 해제(Device Disconnected) 되는 등 지정한 이벤트가 발생할 때마다 Elasticsearch로 이벤트가 색인되어 Kibana 등에서 모니터링할 수 있습니다.
전체 과정은 ① Elasticsearch 접속 정보 및 인증 준비 → ② 제품에서 연동 설정 두 단계로 진행됩니다.
준비 사항#
시작하기 전에 다음 사항을 확인하세요.
| 항목 | 설명 |
|---|---|
| Elastic Stack | 이벤트를 색인할 Elasticsearch 클러스터(및 Kibana)가 필요합니다. |
| 인증 정보 | API Key 또는 대상 인덱스에 쓰기 권한이 있는 사용자 계정이 필요합니다. |
| 네트워크 | 제품이 설치된 환경에서 Elasticsearch URL(기본 포트 9200)로 네트워크 접근이 가능해야 합니다. |
Elasticsearch 접속 정보 및 인증 준비#
Elasticsearch로 이벤트를 색인하려면 Elasticsearch URL과 인증 정보가 필요합니다.
인증은 API Key 또는 Username/Password 방식 중 하나를 사용합니다.
Step 1. Elasticsearch URL 확인#
이벤트를 색인할 Elasticsearch 클러스터의 접속 주소를 확인합니다.
자체 호스팅 환경에서는 일반적으로 https://localhost:9200 형식을 사용하며, 실제 환경에 맞는 호스트와 포트를 사용합니다.
Step 2. API Key 발급 (권장)#
Kibana에서 Stack Management → API Keys로 이동한 후 Create API Key를 클릭하여 API Key를 생성합니다.
이벤트를 색인하려면 대상 인덱스에 대한 쓰기 권한(create_doc 또는 write)이 필요하며, 인덱스를 자동 생성하려면 auto_configure 권한도 필요합니다.
생성된 API Key를 복사합니다.
ℹ️ API Key는 비밀번호와 동일한 권한을 가지므로 공개 저장소나 외부 문서에 노출되지 않도록 주의합니다. 유출된 경우 Kibana에서 해당 API Key를 무효화(Invalidate)합니다.
Step 3. 사용자 계정 준비 (선택)#
API Key 대신 사용자 인증을 사용하는 경우 대상 인덱스에 쓰기 권한이 있는 Username과 Password를 준비합니다.
API Key를 사용하는 경우에는 이 단계가 필요하지 않습니다.
확인 사항#
- ✔ Elasticsearch URL을 확인했습니다.
- ✔ API Key 또는 Username/Password를 준비했습니다.
Elastic Stack 연동 설정#
확인한 접속 정보와 인증 정보를 제품에 입력합니다.
Monitoring 설정 창을 열면 아래와 같은 화면이 표시됩니다.
Step 1. Elasticsearch URL 입력#
Elasticsearch URL 항목에 확인한 접속 주소를 입력합니다.
예)
https://localhost:9200Step 2. 인증 정보 입력#
사용할 인증 방식에 따라 다음 중 하나를 입력합니다.
- API Key 방식
- API Key 항목에 발급한 API Key를 입력합니다.
- Username / Password 방식
- Username과 Password를 입력합니다.
두 인증 방식 중 하나만 사용합니다.
Step 3. 이벤트 선택#
Events 항목에서 모니터링할 이벤트를 선택합니다.
여러 개를 선택할 수 있으며 선택한 이벤트가 발생할 때만 Elasticsearch에 색인됩니다.
| 이벤트 | 발생 시점 |
|---|---|
| Transfer Started | 전송 작업이 시작되었을 때 |
| Transfer Completed | 전송 작업이 정상적으로 완료되었을 때 |
| Transfer Paused | 전송 작업이 일시 중지되었을 때 |
| Transfer Recovered | 중단 또는 오류 후 전송이 자동 복구되어 재개되었을 때 |
| Device Connected | 기기가 연결되었을 때 |
| Device Disconnected | 기기 연결이 해제되었을 때 |
Step 4. 설정 저장#
입력을 완료한 후 Add를 클릭하여 연동을 저장합니다.
확인 사항#
- ✔ Elasticsearch URL이 입력되었습니다.
- ✔ 인증 정보(API Key 또는 Username/Password)가 입력되었습니다.
- ✔ 모니터링할 이벤트가 선택되었습니다.
연동 확인#
설정이 정상적으로 동작하는지 확인합니다.
Step 1. 테스트 이벤트 발생#
실제 전송 작업을 실행하거나 선택한 이벤트를 발생시킵니다.
Step 2. Elasticsearch 또는 Kibana 확인#
Kibana 또는 Elasticsearch 인덱스 조회를 통해 이벤트가 정상적으로 색인되었는지 확인합니다.
확인 사항#
- ✔ Elasticsearch에 이벤트가 색인되었습니다.
- ✔ 발생한 이벤트가 정상적으로 전달되었습니다.
설정 완료#
설정을 저장하면 연동이 적용됩니다.
이후 선택한 이벤트가 발생할 때마다 Elasticsearch로 이벤트가 자동으로 색인됩니다.
문제 해결 (Troubleshooting)#
| 문제 | 확인 사항 |
|---|---|
| 이벤트가 색인되지 않음 | Elasticsearch URL과 인증 정보(API Key 또는 Username/Password)가 정확한지, 앞뒤 공백이나 누락이 없는지 확인 |
| 인증 오류(401)가 발생함 | API Key가 무효화 또는 만료되지 않았는지, Username과 Password가 올바른지 확인 |
| 권한 오류(403)가 발생함 | 인증 정보에 대상 인덱스의 create_doc, write, auto_configure 권한이 있는지 확인 |
| TLS 인증서 오류가 발생함 | 자체 서명(Self-signed) 인증서를 사용하는 경우 인증서 신뢰 설정을 확인 |
| 접속에 실패함 | Elasticsearch URL과 포트(기본 9200)가 정확한지, 방화벽 또는 네트워크 정책에서 접근이 허용되는지 확인 |