NGINX Plus

Prometheus-njs

NGINX Plus 에서 직접 Prometheus 지표 Endpoint를 Expose하세요.

목차

1. 모듈 정보
2. 내보낸 지표
3. 설치 지침
4. 구성
5. 업그레이드 지침
6. 모듈 변수
6-1. $prom_keyval 변수 사용
6-2. $prom_keyval_stream 변수 사용
6-3. $prom_metrics_disabled 변수 사용
7. 예제

1. 모듈 정보

nginx-plus-module-prometheus 모듈은 API 모듈에 의해 Expose되는 기타 NGINX Plus 상태 지표를 Prometheus 호환 형식으로 변환하는 njs 모듈입니다. 이 모듈은 /api Endpoint에 대한 하위 요청을 사용하여 지표에 액세스합니다. Upstream 그룹에 대한 일반 이름을 사용하여 동적 Upstream 라우팅을 구성한 경우, 모듈은 이러한 이름의 대체를 이해하고 올바른 통계를 표시할 수 있습니다.

2. 내보낸 지표

다음과 같은 NGINX Plus 상태 지표가 Prometheus로 내보내집니다.

http/upstreams/ 및 /stream/upstreams/의 상태 지표 값은 다음 규칙을 사용하여 변환됩니다.

NGINXPrometheus
“up”1
“draining”2
“down”3
“unavail”4
“checking”5
“unhealthy”6

3. 설치 지침

nginx-plus-module-prometheus 모듈을 설치합니다.

Amazon Linux, CentOS, Oracle Linux 및 RHEL의 경우:

$ yum install nginx-plus-module-prometheus

Debian 및 Ubuntu의 경우:

$ apt-get install nginx-plus-module-prometheus

SLES의 경우:

$ zypper install nginx-plus-module-prometheus

Alpine의 경우:

$ apk add nginx-plus-module-prometheus

Note: nginx-plus-module-njs 모듈도 모듈과 함께 설치됩니다.

4. 구성

모듈 설치 후 NGINX Plus 구성 파일(nginx.conf)에서 다음 단계를 수행합니다.

1. 최상위 컨텍스트에서 nginx-plus-module-njs 모듈을 활성화합니다.

load_module modules/ngx_http_js_module.so;

http {
    # ...
}

2. prometheus.js 파일을 포함합니다.

http {
    # ...
    js_import /usr/share/nginx-plus-module-prometheus/prometheus.js;
}

3. Prometheus 지표를 위한 location(예: /metrics)를 생성합니다.

location = /metrics {
    js_content prometheus.metrics;
}

4. API가 Prometheus에서 /metrics Endpoint를 Expose할 수 있도록 활성화합니다.

location /api {
    api;
    #...
}

5. (선택 사항, 오류 로그에 “too big sub-request response” 오류가 발생하는 경우) 모듈은 API 호출에 하위 요청을 사용하므로 하위 요청의 응답 본문을 저장하는 버퍼의 크기를 늘려야 할 수 있습니다.

http {
    # ...
    subrequest_output_buffer_size 32k;
}

6. Prometheus 구성 파일의 scrape_config 섹션에 NGINX Plus 인스턴스의 네트워크 주소를 지정하여 NGINX Plus에서 지표를 가져오도록 Prometheus를 구성합니다.

5. 업그레이드 지침

Prometheus-njs 버전을 버전 1.3.1 이상으로 업그레이드하는 경우, NGINX Plus R22 및 njs 0.4.0에 도입된 변경 사항으로 NGINX Plus 구성 파일을 업데이트하는 것이 중요합니다.

6. 모듈 변수

이 모듈은 여러 임베디드 변수를 지원합니다.

변수는 set 지시문을 사용하여 NGINX Plus 구성 파일에서 설정할 수 있습니다.

6-1. $prom_keyval 변수 사용

$prom_keyval 변수는 Upstream 라우팅의 동적 구성에 대한 통계를 올바르게 표시하기 위해 만들어졌습니다. Upstream의 이름이 일반 이름이고 이러한 이름이 Key-Value 저장소의 실제 이름으로 동적으로 대체되는 경우입니다.

$prom_keyval 변수를 추가하려면 Prometheus에 지표를 Expose하는 location(예: = /metrics)에 다음 형식의 set 지시문을 추가합니다.

set $prom_keyval "upstream_keyval";

여기서 $prom_keyval은 keyval_zone 지시문에 지정된 upstream_keyval Key-Val 저장소의 모든 값을 보유합니다.

http {

    #...

    keyval_zone zone=upstream_keyval:64k;
    keyval      $domain $upstream zone=http_upstream_keyval;

    upstream 0 {
        zone   http_backend 64k;
        server backend1.example.com;
        server backend2.example.com;
    }

    server {
        #...

        location / {
            proxy_pass http://$upstream;
            #...
        }

        location /api {
            api;
            #...
        }

        location = /metrics {
            set        $prom_keyval "http_upstream_keyval";
            js_content prometheus.metrics;
        }
    }
}

6-2. $prom_keyval_stream 변수 사용

stream { } 컨텍스트에서 동적 교체를 수행하려면 stream 블록에 새 Key-Val 저장소를 지정하고 $prom_keyval_stream 변수에 Key-Val 저장소의 이름을 설정해야 합니다.

http {

    # the contents of the 'http' block is the same as for the $prom_keyval example
    # except the 'location /metrics' block:
    # ...

        location = /metrics {
            set $prom_keyval        "http_upstream_keyval";
            set $prom_keyval_stream "stream_upstream_keyval";
            js_content              prometheus.metrics;
        }
    }
}

stream {

    keyval_zone zone=stream_keyval:32k;

    upstream stream_backend {
        zone   stream_backend 64k;
        server backend1.example.com:12345;
        server backend2.example.com:12345;
    }

    server {
        listen 12345;

        proxy_pass  stream_backend;
        status_zone backend_stream_zone;
    }
}

6-3. $prom_metrics_disabled 변수 사용

$prom_metrics_disabled 변수는 특정 NGINX Plus 상태 지표를 Prometheus로 내보내는 것을 비활성화합니다. Prometheus에서 NGINX Plus 지표가 차지하는 스토리지 양이 걱정된다면 이 변수를 통해 특정 Endpoint를 비활성화할 수 있습니다. 변수 값은 쉼표로 구분된 NGINX Plus Endpoint 목록이어야 합니다.

#...
location /metrics {
    set $prom_keyval           "http_upstream_keyval";
    set $prom_keyval_stream    "stream_upstream_keyval";
    set $prom_metrics_disabled "stream/upstreams, resolvers";
    js_content                 prometheus.metrics;
}
#...

다음과 같은 NGINX Plus 상태 지표를 Prometheus로 내보내지 않도록 설정할 수 있습니다:

  • nginx
  • processes
  • resolvers
  • connections
  • ssl
  • slabs
  • http/requests
  • http/caches
  • http/upstreams
  • http/server_zones
  • http/location_zones
  • http/limit_conns
  • http/limit_reqs
  • stream/upstreams
  • stream/server_zones
  • stream/zone_sync
  • stream/limit_conns

7. 예제

load_module modules/ngx_http_js_module.so;

#...

http {

    js_import /usr/share/nginx-plus-module-prometheus/prometheus.js;

    subrequest_output_buffer_size 32k;

    upstream backend {
        zone   backend 64k;
        server backend1.example.com;
        server backend2.example.com;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
        }

        location /api {
            api;
        }

        location = /metrics {
            set $prom_keyval           "http_upstream_keyval";
            set $prom_keyval_stream    "stream_upstream_keyval";
            set $prom_metrics_disabled "stream/upstreams, resolvers";
            js_content                 prometheus.metrics;
        }

        status_zone backend_zone;
    }
}

stream {

    keyval_zone zone=stream_keyval:32k;

    upstream stream_backend {
        zone   stream_backend 64k;
        server backend1.example.com:12345;
        server backend2.example.com:12345;
    }

    server {
        listen 12345;

        proxy_pass  stream_backend;
        status_zone backend_stream_zone;
}