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

개요

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

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

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

구성

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

1. Zabbix로부터 데이터를 수신할 원격 시스템을 설정합니다. 이를 위해 다음 도구들을 사용할 수 있습니다:

• 수신된 정보를 events.ndjson 및 history.ndjson 파일에 기록하는 간단한 수신기 예제입니다.
• 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/hosts 설정)에서는 호스트명이나 IP가 루프백 주소(예: 127.0.0.1/localhost)로 해석되거나 클라이언트에 의해 정규화될 수 있어 이러한 경고가 오해의 소지가 있을 수 있습니다. 혼란을 줄이려면 모든 Kafka.URL 주소가 동일한 Kafka 클러스터에 속하도록 하고, 커넥터 호스트와 브로커의 advertised.listeners에서 DNS 해상도를 확인하며, 브로커의 알려진 주소로 해석되는 주소를 선호하십시오.

프로토콜

서버와 수신자 간의 통신은 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"}