nginx

nginx 통합은 연결 측정항목과 액세스 로그를 수집합니다. 연결 측정항목은 현재 연결 상태(활성, 읽기, 대기)를 캡처합니다. 액세스 로그는 요청, 클라이언트, 서버, 메시지에 매핑된 필드를 포함하여 연결 세부정보를 위해 파싱됩니다.

nginx에 대한 자세한 내용은 nginx 문서를 참조하세요.

기본 요건

nginx 원격 분석을 수집하려면 운영 에이전트를 설치해야 합니다.

  • 측정항목의 경우 버전 2.1.0 이상을 설치합니다.
  • 로그의 경우 버전 2.1.0 이상을 설치합니다.

이 통합에서는 nginx 버전 1.18 및 1.20을 지원합니다.

nginx 인스턴스 구성

상태 페이지에 대한 http://www.example.com/nginx_status와 같이 nginx 구성 파일에서 stub_status 모듈을 사용 설정하여 로컬로 연결 가능한 URL을 설정해야 합니다. stub_status 모듈을 사용 설정하려면 다음 단계를 완료합니다.

  1. status.conf 파일을 수정하거나 파일이 없으면 만듭니다. 이 파일은 일반적으로 /etc/nginx/conf.d에 있는 nginx 구성 디렉터리에서 찾을 수 있습니다.

  2. server 섹션에 다음 줄을 추가합니다.

    location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

    구성 파일은 다음 예시와 같이 표시될 수 있습니다.

    server {
   listen 80;
   server_name 127.0.0.1;
   location /nginx_status {
       stub_status on;
       access_log off;
       allow 127.0.0.1;
       deny all;
   }
   location / {
       root /dev/null;
   }
}

  3. nginx 구성을 새로고침합니다.

    sudo service nginx reload

다음 명령어를 실행하여 이전 단계를 자동화할 수 있습니다. status.conf 파일이 없으면 만들고, 파일이 있으면 기존 항목을 덮어씁니다. 이 명령어는 stub_status를 설정하고, nginx를 새로고침하고, 예상한 정보가 엔드포인트를 통해 노출되는지 확인합니다.

sudo tee /etc/nginx/conf.d/status.conf > /dev/null << EOF
server {
    listen 80;
    server_name 127.0.0.1;
    location /nginx_status {
        stub_status on;
        access_log off;
        allow 127.0.0.1;
        deny all;
    }
    location / {
       root /dev/null;
    }
}
EOF
sudo service nginx reload
curl http://127.0.0.1:80/nginx_status

샘플 출력은 다음과 같습니다.

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

또는 별도의 status.conf 파일을 사용하는 대신 기본 nginx.conf 파일에 직접 줄을 삽입할 수도 있습니다. 이 파일은 일반적으로 /etc/nginx, /usr/local/nginx/conf, /usr/local/etc/nginx 디렉터리 중 하나에 있습니다.

nginx용 운영 에이전트 구성

운영 에이전트 구성 가이드를 수행하여 nginx 인스턴스에서 원격 분석을 수집하는 데 필요한 요소를 추가하고 에이전트를 다시 시작합니다.

구성 예시

다음 명령어는 nginx용 원격 분석을 수집하고 운영 에이전트를 다시 시작하는 구성을 만듭니다.

# Configures Ops Agent to collect telemetry from the app and restart Ops Agent.

set -e

# Create a back up of the existing file so existing configurations are not lost.
sudo cp /etc/google-cloud-ops-agent/config.yaml /etc/google-cloud-ops-agent/config.yaml.bak

# Configure the Ops Agent.
sudo tee /etc/google-cloud-ops-agent/config.yaml > /dev/null << EOF
metrics:
  receivers:
    nginx:
      type: nginx
      stub_status_url: http://127.0.0.1:80/nginx_status
  service:
    pipelines:
      nginx:
        receivers:
          - nginx
logging:
  receivers:
    nginx_access:
      type: nginx_access
    nginx_error:
      type: nginx_error
  service:
    pipelines:
      nginx:
        receivers:
          - nginx_access
          - nginx_error
EOF

sudo service google-cloud-ops-agent restart
sleep 60

로그 수집 구성

nginx에서 로그를 수집하려면 nginx에서 생성하는 로그의 수신자를 만든 후 새 수신자의 파이프라인을 만들어야 합니다.

nginx_access 로그의 수신자를 구성하려면 다음 필드를 지정합니다.

필드 기본값 설명
exclude_paths include_paths 중에서 일치하는 집합에서 제외할 파일 시스템 경로 패턴의 목록입니다.
include_paths [/var/log/nginx/access.log] 각 파일을 테일링하여 읽을 파일 시스템 경로의 목록입니다. 와일드 카드(*)를 경로에 사용할 수 있습니다.
record_log_file_path false true로 설정된 경우 로그 레코드를 가져온 특정 파일의 경로가 출력 로그 항목에 agent.googleapis.com/log_file_path 라벨 값으로 표시됩니다. 와일드 카드를 사용할 경우 레코드를 가져온 파일의 경로만 기록됩니다.
type 값은 nginx_access여야 합니다.
wildcard_refresh_interval 60s include_path의 와일드 카드 파일 경로가 새로고침되는 간격입니다. time.ParseDuration으로 구문 분석할 수 있는 기간으로 제공됩니다(예: 30s 또는 2m). 이 속성은 로그 파일이 기본 간격보다 빠르게 순환되는 높은 로깅 처리량에서 유용할 수 있습니다.

nginx_error 로그의 수신자를 구성하려면 다음 필드를 지정합니다.

필드 기본값 설명
exclude_paths include_paths 중에서 일치하는 집합에서 제외할 파일 시스템 경로 패턴의 목록입니다.
include_paths [/var/log/nginx/error.log] 각 파일을 테일링하여 읽을 파일 시스템 경로의 목록입니다. 와일드 카드(*)를 경로에 사용할 수 있습니다.
record_log_file_path false true로 설정된 경우 로그 레코드를 가져온 특정 파일의 경로가 출력 로그 항목에 agent.googleapis.com/log_file_path 라벨 값으로 표시됩니다. 와일드 카드를 사용할 경우 레코드를 가져온 파일의 경로만 기록됩니다.
type 값은 nginx_error여야 합니다.
wildcard_refresh_interval 60s include_path의 와일드 카드 파일 경로가 새로고침되는 간격입니다. time.ParseDuration으로 구문 분석할 수 있는 기간으로 제공됩니다(예: 30s 또는 2m). 이 속성은 로그 파일이 기본 간격보다 빠르게 순환되는 높은 로깅 처리량에서 유용할 수 있습니다.

로깅되는 내용

logName은 구성에 지정된 수신자 ID에서 파생됩니다. LogEntry 내의 자세한 필드는 다음과 같습니다.

nginx_access 로그에는 LogEntry의 다음 필드가 포함됩니다.

필드 유형 설명
httpRequest 객체 HttpRequest 참조
jsonPayload.host 문자열 호스트 헤더 콘텐츠(일반적으로 nginx에서 보고하지 않음)
jsonPayload.level 문자열 로그 항목 수준
jsonPayload.user 문자열 요청의 인증된 사용자 이름
severity 문자열(LogSeverity) 로그 항목 수준입니다(번역됨).

nginx_error 로그에는 LogEntry의 다음 필드가 포함됩니다.

필드 유형 설명
jsonPayload.client 문자열 클라이언트 IP 주소(선택사항)
jsonPayload.connection 숫자 연결 ID
jsonPayload.host 문자열 호스트 헤더(선택사항)
jsonPayload.level 문자열 로그 항목 수준
jsonPayload.message 문자열 로그 메시지
jsonPayload.pid 숫자 로그를 발급하는 프로세스 ID
jsonPayload.referer 문자열 리퍼러 헤더(선택사항)
jsonPayload.request 문자열 원래 HTTP 요청(선택사항)
jsonPayload.server 문자열 Nginx 서버 이름(선택사항)
jsonPayload.subrequest 문자열 Nginx 하위 요청(선택사항)
jsonPayload.tid 숫자 로그가 발생된 스레드 ID
jsonPayload.upstream 문자열 업스트림 요청 URI(선택사항)
severity 문자열(LogSeverity) 로그 항목 수준입니다(번역됨).

측정항목 수집 구성

nginx에서 측정항목을 수집하려면 nginx에서 생성하는 측정항목의 수신자를 만든 후 새 수신자의 파이프라인을 만들어야 합니다.

이 수신자는 구성에서 여러 인스턴스 모니터링과 같은 여러 인스턴스의 사용을 지원하지 않습니다. 이러한 모든 인스턴스는 동일한 시계열에 기록되며, Cloud Monitoring은 이를 구분할 수 있는 방법이 없습니다.

nginx 측정항목의 수신자를 구성하려면 다음 필드를 지정합니다.

필드 기본값 설명
collection_interval 60s 기간(예: 30s 또는 5m)입니다.
server_status_url http://localhost/status nginx 스텁 상태 모듈로 노출되는 URL입니다.
type 값은 nginx여야 합니다.

모니터링 대상

다음 표에서는 운영 에이전트가 nginx 인스턴스에서 수집하는 측정항목 목록을 보여줍니다.

측정항목 유형 
종류, 유형
모니터링 리소스		 라벨
workload.googleapis.com/nginx.connections_accepted
CUMULATIVE, INT64
gce_instance 		 
workload.googleapis.com/nginx.connections_current
GAUGE, INT64
gce_instance 		state
workload.googleapis.com/nginx.connections_handled
CUMULATIVE, INT64
gce_instance 		 
workload.googleapis.com/nginx.requests
CUMULATIVE, INT64
gce_instance 		 

구성 확인

이 섹션에서는 nginx 수신자를 올바르게 구성했는지 확인하는 방법을 설명합니다. 운영 에이전트에서 원격 분석 수집을 시작하려면 1~2분 정도 걸릴 수 있습니다.

nginx 로그가 Cloud Logging으로 전송되고 있는지 확인하려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Logging을 선택한 후 로그 탐색기를 선택합니다.

    로그 탐색기로 이동

  2. 편집기에 다음 쿼리를 입력한 후 쿼리 실행을 클릭합니다. 
    resource.type="gce_instance"
(log_id("nginx_access") OR log_id("nginx_error"))

nginx 측정항목이 Cloud Monitoring으로 전송되는지 확인하려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 탐색기를 선택합니다.

    측정항목 탐색기로 이동

  2. 쿼리 빌더 창의 툴바에서 이름이 MQL 또는 PromQL인 버튼을 선택합니다.
  3. 언어 전환 버튼에 MQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.
  4. 편집기에 다음 쿼리를 입력한 후 쿼리 실행을 클릭합니다. 
    fetch gce_instance
| metric 'workload.googleapis.com/nginx.requests'
| every 1m

대시보드 보기

nginx 측정항목을 보려면 차트나 대시보드가 구성되어 있어야 합니다. nginx 통합에는 대시보드가 하나 이상 포함됩니다. 통합을 구성하고 운영 에이전트가 측정항목 데이터 수집을 시작한 후 모든 대시보드가 자동으로 설치됩니다.

통합을 설치하지 않고도 대시보드의 정적 미리보기를 볼 수 있습니다.

설치된 대시보드를 보려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 대시보드를 선택합니다.

    대시보드로 이동

  2. 대시보드 목록 탭을 선택한 후 통합 카테고리를 선택합니다.
  3. 확인할 대시보드의 이름을 클릭합니다.

통합을 구성했지만 대시보드가 설치되지 않은 경우 운영 에이전트가 실행 중인지 확인합니다. 대시보드에 차트의 측정항목 데이터가 없으면 대시보드 설치가 실패합니다. 운영 에이전트가 측정항목 수집을 시작하면 대시보드가 자동으로 설치됩니다.

대시보드의 정적 미리보기를 보려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 통합을 선택합니다.

    통합으로 이동

  2. Compute Engine 배포 플랫폼 필터를 클릭합니다.
  3. nginx 항목을 찾고 세부정보 보기를 클릭합니다.
  4. 정적 미리보기를 보려면 대시보드 탭을 선택합니다. 대시보드가 설치되어 있으면 대시보드 보기를 클릭하여 대시보드로 이동할 수 있습니다.

Cloud Monitoring의 대시보드에 대한 자세한 내용은 대시보드 및 차트를 참조하세요.

통합 페이지 사용에 대한 자세한 내용은 통합 관리를 참조하세요.

알림 정책 설치

알림 정책은 지정된 조건이 발생할 때 Cloud Monitoring에서 알림을 받도록 지시합니다. nginx 통합에는 사용할 알림 정책이 하나 이상 포함됩니다. Monitoring의 통합 페이지에서 이러한 알림 정책을 보고 설치할 수 있습니다.

사용 가능한 알림 정책에 대한 설명을 보고 설치하려면 다음을 수행합니다.

  1. Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 통합을 선택합니다.

    통합으로 이동

  2. nginx 항목을 찾고 세부정보 보기를 클릭합니다.
  3. 알림 탭을 선택합니다. 이 탭에는 사용 가능한 알림 정책에 대한 설명과 이를 설치하기 위한 인터페이스가 제공됩니다.
  4. 알림 정책을 설치합니다. 알림 정책은 경고가 트리거되었다는 알림을 전송할 위치를 알아야 하므로, 설치 시 사용자에게 해당 정보를 요청합니다. 알림 정책을 설치하려면 다음을 수행합니다.
    1. 사용 가능한 알림 정책 목록에서 설치할 정책을 선택합니다.

    2. 알림 구성 섹션에서 알림 채널을 하나 이상 선택합니다. 알림 채널 사용을 중지할 수 있지만 사용 중지하면 알림 정책이 자동으로 실행됩니다. Monitoring에서 상태를 확인할 수 있지만 알림이 수신되지 않습니다.

      알림 채널에 대한 자세한 내용은 알림 채널 관리를 참조하세요.

    3. 정책 만들기를 클릭합니다.

Cloud Monitoring의 알림 정책에 대한 자세한 내용은 알림 소개를 참조하세요.

통합 페이지 사용에 대한 자세한 내용은 통합 관리를 참조하세요.

문제 해결

대부분의 배포판에서 nginx는 ngx_http_stub_status_module이 사용 설정된 상태로 제공됩니다. 다음 명령어를 실행하여 모듈이 사용 설정되었는지 확인할 수 있습니다.

sudo nginx -V 2>&1 | grep -o with-http_stub_status_module

예상되는 출력은 모듈이 사용 설정되었음을 의미하는 with-http_stub_status_module입니다. 드물지만 명령어가 출력을 반환하지 않으면 nginx 공개 문서에 따라 소스의 nginx를 -with-http_stub_status_module과 조합해야 합니다.

다음 단계

Ansible을 사용하여 운영 에이전트를 설치하고, 서드파티 애플리케이션을 구성하고, 샘플 대시보드를 설치하는 방법은 운영 에이전트를 설치하여 서드파티 애플리케이션 문제 해결 동영상을 참조하세요.