2 외부 시스템으로 스트리밍

개요

Zabbix에서 외부 시스템으로 HTTP를 통해 항목 값과 이벤트를 스트리밍하는 것이 가능합니다 (프로토콜 세부사항 참조).

태그 필터를 사용하여 항목 값이나 이벤트의 하위 집합을 스트리밍할 수 있습니다.

두 가지 Zabbix 서버 프로세스 유형이 데이터 스트리밍을 담당합니다: connector manager와 connector worker. Zabbix 내부 항목 zabbix[connector_queue]을 통해 커넥터 큐에 대기 중인 값의 개수를 모니터링할 수 있습니다.

구성

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

1. Zabbix에서 데이터를 받을 원격 시스템을 설정합니다. 이 목적을 위해 다음 도구들을 사용할 수 있습니다:

• 수신된 정보를 events.ndjson과 history.ndjson 파일에 로그하는 간단한 receiver의 예시.
• Zabbix server용 Kafka 커넥터 - Go로 작성된 경량 서버로, Zabbix 서버에서 Kafka 브로커로 아이템 값과 이벤트를 전달하도록 설계되었습니다.

2. zabbix_server.conf에서 StartConnectors 매개변수를 조정하여 Zabbix에서 필요한 수의 커넥터 워커를 설정합니다. 커넥터 워커의 수는 Zabbix 프론트엔드에서 구성된 커넥터 수와 일치해야 합니다(동시 세션이 1개 이상인 경우 초과해야 함). 그런 다음 Zabbix 서버를 다시 시작합니다.

3. Zabbix 프론트엔드(관리 > 일반 > 커넥터)에서 새 커넥터를 구성하고 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/호스트 설정)에서는 호스트명이나 IP가 루프백 주소(예: 127.0.0.1/localhost)로 해결되거나 클라이언트에 의해 정규화될 수 있어, 이러한 경고가 오해를 불러일으킬 수 있습니다. 혼동을 줄이려면, 모든 Kafka.URL 주소가 동일한 Kafka 클러스터에 속하도록 하고, 커넥터 호스트에서의 DNS 해결과 브로커의 advertised.listeners를 확인하며, 브로커의 광고된 주소로 해결되는 주소를 선호하시기 바랍니다.

프로토콜

서버와 수신기 간의 통신은 REST API, NDJSON, "Content-Type: application/x-ndjson"을 사용하여 HTTP를 통해 수행됩니다.

자세한 내용은 줄바꿈으로 구분된 JSON 내보내기 프로토콜을 참조하세요.

서버 요청

스트리밍 아이템 값의 예:

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"}