사용자 매크로

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

개요

Zabbix는 기본 제공되는 지원 매크로 외에도, 더 높은 유연성을 위해 사용자 매크로를 지원합니다.

사용자 매크로는 전역, 템플릿, 호스트 수준에서 정의할 수 있습니다. 이 매크로는 특별한 구문을 가집니다:

{$MACRO}

Zabbix는 다음 우선순위에 따라 매크로를 확인합니다:

  1. 호스트 수준 매크로(가장 먼저 확인됨)
  2. 호스트의 1단계 템플릿(즉, 호스트에 직접 연결된 템플릿)에 정의된 매크로, 템플릿 ID로 정렬
  3. 호스트의 2단계 템플릿에 정의된 매크로, 템플릿 ID로 정렬
  4. 호스트의 3단계 템플릿에 정의된 매크로, 템플릿 ID로 정렬, 등등
  5. 전역 매크로(가장 나중에 확인됨)

다시 말해, 호스트에 매크로가 존재하지 않으면 Zabbix는 점점 깊어지는 호스트 템플릿에서 이를 찾으려고 시도합니다. 그래도 찾지 못하면 전역 매크로가 존재할 경우 그것이 사용됩니다.

동일한 수준의 여러 연결된 템플릿에 동일한 이름을 가진 매크로가 존재하는 경우, 가장 낮은 ID를 가진 템플릿의 매크로가 사용됩니다. 따라서 여러 템플릿에 동일한 이름의 매크로를 두는 것은 구성 위험 요소입니다.

Zabbix가 매크로를 찾을 수 없으면 해당 매크로는 확인되지 않습니다.

매크로(사용자 매크로 포함)는 복잡한 구성을 더 명확하게 하기 위한 설계상, 구성(Configuration) 섹션(예: 트리거 목록)에서는 확인되지 않은 상태로 남습니다.

사용자 매크로는 다음 위치에서 사용할 수 있습니다:

  • 아이템 이름
  • 아이템 키 파라미터
  • 아이템 업데이트 간격 및 유연한 간격(flexible intervals)
  • 트리거 이름 및 설명
  • 트리거 표현식 파라미터 및 상수(예시 참조)
  • 기타 다양한 위치 - 전체 목록 참조
전역 매크로와 호스트 매크로의 일반적인 사용 사례
  • 전역 매크로를 여러 위치에서 사용한 다음, 매크로 값을 변경하고 클릭 한 번으로 모든 위치에 구성 변경 사항 적용하기
  • 비밀번호, 포트 번호, 파일 이름, 정규 표현식 등 호스트별 속성을 가진 템플릿 활용하기

전역 매크로를 추가, 업데이트, 삭제하면 모든 호스트에 대해 점진적인 구성 업데이트가 강제로 발생하므로, 전역 매크로 대신 호스트 매크로를 사용하는 것이 권장됩니다. 자세한 내용은 수동 및 자동 에이전트 점검을 참조하십시오.

구성

사용자 매크로를 정의하려면 프론트엔드에서 해당 위치로 이동하십시오:

  • 전역 매크로의 경우 Administration → Macros를 방문하십시오
  • 호스트 및 템플릿 수준 매크로의 경우 호스트 또는 템플릿 속성을 열고 Macros 탭을 찾으십시오

사용자 매크로는 다음과 같은 속성을 가집니다:

파라미터 설명
Macro 매크로 이름. 이름은 중괄호로 감싸야 하며 달러 기호로 시작해야 합니다.
예시: {$FRONTEND_URL}. 매크로 이름에는 다음 문자가 허용됩니다: A-Z(대문자만), 0-9, _, .
Value 매크로 값. 세 가지 값 유형이 지원됩니다:
Text(기본값) - 일반 텍스트 값
Secret text - 값이 별표로 마스킹됨
Vault secret - 값에 vault secret에 대한 경로/쿼리가 포함됨.

값 유형을 변경하려면 값 입력 필드 끝에 있는 버튼을 클릭하십시오.

사용자 매크로 값의 최대 길이는 2048자입니다.
Description 이 매크로에 대한 추가 정보를 제공하는 데 사용되는 텍스트 필드입니다.

사용자 매크로를 구성할 때 다음과 같은 상황별 동작에 유의하십시오:

  • 사용자 매크로가 템플릿 아이템이나 트리거에서 사용되는 경우, (전역으로 정의되어 있더라도) 해당 매크로를 템플릿에도 추가하는 것을 고려하십시오. 그래야 Text 유형 매크로가 템플릿을 XML로 내보내고 다른 시스템으로 가져온 후에도 예상대로 작동합니다(시크릿 매크로 값은 내보내기되지 않습니다)
  • 사용자 매크로가 트리거 표현식에서 사용되는 경우, 파라미터나 상수를 참조할 때만 확인됩니다. 호스트, 아이템 키, 함수, 연산자, 또는 다른 트리거 표현식을 참조하는 경우에는 확인되지 않습니다(시크릿 매크로는 트리거 표현식에서 사용할 수 없습니다)
  • 호스트 프로토타입이 있는 로우레벨 디스커버리 규칙을 가진 호스트에서 사용자 매크로가 사용되는 경우, 디스커버리된 호스트는 해당 호스트에 정의된 모든 사용자 매크로를 상속합니다

예시

예시 1

"Status of SSH daemon" 아이템 키에서 호스트 수준 매크로 사용:

net.tcp.service[ssh,,{$SSH_PORT}]

이 아이템은 여러 호스트에 할당할 수 있으며, 해당 호스트에서 {$SSH_PORT} 값이 정의되어 있어야 합니다.

예시 2

"CPU load is too high" 트리거에서 호스트 수준 매크로 사용:

last(/ca_001/system.cpu.load[,avg1])>{$MAX_CPULOAD}

이러한 트리거는 개별 호스트에서 편집하지 않고 템플릿에서 생성됩니다.

값의 개수를 함수 파라미터로 사용하려는 경우(예: max(/host/key,#3)), 다음과 같이 매크로 정의에 해시 기호를 포함하십시오: SOME_PERIOD => #3

예시 3

"CPU load is too high" 트리거에서 두 개의 매크로 사용:

min(/ca_001/system.cpu.load[,avg1],{$CPULOAD_PERIOD})>{$MAX_CPULOAD}

매크로는 트리거 함수의 파라미터로 사용될 수 있으며, 이 예시에서는 min() 함수가 그렇습니다.

예시 4

에이전트 사용 불가 조건을 아이템 업데이트 간격과 동기화:

  • {$INTERVAL} 매크로를 정의하여 아이템 업데이트 간격에 사용합니다;
  • 에이전트 사용 불가 트리거의 파라미터로 {$INTERVAL}을 사용합니다:

nodata(/ca_001/agent.ping,{$INTERVAL})=1

예시 5

근무 시간 구성 중앙화:

  • 1-5,09:00-18:00과 동일한 전역 {$WORKING_HOURS} 매크로를 생성합니다;
  • Administration → General → GUI의 Working time 필드에서 사용합니다;
  • Users → Users의 사용자 Media 탭에 있는 When active 필드에서 사용합니다;
  • 근무 시간 동안 더 빈번한 아이템 폴링을 설정하는 데 사용합니다:

  • Time period 액션 조건에서 사용합니다;
  • 필요한 경우 Administration → Macros에서 근무 시간을 조정합니다.
예시 6

디스커버리된 호스트의 아이템을 구성하기 위해 호스트 프로토타입 매크로 사용:

  • 호스트 프로토타입에서 값으로 {#SNMPVALUE} 로우레벨 디스커버리 매크로를 가진 사용자 매크로 {$SNMPVALUE}를 정의합니다:

  • 호스트 프로토타입에 Generic SNMPv2 템플릿을 할당합니다;
  • Generic SNMPv2 템플릿 아이템의 SNMP OID 필드에서 {$SNMPVALUE}를 사용합니다.

사용자 매크로 컨텍스트

컨텍스트가 있는 사용자 매크로를 참조하십시오.