NGINX 모니터링

NGINX 센서 및 NGINX 추적 기능은 운영 체제 요구 사항이 다릅니다.

NGINX 센서의 경우, 지원되는 운영 체제는 호스트 에이전트의 요구 사항과 동일하며, 이는 각 호스트 에이전트의 ‘지원되는 운영 체 제’ 섹션에서 확인할 수 있습니다. 예를 들어, ‘ Linux 의 지원되는 운영 체제’를 참조하십시오.

NGINX 추적 기능의 경우, 다음 운영 체제가 지원됩니다:

CPP 센서( 1.12.0 ) 및 이후 버전에서는 Debian 10과 Ubuntu 20.04 에 대한 지원을 중단합니다.

CPP 센서( 1.11.0 )는 2017년 10월부터 CentOS 7, CentOS 8, CentOS Stream 8, Alpine 3.10 및 RHEL 7에 대한 지원을 중단합니다.

NGINX 센서 및 NGINX 추적 기능은 버전 및 플랫폼 요구 사항이 다릅니다. 자세한 내용은 지원되는 NGINX 버전 및 플랫폼을 참조하십시오.

다음 표는 최신 지원 버전 및 지원 정책을 보여줍니다:

지원 정책에 대한 자세한 내용은 ‘센서 지원 전략’을 참조하십시오.

다음 Docker 컨테이너 이미지는 NGINX 추적 기능을 지원합니다:

CPP 센서( 1.12.0 ) 및 이후 버전에서는 컨테이너 이미지 지원을 openresty/openresty CentOS based중단합니다.

Instana 가 NGINX 프로세스를 자동으로 수집하고 모니터링하도록 하려면 다음과 같이 메트릭 수집을 활성화해야 합니다:

• PID
• 작업자 프로세스 수
• 작업자 연결 수
• 시작 시간
• 버전
• 빌드 (*)
• 주소 (*)
• 생성 (*)
• PPID (*)

• 요청
• 연결
• 프로세스 (*)
• SSL (*)
• 캐시 (*)
• 서버 영역 (*)
• 업스트림 (*)

각 센서에는 수신 메트릭에 대해 지속적으로 평가되고 사용자 영향에 따라 문제 또는 인시던트를 제기하는 데 사용되는 상태 서명의 큐레이트된 지식 기반이 있습니다.

내장 이벤트는 엔티티의 상태 지표가 정상 범위를 벗어날 경우 이슈나 인시던트를 발생시키며, 사용자 정의 이벤트는 특정 엔티티의 개별 메트릭 임계값을 기준으로 이슈나 인시던트를 발생시킵니다.

NGINX 센서의 기본 제공 이벤트에 대한 자세한 내용은 기본 제공 이벤트 참조 문서를 참조하십시오.

NGINX 추적 기능을 사용하려면 다음 구성 값을 지정해야 합니다:

• NGINX Ingress용 ConfigMap 에 다음 항목을 추가하십시오:

    data:
      enable-opentracing: "true"
      zipkin-collector-host: $HOST_IP
      zipkin-collector-port: "42699"
   

• NGINX 의 Pod Spec에 다음과 같이 환경 변수를 추가하십시오(이미 POD_NAME 및 가 포함되어 POD_NAMESPACE있어야 합니다):

  env:
     - name: HOST_IP
       valueFrom:
       fieldRef:
           fieldPath: status.hostIP
   

참고:

• Ingress의 ` NGINX `는 `$ENV` 및 ` POD_NAMESPACE $ENV` POD_NAME 환경 변수를 자동으로 설정합니다. 따라서 NGINX Pod Spec에 및 POD_NAMESPACE 환경 POD_NAME 변수를 추가할 필요가 없습니다.

• 이 구성은 Kubernetes DownwardAPI 를 사용하여 호스트 IP를 환경 변수 (HOST_IP) 로 사용 가능하게 하고 ConfigMap 이 이를 선택합니다.

• 포트를 Instana 에이전트 포트인 42699로 고정할 수 있습니다.

• 서비스 이름은 기본 nginx 로 지정되거나 zipkin-service-name매개변수로 겹쳐써야 하며, 이 매개변수는 ConfigMap에서 구성할 수 있습니다.

NGINX Ingress에 대한 자세한 내용은 Kubernetes Ingress NGINX 문서를 참조하십시오.

설정에 ‘ NGINX ’ 추적 기능을 설치하려면 다음 단계를 따르십시오:

1. 사용 중인 NGINX 버전에 맞는 바이너리 파일을 다운로드하세요.
2. NGINX 서버에서 액세스할 수 있는 위치로 바이너리 파일을 복사하십시오.
3. NGINX 의 설정을 수정합니다.
4. NGINX 프로세스를 다시 시작하거나 명령을 reload 전송하여 구성을 다시 불러오십시오.

NGINX 에 서버리스 추적 기능을 구성하려면 다음 단계를 따르십시오:

1. 사용 중인 NGINX 버전에 따라 서버리스 추적을 위한 Instana 바이너리 파일을 다운로드하세요. NGINX 의 HTTP 추적 모듈은 nginx-opentracing 모듈을 기반으로 합니다. Instana 변형 버전은 향상된 사용 편의성, 맞춤형 버그 수정 및 추가 기능을 제공하도록 맞춤 제작되었습니다. Instana 의 바이너리 파일은 NGINX Distributed Tracing Binaries를 참조하십시오.

2. 서버리스 추적을 위해 바이너리 파일을 복사합니다:

   1. 1단계에서 다운로드하여 압축을 푼 바이너리 파일에서 버전에 따라 ' libinstana_sensor.so 모듈의 OpenSSL 변형을 선택합니다. ' openssl version 명령을 사용하여 OpenSSL 버전을 검색합니다. 다음 예시에는 OpenSSL 3.0.2 샘플 출력이 나와 있습니다:

      # openssl version
      OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)
       

      OpenSSL 3.x.x.x의 경우 ' libinstana_sensor_ssl3x.so ' 모듈을 선택합니다.

      • 다음 예시에는 OpenSSL 1.1.1f의 샘플 출력이 나와 있습니다:

        # openssl version
        OpenSSL 1.1.1f  31 Mar 2020
         

        OpenSSL 1.1x의 경우 ' libinstana_sensor_ssl1.1x.so 모듈을 선택합니다.

   2. NGINX 프로세스가 액세스할 수 있는 파일 시스템에 저장하십시오. NGINX 프로세스는. libinstana_sensor.so에 대한 읽기 권한이 필요합니다.

   3. NGINX 가 컨테이너 내에서 실행되는 것이 아니라 호스트 운영 체제에서 직접 실행되는 경우, 두 개의 Instana 바이너리 파일을 다른 NGINX 모듈이 있는 디렉터리로 복사하십시오.

   4. NGINX 가 모듈을 검색하는 위치를 확인하려면 해당 nginx -V 명령을 실행하고 구성 --modules-path 옵션을 찾아보세요.

   5. 다음 단계 중 하나를 완료하십시오.

      • 컨테이너화된 환경에서는 해당 파일을 컨테이너 이미지에 추가하거나 컨테이너에 볼륨으로 마운트합니다.
      • docker 의 마운트 지점에 대해서는 Docker 의 바인드 마운트 항목을 참조하십시오.
      • Kubernetes 에 대해서는 Kubernetes 의 ‘포드에 볼륨 마운트하기’를 참조하십시오.

3. 환경 변수를 설정하십시오.

   1. 명령어 systemctl show -p FragmentPath nginx 출력에 표시된 NGINX 서비스 파일을 검색하십시오. 다음 예제에는 샘플 출력이 나와 있습니다:

      # systemctl show -p FragmentPath nginx
      FragmentPath=/lib/systemd/system/nginx.service
       

   2. NGINX 서비스 파일의 Service 섹션에 환경 INSTANA_AGENT_KEY 변수 INSTANA_ENDPOINT_URL 와 를 추가하십시오. 환경 변수에 대한 자세한 내용은 서버리스 모니터링용 환경 변수를 참조하세요.

   3. 다음 예시와 같이 ' INSTANA_ENDPOINT_URL ' 및 ' INSTANA_AGENT_KEY '를 실제 값으로 바꿉니다:

      [Service]
      Environment="INSTANA_ENDPOINT_URL=https://XXX.instana.io/serverless/"
      Environment="INSTANA_AGENT_KEY=*****"
       

4. 서버리스 추적을 위해 ` NGINX ` 구성을 편집합니다:

   1. 필요한 추출된 모듈의 이름에 따라 ' libinstana_sensor_ssl1.1x.so ' 또는 ' libinstana_sensor_ssl3x.so '의 이름을 ' libinstana_sensor.so '로 바꾸거나 ' nginx.conf ' 파일의 ' opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json; ' 줄을 업데이트합니다.

   2. 이러한 환경 변수를 허용하도록 ' nginx.conf ' 파일에 ' env INSTANA_ENDPOINT_URL; ' 및 ' env INSTANA_AGENT_KEY; ' 줄을 추가합니다.

      # The following line adds the basic module Instana uses to get tracing data.
      # It is required that you use the version of this module built by Instana,
      # rather than the one shipped in many NGINX distros, as there are some
      # modifications in the Instana version that are required for tracing to work
      load_module modules/ngx_http_opentracing_module.so;
      
      # Whitelists environment variables used for tracer configuration to avoid
      # that NGINX wipes them. This is only needed if instana-config.json
      # should contain an empty configuration with "{}" inside to do the
      # configuration via these environment variables instead.
      env INSTANA_SERVICE_NAME;
      env INSTANA_AGENT_HOST;
      env INSTANA_AGENT_PORT;
      env INSTANA_MAX_BUFFERED_SPANS;
      env INSTANA_DEV;
      # Serverless tracing:
      env INSTANA_ENDPOINT_URL;
      env INSTANA_AGENT_KEY;
      
      events {}
      
      error_log /dev/stdout info;
      
      http {
      error_log /dev/stdout info;
      
      # The following line loads the Instana libsinstana_sensor library, that
      # gets the tracing data from ngx_http_opentracing_module.so and converts
      # them to Instana AutoTrace tracing data.
      # The content of instana-config.json is discussed as follows.
      opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;
       

5. NGINX 프로세스를 다시 시작하거나 다음 reload 명령을 실행하여 구성을 다시 불러오십시오.

Instana ( AutoTrace ) 웹훅은 Kubernetes 및 Red Hat OpenShift 에서 NGINX 에 대한 분산 추적을 자동으로 구성할 수 있으며, 다음과 같은 제한 사항이 있습니다:

• Instana AutoTrace 웹훅은 NGINX 1.19 버전 이상을 지원합니다.
• Instana AutoTrace 웹훅은 아직 OpenResty 를 지원하지 않습니다.
• Instana AutoTrace 웹훅은 독립형 NGINX 에서 ConfigMap 의 사용을 지원하지 않습니다.

자세한 내용은 ‘ NGINX 및 ingress-nginx에 대한 웹훅 계측 활성화’를 참조하세요.

Instana ( AutoTrace ) 웹훅을 사용하면 Kubernetes 및 Red Hat OpenShift 에서 Ingress( NGINX )와 NGINX 에 대한 분산 추적을 자동으로 구성할 수 있습니다. NGINX 의 자동 추적 기능이 활성화되면, 웹훅은 앞서 언급한 구성 스니펫과 추적 바이너리를 NGINX 및 Ingress NGINX 컨테이너의 구성에 자동으로 삽입합니다.

Kubernetes 의 Ingress( NGINX )는 OpenTracing 프로젝트를 통해 분산 추적을 지원합니다. Instana 에이전트는 Jaeger 및 Zipkin 의 트레이스도 수집할 수 있으므로, NGINX 인그레스를 구성하여 트레이스가 Instana 로 전달되도록 설정할 수 있습니다.

NGINX 추적을 비활성화하려면, NGINX 구성 파일에서, opentracing_load_tracer, 및 opentracing_propagate_context 지시문과 load_module함께 Instana 관련 환경 변수(예: INSTANA_SERVICE_NAME 또는 INSTANA_AGENT_HOST)를 제거하십시오. 또한, 해당 디렉터리에서 트레이싱 라이브러리와 파일을 instana-config.json 삭제하십시오.

load_module modules/ngx_http_opentracing_module.so;

env INSTANA_SERVICE_NAME;
env INSTANA_AGENT_HOST;
env INSTANA_AGENT_PORT;
env INSTANA_MAX_BUFFERED_SPANS;
env INSTANA_DEV;

opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;

opentracing_propagate_context;

Instana 추적기는 로그 항목을 NGINX 의 표준 오류 출력으로 기록합니다. 해당 행에는 [lis]접두부가 있습니다.

autotrace-mutating-webhook을 사용한 자동 계측의 경우, NGINX 의 자동 추적에 포함된 바이너리 파일의 로그를 활용하여 문제를 해결하십시오. 더 세분화된 정보와 상황을 명확히 전달하기 위해 이 로그들을 IBM 지원팀에 공유하실 수도 있습니다. 자동 인스트루멘테이션에는 두 개의 바이너리 파일, 즉 libinstana_init 라이브러리와 실행 파일이 watcher_nginx사용됩니다.

• libinstana_sensor에 대한 로그 파일은 /tmp/instana/lii_logs/$PID.log에 있습니다.
• watcher_nginx에 대한 로그 파일은 /tmp/instana/iwn_logs/$PID.log에 있습니다.

여기서 $PID 는 관련된 프로세스의 프로세스 ID를 나타냅니다.

로그 레벨은 기본적으로 error 로 설정됩니다. NGINX 를 다른 로깅 수준으로 배포하려면 환경 변수를 설정하여 로깅 수준을 변경하십시오.

libinstana_init 라이브러리의 경우 다음 환경 변수를 설정하십시오.

INSTANA_LII_LOG_LEVEL=debug
 

watcher_nginx 실행 파일의 경우 다음 환경 변수를 설정하십시오.

INSTANA_IWN_LOG_LEVEL=debug
 

NGINX 센서의 경고 및 오류는 Instana 에이전트 서비스의 로그에서 확인할 수 있습니다. 최신 로그 항목을 보려면 다음 명령을 실행하십시오.

systemctl status instana-agent
 

Instana 에이전트 서비스의 전체 로그를 확인하려면 다음 명령을 실행하십시오:

sudo journalctl -xeu instana-agent.service
 

관찰 사항: AutoTrace 계측 기능을 활성화한 후, Kubernetes Ingress NGINX 포드에서 한 번의 재시작이 기록되었습니다:

NAME READY STATUS RESTARTS AGE ingress-nginx-controller-xxxxx 1/1 Running 1 (2m ago) 5m  

원인: 이번 재시작은 정상적인 동작입니다. 기존 Ingress NGINX 배포 환경에 계측 기능을 적용할 때는 Pod와 ConfigMap 가 별도로 계측됩니다. Pod는 먼저 기존 ConfigMap, 를 시작하고, 그 다음 ConfigMap 를 OpenTracing 구성으로 업데이트합니다. NGINX 이러한 변경 사항은 핫 리로드할 수 없으며, 새로운 추적 구성을 적용하려면 재시작이 필요합니다.

문제: NGINX 또는 Kubernetes Ingress NGINX 에 Instana AutoTrace 웹훅이 적용된 경우, 로그에 다음과 같은 오류 메시지가 표시됩니다:

dlopen() "/opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so" failed (Error loading shared library /opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so: No such file or directory) in /tmp/nginx/nginx-cfg33744904:20 nginx: [emerg] dlopen() "/opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so" failed (Error loading shared library /opt/instana/instrumentation/nginx/tracing/ngx_http_opentracing_module.so: No such file or directory) in /tmp/nginx/nginx-cfg33744904:20 nginx: configuration file /tmp/nginx/nginx-cfg33744904 test failed  

원인: 배포가 완전히 준비되기 전에 ConfigMap 이 업데이트될 때 발생할 수 있는 드문 경합 상태입니다. CrashLoopBackOff이 상태에서 ` NGINX `는 파일 시스템에 아직 존재하지 않는 추적 파일을 불러오려고 시도하며, 이로 인해 컨트롤러 포드가 중단되거나. 상태로 진입하게 됩니다.

해결 방법: 포드를 삭제한 후 다시 시작하십시오.

kubectl delete pod <pod-name> -n <namespace>

배포 컨트롤러가 포드를 다시 생성하면, 포드가 성공적으로 시작됩니다.

모니터링 문제 유형: nginx_api_not_accessible

이 문제를 해결하려면 ‘메트릭 수집 활성화’ 섹션에 설명된 대로 Instana 에이전트를 구성하여 모든 NGINX 메트릭을 수집하는 방법을 참조하십시오.

모니터링 문제 유형: nginx_status_not_accessible

이 문제를 해결하려면 ‘메트릭 수집 활성화’ 섹션에 설명된 대로 Instana 에이전트를 구성하여 모든 NGINX 메트릭을 수집하는 방법을 참조하십시오.

모니터링 문제 유형: nginx_api_not_found

이 문제를 해결하려면 ‘메트릭 수집 활성화’ 섹션에 설명된 대로 Instana 에이전트를 구성하여 모든 NGINX 메트릭을 수집하는 방법을 참조하십시오.

모니터링 문제 유형: nginx_status_not_found

이 문제를 해결하려면 ‘메트릭 수집 활성화’ 섹션에 설명된 대로 Instana 에이전트를 구성하여 모든 NGINX 메트릭을 수집하는 방법을 참조하십시오.

모니터링 문제 유형: nginx_config_location_not_discovered

이 문제를 해결하려면 ‘메트릭 수집 활성화’ 섹션에 설명된 대로 Instana 에이전트를 구성하여 모든 NGINX 메트릭을 수집하는 방법을 참조하십시오.

문제: Lua 코드에서 발행된 사용자 정의 ` HTTP ` 요청은 자동으로 추적할 수 없습니다.

$http_traceparent해결 방법: 추적 연속성을 보장하려면, 발신(outbound) ` W3Ctraceparent ` 헤더가 해당 ` NGINX ` 변수에서 전달되어야 합니다. NGINX 의 Tracer는 스팬 ID를 자동으로 업데이트합니다.

HTTP 클라이언트 lua-resty-http ( 0.18.0 및 이후 버전)에서 이 기능을 지원합니다.

lua-resty-http최신 버전을 사용하면, 다음 예제에서 볼 수 있듯이 해당 함수를 호출하는 코드는 변경할 필요가 없습니다:

local http = require "resty.http"
local http_c = http.new()
local response, error = http_c:request_uri(request_url, {
    method = "GET",
})

NGINX 센서( 1.1.89 및 이후 버전)에는 설치된 lua-resty-http 센서가 이 기능을 지원하는지 확인하는 기능이 포함되어 있습니다. 그렇지 않은 경우, 센서가 모니터링 이벤트를 resty_http_no_tracing 발생시킵니다. 이 기능은 전환 및 디버깅에 도움이 됩니다.

Instana 에이전트 구성 파일(<agent_install_dir>/etc/instana/configuration.yaml)에서 다음과 같이 이 기능을 활성화하십시오:

com.instana.plugin.nginx:
  openresty:
    tracing:
      enabled: true  # Default is false. Enable this if tracing OpenResty LUA HTTP requests is wanted in general.
      check_resty_http: true  # Default is false. Enable this and "enabled" above for letting this sensor check if installed `lua-resty-http` has W3C traceparent header support.

사용 중인 Lua HTTP 클라이언트가 상용 제품이라 이 기능을 지원하지 않는다면, 다음의 대체 방법을 사용하십시오:

local http = require "resty.http"
local http_c = http.new()
local req_headers = {}
if ngx.var.http_traceparent then
    req_headers["traceparent"] = ngx.var.http_traceparent
end
local response, error = http_c:request_uri(request_url, {
    method = "GET",
    headers = req_headers,
})

문제: NGINX 센서가 지원되지 ngx.var.http_traceparent 않는 파일을 http.lualua-resty-http 감지했습니다.

해결 방법: 앞 섹션에 설명된 대로 최신 버전으로 업데이트하고 lua-resty-http , Lua 코드에서 헤더를 설정하기 X-INSTANA-T/-S/-L 위해 이전에 적용했던 임시 해결책을 제거하십시오.

문제: ` NGINX `에 대한 호출이 추적되지 않으며, ` NGINX ` 오류 파일에는 다음 오류가 표시됩니다:

/etc/nginx/modules/ngx_http_opentracing_module.so: failed to map segment from shared object: Permission denied

해결 방법: SELinux는 ` NGINX ` 프로세스가 공유 객체인 ` OpenTracing ` 모듈의 메모리를 읽고 매핑하는 것을 차단합니다. SELinux가 오류의 원인인지 확인하기 위해 다음과 같이 스모크 테스트를 수행할 수 있습니다.

1. 일시적으로 SELinux 사용 안함
2. NGINX 를 다시 시작하세요

SELinux를 비활성화하고 ` NGINX `를 재시작하면, ` NGINX ` 오류 로그에서 오류 메시지가 사라지며 ` Instana `가 호출을 추적할 수 있게 됩니다.

SELinux를 사용 안함으로 설정하는 것은 장기적인 솔루션이 아닙니다. 올바르고 안전한 방법은 ` NGINX ` 프로세스가 ` OpenTracing ` 모듈의 메모리를 읽고 매핑할 수 있도록 허용하는 SELinux 정책을 생성하는 것입니다. NGINX 구성 디렉터리를 확인하면 OpenTracing 모듈을 찾을 수 있습니다. NGINX 의 구성 디렉터리가 인 경우 /etc/nginx, 해당 모듈은 /etc/nginx/modules 디렉터리에 위치합니다. DevOps 이나 IT 부서에서 SELinux를 설정해야 합니다. 자세한 내용은 Instana 에서 지원하는 일부 Linux 배포판의 SELinux 구성을 설명하는 다음 온라인 자료를 참조하십시오:

• Red Hat 의 SELinux
• Debian 의 SELinux
• Ubuntu의 SELinux

NGINX 와 SELinux 통합에 대한 자세한 내용은 “ NGINX 및 NGINX Plus와 SELinux 함께 사용하기”를 참조하십시오.

문제 : NGINX 에서 구성된 FastCGI 에 대해 OpenTracing 컨텍스트 전파가 작동하지 않습니다.

솔루션: 모든 FastCGI 구성 블록에서 opentracing_propagate_context 지시문을 opentracing_fastcgi_propagate_context 지시문으로 바꾸십시오.

문제 : docker.io 이미지와 같은 일부 NGINX 이미지는 restricted-v2 보안 컨텍스트를 사용하는 nginx:1.24.0OpenShift 환경과 호환되지 않습니다.

원인 :

OpenShift restricted-v2 다음과 같은 제한 사항이 있습니다:

• 0그룹 쓰기 권한이 없습니다: ` NGINX `는 일반 사용자(루트 권한이 없는 사용자)로 실행됩니다(예: 사용자 ID 1000650000 및 그룹 ID). 따라서 수정이 필요한 모든 파일과 디렉토리에는 그룹 쓰기 권한이 부여되어 있어야 합니다. 여기에는 autotracing 구성 요소에 watcher_nginx 의해 패치되는 파일이 /etc/nginx/nginx.conf 포함됩니다.

• 권한 상승이 차단되었습니다 : OpenShift restricted-v2 환경에서는 권한 상승이 허용되지 않습니다. NGINX 포드는 이미 일반 사용자로 실행되고 있으므로, NGINX 구성에서 사용자 ID를 101 지정하는 NGINX 지시어를 user nginx; 삭제해야 합니다.

• CAP_NET_BIND_SERVICELinux 의 모든 기능이 제거되었습니다. 그 결과, 포트 80과 같이 1024 미만의 포트를 수신 대기할 bind() error 13: permission denied 경우, 파일이 없어 오류가 발생합니다.

해결 방법 : NGINX 의 자동 추적 기능이 올바르게 작동하도록 하려면:

• nginx.conf런타임 데이터 및 에 chmod -R g+w 대해 그룹 쓰기 권한을 부여합니다.
• userNGINX 지시문을 사용하지 마십시오.
• 1024 미만의 포트는 사용하지 마십시오.