외부 시스템 스트리밍

개요

Zabbix에서 아이템 값과 이벤트를 HTTP를 통해 외부 시스템으로 스트리밍할 수 있습니다(프로토콜 상세 참고).

태그 필터를 사용하여 아이템 값이나 이벤트의 일부만 스트리밍할 수 있습니다.

데이터 스트리밍은 두 가지 Zabbix 서버 프로세스 타입이 담당합니다: connector manager와 connector worker. Zabbix 내부 아이템 zabbix[connector_queue]를 사용하면 커넥터 큐에 대기 중인 값의 개수를 모니터링할 수 있습니다.

설정

외부 시스템으로 데이터 스트리밍을 설정하려면 다음 단계가 필요합니다:

1. Zabbix로부터 데이터를 수신할 원격 시스템을 준비합니다. 이를 위해 다음과 같은 도구를 사용할 수 있습니다:

• 수신한 정보를 events.ndjson과 history.ndjson 파일에 기록하는 간단한 receiver 예제.
• Kafka connector for Zabbix server - Zabbix 서버의 아이템 값과 이벤트를 Kafka 브로커로 전달하도록 설계된 Go로 작성된 경량 서버.

2. zabbix_server.conf의 StartConnectors 파라미터를 조정하여 Zabbix에서 필요한 커넥터 워커 수를 설정합니다. 커넥터 워커 수는 Zabbix 프론트엔드에서 설정한 커넥터 개수와 일치해야 하며(동시 세션이 1개보다 많은 경우 그 이상이어야 함), 설정 후 Zabbix 서버를 재시작합니다.

3. Zabbix 프론트엔드(Administration > General > Connectors)에서 새 커넥터를 설정하고 zabbix_server -R config_cache_reload 명령으로 서버 캐시를 리로드합니다.

필수 항목은 별표로 표시되어 있습니다.

Kafka 커넥터가 쉼표로 구분된 부트스트랩 브로커 주소 목록으로 설정된 경우(예: Kafka.URL=kafka1.example.com:9093,kafka2.example.com:9093), Kafka 클라이언트는 가장 먼저 응답한 브로커에 연결하여 해당 브로커의 클러스터 메타데이터를 사용합니다. 목록에 서로 다른 Kafka 클러스터의 주소가 포함되어 있으면 가장 빠르게 응답한 클러스터만 사용되고 나머지 주소는 사용 불가로 로그에 기록됩니다. 그 결과 커넥터가 정상적으로 연결되어 있더라도 다음과 같은 시작 경고가 나타날 수 있습니다:

kafka cluster connected, but broker(s) "kafka1.example.com:9093, kafka2.example.com:9093" unavailable; will retry on message send if active brokers fail

일부 환경(사설 네트워크, 컨테이너 네트워크 또는 비표준 DNS/hosts 설정)에서는 호스트 이름이나 IP가 루프백 주소(예: 127.0.0.1/localhost)로 확인되거나 클라이언트에 의해 정규화될 수 있어 이러한 경고가 혼란을 줄 수 있습니다. 혼란을 줄이려면 모든 Kafka.URL 주소가 동일한 Kafka 클러스터에 속하는지 확인하고, 커넥터 호스트와 브로커의 advertised.listeners로부터의 DNS 확인을 검증하며, 브로커의 advertised 주소로 확인되는 주소를 사용하는 것이 좋습니다.

프로토콜

서버와 수신자 간의 통신은 REST API, NDJSON, "Content-Type: application/x-ndjson"을 사용하여 HTTP로 이루어집니다.

자세한 내용은 Newline-delimited JSON export protocol을 참고하세요.

서버 요청

아이템 값 스트리밍 예제:

POST /v1/history HTTP/1.1
Host: localhost:8080
Accept: */*
Accept-Encoding: deflate, gzip, br, zstd
Content-Length: 628
Content-Type: application/x-ndjson

{"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":44457,"name":"foo","clock":1673454303,"ns":800155804,"value":0,"type":3}
{"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"foo","value":"test"}],"itemid":44457,"name":"foo","clock":1673454303,"ns":832290669,"value":1,"type":3}
{"host":{"host":"Zabbix server","name":"Zabbix server"},"groups":["Zabbix servers"],"item_tags":[{"tag":"bar","value":"test"}],"itemid":44458,"name":"bar","clock":1673454303,"ns":867770366,"value":123,"type":3}

이벤트 스트리밍 예제:

POST /v1/events HTTP/1.1
Host: localhost:8080
Accept: */*
Accept-Encoding: deflate, gzip, br, zstd
Content-Length: 333
Content-Type: application/x-ndjson

{"clock":1673454303,"ns":800155804,"value":1,"eventid":5,"name":"trigger for foo being 0","severity":0,"hosts":[{"host":"Zabbix server","name":"Zabbix server"}],"groups":["Zabbix servers"],"tags":[{"tag":"foo_trig","value":"test"},{"tag":"foo","value":"test"}]}
{"clock":1673454303,"ns":832290669,"value":0,"eventid":6,"p_eventid":5}

수신자 응답

응답은 HTTP 응답 상태 코드와 JSON 페이로드로 구성됩니다. 요청이 정상적으로 처리된 경우 HTTP 응답 상태 코드는 "200", "201", "202", "203", "204" 중 하나여야 하며, 실패한 요청은 그 외의 코드를 사용합니다.

성공 예제:

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
Date: Tue, 21 Apr 2026 10:13:04 GMT
Content-Length: 23

{"response":"success"}

오류 예제:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
Date: Tue, 21 Apr 2026 12:15:01 GMT
Content-Length: 55

{"error":"invalid character '{' after top-level value"}