HTTP agent

Zabbix v7.4번역일: 2026-09-09원본 보기

개요

이 아이템 유형은 HTTP/HTTPS 프로토콜을 사용한 데이터 폴링을 허용합니다. Zabbix sender 유틸리티나 Zabbix sender 프로토콜(Zabbix server 또는 proxy로 데이터를 전송하는 경우), 또는 history.push API 메소드(Zabbix server로 데이터를 전송하는 경우)를 사용한 트래핑도 가능합니다.

HTTP 아이템 체크는 Zabbix server가 실행합니다. 하지만 호스트가 Zabbix proxy에 의해 모니터링되는 경우, HTTP 아이템 체크는 proxy가 실행합니다.

HTTP 아이템 체크는 모니터링 대상 호스트에서 실행되는 에이전트를 필요로 하지 않습니다.

HTTP agent는 HTTP와 HTTPS를 모두 지원합니다. Zabbix는 선택적으로 리다이렉트를 따라갈 수 있습니다(아래 Follow redirects 옵션 참고). 최대 리다이렉트 횟수는 10회로 하드코딩되어 있습니다(cURL 옵션 CURLOPT_MAXREDIRS 사용).

Zabbix server/proxy는 cURL(libcurl) 지원이 포함된 상태로 초기 설정되어야 합니다.

HTTP 체크는 비동기적으로 실행됩니다 - 다른 체크를 시작하기 위해 이전 요청의 응답을 받을 때까지 기다릴 필요가 없습니다. DNS 조회도 마찬가지로 비동기적으로 처리됩니다.

비동기 체크의 최대 동시 실행 수는 1000개입니다(MaxConcurrentChecksPerPoller로 정의).

비동기 HTTP agent poller 수는 StartHTTPAgentPollers 파라미터로 정의됩니다.

지속적 연결(persistent connections) cURL 기능은 Zabbix 7.0부터 HTTP agent 체크에 추가되었습니다.

설정

HTTP 아이템을 설정하려면:

  1. Data collection > Hosts로 이동합니다.
  2. 호스트 행에서 Items를 클릭합니다.
  3. Create item을 클릭합니다.
  4. 양식에 아이템의 파라미터를 입력합니다.

필수 입력 필드는 모두 빨간색 별표로 표시되어 있습니다.

HTTP 아이템에서 특정 정보가 필요한 필드는 다음과 같습니다:

Parameter 설명
Type 여기서 HTTP agent를 선택합니다.
Key 고유한 아이템 key를 입력합니다.
URL 연결하여 데이터를 가져올 URL입니다. 예:
https://www.example.com
http://www.example.com/download
도메인 이름은 유니코드 문자로 지정할 수 있습니다. HTTP 체크를 실행할 때 자동으로 punycode로 ASCII 변환됩니다.
Parse 버튼을 사용하면 선택적 쿼리 필드(예: ?name=Admin&password=mypassword)를 URL에서 분리하여 속성과 값을 자동 URL 인코딩을 위해 Query fields로 옮길 수 있습니다.
2048자로 제한됩니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_URL cURL 옵션을 설정합니다.
Query fields URL을 위한 변수입니다(위 참고).
속성과 값의 쌍으로 지정합니다.
값은 자동으로 URL 인코딩됩니다. 매크로에서 나온 값은 해석된 후 자동으로 URL 인코딩됩니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_URL cURL 옵션을 설정합니다.
Request type 요청 메소드 유형을 선택합니다: GET, POST, PUT 또는 HEAD
Request body type 요청 본문 유형을 선택합니다:
Raw data - 커스텀 HTTP 요청 본문, 매크로는 치환되지만 인코딩은 수행되지 않습니다
JSON data - JSON 형식의 HTTP 요청 본문. 매크로는 문자열, 숫자, true, false로 사용할 수 있으며, 문자열로 사용되는 매크로는 큰따옴표로 감싸야 합니다. 매크로에서 나온 값은 해석된 후 자동으로 이스케이프됩니다. 헤더에 "Content-Type"이 지정되지 않으면 기본값으로 "Content-Type: application/json"이 사용됩니다
XML data - XML 형식의 HTTP 요청 본문. 매크로는 텍스트 노드, 속성 또는 CDATA 섹션으로 사용할 수 있습니다. 매크로에서 나온 값은 해석된 후 텍스트 노드와 속성에서 자동으로 이스케이프됩니다. 헤더에 "Content-Type"이 지정되지 않으면 기본값으로 "Content-Type: application/xml"이 사용됩니다
참고: XML data를 선택하려면 libxml2가 필요합니다.
Request body 요청 본문을 입력합니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
Headers 요청을 수행할 때 전송될 커스텀 HTTP 헤더입니다.
속성과 값의 쌍으로 지정합니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_HTTPHEADER cURL 옵션을 설정합니다.
Required status codes 예상되는 HTTP 상태 코드 목록입니다. Zabbix가 목록에 없는 코드를 받으면 해당 아이템은 지원되지 않음(unsupported) 상태가 됩니다. 비어 있으면 체크가 수행되지 않습니다.
예: 200,201,210-299
목록에서 지원되는 매크로: 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLINFO_RESPONSE_CODE cURL 옵션을 사용합니다.
Follow redirects HTTP 리다이렉트를 따라가려면 체크박스를 선택합니다.
이 필드는 CURLOPT_FOLLOWLOCATION cURL 옵션을 설정합니다.
Retrieve mode 가져와야 할 응답 부분을 선택합니다:
Body - 본문만
Headers - 헤더만
Body and headers - 본문과 헤더
Convert to JSON Retrieve mode가 Body로 설정되지 않은 경우, 헤더는 "header" key 아래에 속성과 값의 쌍으로 저장됩니다.
'Content-Type: application/json'이 확인되면 본문은 객체로 저장되고, 그렇지 않으면 문자열로 저장됩니다. 예:
HTTP proxy 사용할 HTTP 프록시를 [protocol://][username[:password]@]proxy.example.com[:port] 형식으로 지정할 수 있습니다.
선택적인 protocol:// 접두사는 대체 프록시 프로토콜(예: https, socks4, socks5; 문서 참고, 프로토콜 접두사 지원은 cURL 7.21.7에서 추가됨)을 지정할 때 사용할 수 있습니다. 프로토콜이 지정되지 않으면 프록시는 HTTP 프록시로 처리됩니다. 잘못된 프로토콜을 지정하면 연결이 실패하고 아이템은 지원되지 않음(unsupported) 상태가 됩니다.
기본적으로 1080 포트가 사용됩니다.
지정된 경우, 프록시는 http_proxy, HTTPS_PROXY와 같은 프록시 관련 환경 변수를 덮어씁니다. 지정되지 않은 경우, 프록시는 프록시 관련 환경 변수를 덮어쓰지 않습니다. 입력된 값은 "있는 그대로" 전달되며, 유효성 검사는 이루어지지 않습니다.
참고: HTTP 프록시에서는 단순 인증만 지원됩니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_PROXY cURL 옵션을 설정합니다.
HTTP authentication 인증 옵션을 선택합니다:
None - 인증을 사용하지 않음;
Basic - 기본 인증 사용;
NTLM - NTLM(Windows NT LAN Manager) 인증 사용;
Kerberos - Kerberos 인증 사용(참고: Zabbix에서 Kerberos 설정하기);
Digest - Digest 인증 사용.
이 필드는 CURLOPT_HTTPAUTH cURL 옵션을 설정합니다.
User name 사용자 이름을 입력합니다(최대 255자).
이 필드는 HTTP authentication이 Basic, NTLM, Kerberos, Digest 중 하나로 설정된 경우 사용할 수 있습니다. 사용자 매크로와 저수준 디스커버리 매크로가 지원됩니다.
Password 사용자 비밀번호를 입력합니다(최대 255자).
이 필드는 HTTP authentication이 Basic, NTLM, Kerberos, Digest 중 하나로 설정된 경우 사용할 수 있습니다. 사용자 매크로와 저수준 디스커버리 매크로가 지원됩니다.
SSL verify peer 웹 서버의 SSL 인증서를 검증하려면 체크박스를 선택합니다. 서버 인증서는 시스템 전체의 인증 기관(CA) 위치에서 자동으로 가져옵니다. Zabbix server 또는 proxy 설정 파라미터 SSLCALocation을 사용하여 CA 파일 위치를 재정의할 수 있습니다.
이 필드는 CURLOPT_SSL_VERIFYPEER cURL 옵션을 설정합니다.
SSL verify host 웹 서버 인증서의 Common Name 필드나 Subject Alternate Name 필드가 일치하는지 검증하려면 체크박스를 선택합니다.
이 필드는 CURLOPT_SSL_VERIFYHOST cURL 옵션을 설정합니다.
SSL certificate file 클라이언트 인증에 사용되는 SSL 인증서 파일의 이름입니다. 인증서 파일은 PEM^1^ 형식이어야 합니다. 인증서 파일에 개인 키(private key)도 포함되어 있다면 SSL key file 필드는 비워 두십시오. 키가 암호화되어 있다면 SSL key password 필드에 비밀번호를 지정하십시오. 이 파일이 위치한 디렉토리는 Zabbix server 또는 proxy 설정 파라미터 SSLCertLocation으로 지정됩니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_SSLCERT cURL 옵션을 설정합니다.
SSL key file 클라이언트 인증에 사용되는 SSL 개인 키 파일의 이름입니다. 개인 키 파일은 PEM^1^ 형식이어야 합니다. 이 파일이 위치한 디렉토리는 Zabbix server 또는 proxy 설정 파라미터 SSLKeyLocation으로 지정됩니다.
지원되는 매크로: {HOST.IP}, {HOST.CONN}, {HOST.DNS}, {HOST.HOST}, {HOST.NAME}, {HOST.PORT}, {ITEM.ID}, {ITEM.KEY}, {ITEM.KEY.ORIG}, 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_SSLKEY cURL 옵션을 설정합니다.
SSL key password SSL 개인 키 파일 비밀번호입니다.
지원되는 매크로: 사용자 매크로, 저수준 디스커버리 매크로.
이 필드는 CURLOPT_KEYPASSWD cURL 옵션을 설정합니다.
Timeout Zabbix는 URL 처리에 설정된 시간(1-600초)보다 더 많은 시간을 쓰지 않습니다. 실제로 이 파라미터는 URL에 연결하는 최대 시간과 HTTP 요청을 수행하는 최대 시간을 정의합니다. 따라서 Zabbix는 하나의 체크에 2 x Timeout초보다 더 많은 시간을 쓰지 않습니다.
이 필드는 CURLOPT_TIMEOUT cURL 옵션을 설정합니다.
Timeout 파라미터에 대한 자세한 내용은 일반 아이템 속성을 참고하십시오.
Enable trapping 이 체크박스를 선택하면, 해당 아이템은 trapper 아이템으로도 동작하여 Zabbix sender 유틸리티나 Zabbix sender 프로토콜을 사용해 Zabbix server 또는 proxy로 전송된 데이터를 받아들이거나, history.push API 메소드를 사용해 Zabbix server로 전송된 데이터를 받아들입니다. 데이터 전송에 대한 자세한 내용은 다음을 참고하십시오: Trapper 아이템.
Allowed hosts Enable trapping 체크박스가 선택된 경우에만 표시됩니다.
쉼표로 구분된 IP 주소 목록으로, 선택적으로 CIDR 표기법이나 DNS 이름을 사용할 수 있습니다.
지정된 경우, 여기 나열된 호스트에서만 들어오는 연결이 허용됩니다.
IPv6 지원이 활성화된 경우 '127.0.0.1', '::127.0.0.1', '::ffff:127.0.0.1'은 동일하게 취급되며 '::/0'은 모든 IPv4 또는 IPv6 주소를 허용합니다.
'0.0.0.0/0'을 사용하면 모든 IPv4 주소를 허용할 수 있습니다.
"IPv4 호환 IPv6 주소"(0000::/96 접두사)는 지원되지만 RFC4291에 의해 더 이상 권장되지 않습니다(deprecated).
예: 127.0.0.1, 192.168.1.0/24, 192.168.3.1-255, 192.168.1-10.1-255, ::1,2001:db8::/32, mysqlserver1, zabbix.example.com, {HOST.HOST}
이 필드에는 공백과 사용자 매크로가 허용됩니다.
호스트 매크로: {HOST.HOST}, {HOST.NAME}, {HOST.IP}, {HOST.DNS}, {HOST.CONN}이 이 필드에서 허용됩니다.

HTTP proxy 필드를 비워 두는 경우, HTTP 프록시를 사용하는 다른 방법은 프록시 관련 환경 변수를 설정하는 것입니다.

HTTP의 경우 - Zabbix server 사용자를 위해 http_proxy 환경 변수를 설정합니다. 예:
http_proxy=http://proxy_ip:proxy_port.

HTTPS의 경우 - HTTPS_PROXY 환경 변수를 설정합니다. 예:
HTTPS_PROXY=http://proxy_ip:proxy_port. 더 자세한 내용은 쉘 명령어를 실행하여 확인할 수 있습니다: # man curl.

[1] Zabbix는 PEM 형식의 인증서와 개인 키 파일만 지원합니다. 인증서와 개인 키 데이터가 PKCS #12 형식 파일(보통 *.p12 또는 *.pfx 확장자)로 되어 있는 경우, 다음 명령어를 사용하여 PEM 파일을 생성할 수 있습니다:

openssl pkcs12 -in ssl-cert.p12 -clcerts -nokeys -out ssl-cert.pem
openssl pkcs12 -in ssl-cert.p12 -nocerts -nodes  -out ssl-cert.key

예시

예시 1

Elasticsearch와 같은 서비스에서 데이터를 가져오기 위해 간단한 GET 요청을 보냅니다:

  • URL이 localhost:9200/?pretty인 GET 아이템을 생성합니다
  • 응답을 확인합니다:
    {
      "name" : "YQ2VAY-",
      "cluster_name" : "elasticsearch",
      "cluster_uuid" : "kH4CYqh5QfqgeTsjh2F9zg",
      "version" : {
        "number" : "6.1.3",
        "build_hash" : "af51318",
        "build_date" : "2018-01-26T18:22:55.523Z",
        "build_snapshot" : false,
        "lucene_version" : "7.1.0",
        "minimum_wire_compatibility_version" : "5.6.0",
        "minimum_index_compatibility_version" : "5.0.0"
      },
      "tagline" : "You know, for search"
    }
  • 이제 JSONPath 전처리 단계를 사용하여 버전 번호를 추출합니다: $.version.number
예시 2

Elasticsearch와 같은 서비스에서 데이터를 가져오기 위해 간단한 POST 요청을 보냅니다:

  • URL이 http://localhost:9200/str/values/_search?scroll=10s인 POST 아이템을 생성합니다
  • 프로세서 부하(코어당 1분 평균)를 얻기 위해 다음 POST 본문을 구성합니다
    {
        "query": {
            "bool": {
                "must": [{
                    "match": {
                        "itemid": 28275
                    }
                }],
                "filter": [{
                    "range": {
                        "clock": {
                            "gt": 1517565836,
                            "lte": 1517566137
                        }
                    }
                }]
            }
        }
    }
  • 수신된 결과:
    {
        "_scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAAkFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAJRZZUTJWQVktVFNacU5nRHhlcEI0QUxRAAAAAAAAACYWWVEyVkFZLVRTWnFOZ0R4ZXBCNEFMUQAAAAAAAAAnFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAKBZZUTJWQVktVFNacU5nRHhlcEI0QUxR",
        "took": 18,
        "timed_out": false,
        "_shards": {
            "total": 5,
            "successful": 5,
            "skipped": 0,
            "failed": 0
        },
        "hits": {
            "total": 1,
            "max_score": 1.0,
            "hits": [{
                "_index": "dbl",
                "_type": "values",
                "_id": "dqX9VWEBV6sEKSMyk6sw",
                "_score": 1.0,
                "_source": {
                    "itemid": 28275,
                    "value": "0.138750",
                    "clock": 1517566136,
                    "ns": 25388713,
                    "ttl": 604800
                }
            }]
        }
    }
  • 이제 JSONPath 전처리 단계를 사용하여 아이템 값을 얻습니다: $.hits.hits[0]._source.value
예시 3

apiinfo.version을 사용하여 Zabbix API가 살아있는지 확인합니다.

  • 아이템 설정:

JSON 데이터를 사용한 POST 메소드 사용, 요청 헤더 설정, 헤더만 반환하도록 요청한 부분을 확인하십시오:

  • HTTP 코드를 얻기 위한 정규식을 사용한 아이템 값 전처리:

  • Latest data에서 결과 확인:

예시 4

Openweathermap 공개 서비스에 연결하여 날씨 정보를 가져옵니다.

  • 단일 JSON으로 대량 데이터를 수집하기 위한 마스터 아이템을 구성합니다:

쿼리 필드에서 매크로가 사용된 부분을 확인하십시오. 이를 채우는 방법은 Openweathermap API를 참고하십시오.

HTTP agent 응답으로 반환되는 샘플 JSON:

{
    "body": {
        "coord": {
            "lon": 40.01,
            "lat": 56.11
        },
        "weather": [{
            "id": 801,
            "main": "Clouds",
            "description": "few clouds",
            "icon": "02n"
        }],
        "base": "stations",
        "main": {
            "temp": 15.14,
            "pressure": 1012.6,
            "humidity": 66,
            "temp_min": 15.14,
            "temp_max": 15.14,
            "sea_level": 1030.91,
            "grnd_level": 1012.6
        },
        "wind": {
            "speed": 1.86,
            "deg": 246.001
        },
        "clouds": {
            "all": 20
        },
        "dt": 1526509427,
        "sys": {
            "message": 0.0035,
            "country": "RU",
            "sunrise": 1526432608,
            "sunset": 1526491828
        },
        "id": 487837,
        "name": "Stavrovo",
        "cod": 200
    }
}

다음 작업은 JSON에서 데이터를 추출하는 종속 아이템(dependent items)을 구성하는 것입니다.

  • 습도를 위한 샘플 종속 아이템을 구성합니다:

'Temperature'와 같은 다른 날씨 지표도 동일한 방식으로 추가됩니다.

  • JSONPath를 사용한 샘플 종속 아이템 값 전처리:

  • Latest data에서 날씨 데이터 결과를 확인합니다:

예시 5

Nginx 상태 페이지에 연결하여 그 지표들을 일괄로 가져옵니다.

  • 공식 가이드를 따라 Nginx를 구성합니다.
  • 대량 데이터 수집을 위한 마스터 아이템을 구성합니다:

Nginx stub status 출력 샘플:

Active connections: 1 Active connections:
server accepts handled requests
 52 52 52
Reading: 0 Writing: 1 Waiting: 0

다음 작업은 데이터를 추출하는 종속 아이템을 구성하는 것입니다.

  • 초당 요청 수를 위한 샘플 종속 아이템을 구성합니다:

  • 정규식 server accepts handled requests\s+([0-9]+) ([0-9]+) ([0-9]+)를 사용한 샘플 종속 아이템 값 전처리:

  • Latest data에서 stub 모듈의 전체 결과를 확인합니다: