OpenTelemetry NGINX 모듈: 앱 추적을 위한 가이드

NGINX는 최근 요청 처리 성능 추적을 혁신적으로 개선한 OpenTelemetry 모듈인 ngx_otel_module을 개발했습니다. 이 모듈은 텔레메트리 호출을 활용하여 애플리케이션 요청과 응답을 모니터링함으로써 향상된 추적 기능을 제공합니다. 이 모듈은 NGINX 구성 파일 내에서 편리하게 설정 및 구성할 수 있어 사용자 편의성이 매우 높습니다. 이 새로운 모듈은 NGINX OSS와 NGINX Plus 사용자 모두의 요구를 충족합니다. 이 모듈은 W3C 컨텍스트 전파 및 OTLP/gRPC export 프로토콜을 지원하므로 성능 최적화를 위한 종합적인 솔루션이 됩니다.

웹 애플리케이션과 인프라를 보다 효과적으로 추적할 수 있는 도구를 찾고 있다면, OpenTelemetry 가 딱 맞는 도구일 수 있습니다. 기존 OpenTelemetry NGINX Community 모듈로 NGINX 서버를 계측하면 메트릭, 추적 및 로그를 수집하고 서버의 상태를 더 잘 파악할 수 있습니다. 이를 통해 문제를 해결하고 웹 애플리케이션을 최적화하여 성능을 개선할 수 있습니다. 그러나 이 기존 커뮤니티 모듈은 추적에 필요한 성능 오버헤드로 인해 서버의 응답 시간이 느려질 수도 있습니다. 또한 이 프로세스는 추가 리소스를 소비하여 CPU 및 메모리 사용량을 증가시킬 수 있습니다. 또한 모듈을 설정하고 구성하는 것이 번거로울 수 있습니다.

NGINX-native OpenTelemetry 모듈은 NGINX Plus와 함께 추가 패키징이 필요 없는 동적 모듈입니다. 이 모듈은 API 및 key-value stores 모듈을 비롯한 다양한 기능을 제공합니다. 이러한 기능이 함께 작동하여 NGINX Plus 인스턴스의 성능을 모니터링하고 최적화하기 위한 완벽한 솔루션을 제공합니다. ngx_otel_module을 사용하면 웹 애플리케이션의 성능에 대한 귀중한 인사이트를 얻고 성능을 개선하기 위한 조치를 취할 수 있습니다. 더 나은 결과를 얻는 데 도움이 되는 방법을 알아보려면 ngx_otel_module을 살펴볼 것을 적극 권장합니다.

참고: nginx_otel_module 설치 및 시작 방법에 대한 자세한 지침은 GitHub 페이지에서 확인할 수 있습니다.

목차

1. 자습서 개요
2. 전제 조건
3. NGINX Plus 배포 및 OpenTelemetry 모듈 설치
4. Jaeger 및 echo 애플리케이션 배포
5. 추적을 위해 NGINX에서 OpenTelemetry 구성하기
5-1. OpenTelemetry 지시어 및 변수
6. 구성 예제
7. 구성 테스트
8. 결론

1. 자습서 개요

이 포스트에서는 NGINX Plus에서 OpenTelemetry를 구성하고 Jaeger 도구를 사용하여 추적을 수집하고 시각화하는 방법에 대한 단계별 가이드를 따를 수 있습니다. OpenTelemetry는 지연 시간, 요청 세부 정보, 응답 데이터와 같은 중요한 정보를 포함하여 요청 경로에 대한 포괄적인 보기를 제공하는 강력한 도구입니다. 이는 성능을 최적화하고 잠재적인 문제를 파악하는 데 매우 유용할 수 있습니다. 작업을 간소화하기 위해 아래 다이어그램에서 볼 수 있듯이 하나의 인스턴스에 OpenTelemetry 모듈, 애플리케이션, Jaeger를 모두 설정했습니다.

자습서를 완료하려면 이 섹션의 단계를 따르세요:

  • 사전 요구 사항
  • NGINX Plus 배포 및 OpenTelemetry 모듈 설치
  • Jaeger 및 echo 애플리케이션 배포
  • 추적을 위해 NGINX에서 OpenTelemetry 구성
  • 구성 테스트

2. 전제 조건

  • Linux/Unix 환경 또는 호환되는 모든 환경
  • NGINX Plus 구독
  • Linux command line 및 JavaScript에 대한 기본적인 지식
  • Docker
  • Node.js 19.x 이상
  • Curl

3. NGINX Plus 배포 및 OpenTelemetry 모듈 설치

NGINX 인스턴스를 성공적으로 배포하려면, 적절한 환경을 선택하는 것이 중요합니다. 이 자습서에서는 NGINX Plus를 배포하고 NGINX 동적 모듈을 설치하는 과정을 안내합니다.

  1. 지원되는 운영체제에 NGINX Plus를 설치합니다.
  2. ngx_otel_module을 설치합니다. 동적 모듈을 NGINX 구성 디렉터리에 추가하여 OpenTelemetry를 활성화합니다:
    load_module modules/ngx_otel_module.so;
  3. 모듈을 활성화하려면 NGINX를 reload 합니다:
    nginx -t && nginx -s reload

4. Jaeger 및 echo 애플리케이션 배포

추적을 보는 데 사용할 수 있는 다양한 옵션이 있습니다. 이 자습서에서는 Jaeger를 사용하여 OpenTelemetry 데이터를 수집하고 분석합니다. Jaeger는 추적 데이터를 수집하고 시각화할 수 있는 효율적이고 사용자 친화적인 인터페이스를 제공합니다. 데이터를 수집한 후에는 간단한 Docker 애플리케이션인 mendhak/http-https-echo를 배포합니다. 이 애플리케이션은 JavaScript에 대한 요청 속성을 JSON 형식으로 반환합니다.

1. docker-compose를 사용하여 Jaeger와 http-echo 애플리케이션을 배포합니다. 아래 구성을 복사하여 원하는 디렉터리에 저장하여 docker-compose 파일을 만들 수 있습니다.

version: '3'

Services:
  jaeger:
    image: jaegertracing/all-in-one:1.41
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      COLLECTOR_OTLP_ENABLED: true
  http-echo:
    image: mendhak/http-https-echo
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "4500:8888" 
        - "8443:9999"

2. Jaeger all-in-one 추적 및 http-echo 애플리케이션을 설치하려면 다음 명령을 실행하세요:
‘docker-compose up -d’

3. 컨테이너가 설치되었는지 확인하려면 docker ps -a 명령을 실행합니다.

$docker ps -a

CONTAINER ID   IMAGE                           COMMAND                  CREATED        STATUS

PORTS                                                                                                                                                                   NAMES

5cb7763439f8   jaegertracing/all-in-one:1.41   "/go/bin/all-in-one-…"   30 hours ago   Up 30 hours   5775/udp, 5778/tcp, 14250/tcp, 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp, 6831-6832/udp, 14268/tcp   jaeger

e55d9c00a158   mendhak/http-https-echo         "docker-entrypoint.s…"   11 days ago    Up 30 hours   8080/tcp, 8443/tcp, 0.0.0.0:8080->8888/tcp, :::8080->8888/tcp, 0.0.0.0:8443->9999/tcp, :::8443->9999/tcp                                                                ubuntu-http-echo-1

이제 브라우저에 http://localhost:16686 엔드포인트를 입력하기만 하면 Jaeger에 접속할 수 있습니다. 시스템 추적 데이터는 현재 콘솔로 전송 중이므로 바로 확인하지 못할 수도 있습니다. 하지만 걱정하지 마세요! 추적을 OTLP(OpenTelemetry Protocol) 형식으로 내보내면 이 문제를 빠르게 해결할 수 있습니다. 다음 섹션에서 Jaeger로 추적을 전송하도록 NGINX를 구성할 때 이 방법을 배우게 될 것입니다.

5. 추적을 위해 NGINX에서 OpenTelemetry 구성하기

이 섹션에서는 key-value store를 사용하여 NGINX Plus에서 OpenTelemetry 지시문을 설정하는 방법을 단계별로 설명합니다. 이 강력한 구성을 통해 트래픽을 정밀하게 모니터링하고 분석하여 애플리케이션의 성능을 최적화할 수 있습니다. 이 섹션이 끝나면 애플리케이션의 성능을 추적하기 위해 NGINX OpenTelemetry 모듈을 활용하는 방법을 확실히 이해할 수 있습니다.

텔레메트리 수집을 설정하고 구성하는 것은 NGINX 구성 파일을 통해 매우 쉽습니다. ngx_otel_module을 통해 사용자는 애플리케이션의 문제를 신속하게 식별하고 해결하는 데 도움이 되는 강력한 프로토콜 인식 추적 도구에 액세스할 수 있습니다. 이 모듈은 애플리케이션 개발 및 관리 도구 세트에 유용한 추가 기능이며 애플리케이션의 성능을 향상시키는 데 도움이 됩니다. 다른 OpenTelemetry 샘플 구성에 대해 자세히 알아보려면 ngx_otel_module 설명서를 참조하세요.

5-1. OpenTelemetry 지시어 및 변수

NGINX에는 특정 요구사항에 맞춰 더욱 최적화된 OpenTelemetry 배포를 달성하는 데 도움이 되는 새로운 지시어가 있습니다. 이 지시어는 애플리케이션의 성능을 향상시키고 그 어느 때보다 효율적으로 만들 수 있도록 설계되었습니다.

모듈 지시어:

  • otel_exporter – 엔드포인트, 간격, 배치 크기, 배치 수 등 OpenTelemetry 데이터에 대한 매개변수를 설정합니다. 이러한 매개변수는 데이터를 성공적으로 내보내는 데 매우 중요하므로 정확하게 정의해야 합니다.
  • otel_service_name – 정리 및 추적을 개선하기 위해 OpenTelemetry 리소스에 대한 서비스 이름 속성을 설정합니다.
  • otel_trace – 이제 변수를 지정하여 OpenTelemetry 추적을 활성화 또는 비활성화할 수 있습니다. 이를 통해 추적 설정을 유연하게 관리할 수 있습니다.
  • otel_span_name – 기본적으로 OpenTelemetry span의 이름이 요청의 위치 이름으로 설정됩니다. 이 이름은 사용자 정의할 수 있으며 필요에 따라 변수를 포함할 수 있다는 점에 주목할 필요가 있습니다.

6. 구성 예제

다음은 NGINX Plus key-value store를 사용하여 NGINX에서 OpenTelemetry를 구성하는 방법의 예시입니다. NGINX Plus key-value store 모듈은 OpenTelemetry 범위 및 기타 OpenTelemetry 속성을 동적으로 구성하여 추적 및 디버깅 프로세스를 간소화할 수 있는 유용한 사용 사례를 제공합니다.

다음은 key-value store를 사용하여 OpenTelemetry 추적을 동적으로 활성화하는 예시입니다:

http {
      keyval "otel.trace" $trace_switch zone=name;

      server {
          location / {
              otel_trace $trace_switch;
              otel_trace_context inject;
              proxy_pass http://backend;
          }
          location /api {
              api write=on;
          } 
      }
  }

다음은 key-value store를 사용하여 OpenTelemetry 추적을 동적으로 비활성화하는 예제입니다:

location /api {
              api write=off;
          }

다음은 NGINX OpenTelemetry span 속성 구성 예시입니다:

user  nginx;
worker_processes  auto;
load_module modules/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid   /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    keyval "otel.span.attr" $trace_attr zone=demo;
    keyval_zone zone=demo:64k  state=/var/lib/nginx/state/demo.keyval;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    include       mime.types;
    default_type  application/json;

    upstream echo {
        server localhost:4500;
        zone echo 64k;
    }

    otel_service_name nginx;

    otel_exporter {
           endpoint localhost:4317;
        }

    server {
       listen       4000;
       otel_trace on;
       otel_span_name otel;

       location /city {
            proxy_set_header   "Connection" "" ;
            proxy_set_header Host $host;
            otel_span_attr demo $trace_attr;
            otel_trace_context inject;
            proxy_pass http://echo;
       }

       location /api {
           api write=on;
       }

       location = /dashboard.html {
        root /usr/share/nginx/html;
    }
      
  }

}

구성을 저장하고 NGINX를 다시 시작하려면 다음 코드를 입력합니다:

nginx -s reload

마지막으로, NGINX Plus API에서 span 속성을 추가하는 방법은 다음과 같습니다:

curl -X POST -d '{"otel.span.attr": "<span attribute name>"}' http://localhost:4000/api/6/http/keyvals/<zone name>

7. 구성 테스트

이제 아래 단계에 따라 구성을 테스트할 수 있습니다.

1. 추적 데이터를 생성하려면 먼저 터미널 창을 엽니다. 그런 다음 다음 명령을 입력하여 데이터를 생성합니다:
curl -i localhost:4000/city

출력은 다음과 같이 표시됩니다:

HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Wed, 29 Nov 2023 20:25:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 483
Connection: keep-alive
X-Powered-By: Express
ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"

{
"path": "/city",
"headers": {
"host": "localhost",
"connection": "close",
"user-agent": "curl/7.81.0",
"accept": "*/*",
"traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
},
"method": "GET",
"body": "",
"fresh": false,
"hostname": "localhost",
"ip": "::ffff:172.18.0.1",
"ips": [],
"protocol": "http",
"query": {},
"subdomains": [],
"xhr": false,
"os": {
"hostname": "e55d9c00a158"
},
"connection": {}

2. 이제 OTLP exporter가 올바르게 작동하고 추적에 액세스할 수 있는지 확인해야 합니다. 먼저 브라우저를 열고 Jaeger UI(http://localhost:16686)에 접속합니다. 페이지가 로드되면 제목 표시줄에 있는 검색 버튼을 클릭합니다. 거기서 서비스 필드의 드롭다운 메뉴에서 NGINX로 시작하는 서비스를 선택합니다. 그런 다음 작업이라는 드롭다운 메뉴에서 Otel이라는 이름의 작업을 선택합니다. 문제를 더 쉽게 식별할 수 있도록 추적 찾기 버튼을 클릭하여 추적을 시각화합니다.

그림 2: Jaeger 대시보드

그림 2: Jaeger 대시보드

3. 특정 추적에 대한 보다 상세하고 포괄적인 분석에 액세스하려면 사용 가능한 개별 추적 중 하나를 클릭하세요. 그러면 선택한 추적에 대한 귀중한 인사이트를 얻을 수 있습니다. 아래 추적에서는 OpenTelemetry 지시어 범위 속성과 추적의 비지시어를 모두 검토할 수 있으므로 현재 데이터를 더 잘 이해할 수 있습니다.

태그에서 다음 속성을 볼 수 있습니다:

  • demo – OTel – OpenTelemetry span 속성 이름
  • http.status_code field – 200 – 성공적인 생성을 나타냅니다.
  • otel.library.name – nginx – OpenTelemetry 서비스 이름

8. 결론

이제 NGINX는 복잡한 애플리케이션 환경에서 요청과 응답을 추적하기 위한 중요한 개발 사항인 OpenTelemetry를 기본 지원합니다. 이 기능은 프로세스를 간소화하고 원활한 통합을 보장하여 개발자가 애플리케이션을 훨씬 쉽게 모니터링하고 최적화할 수 있도록 지원합니다.

NGINX Plus R18에 도입된 OpenTracing 모듈은 이제 더 이상 사용되지 않으며 NGINX Plus R34부터 제거될 예정이지만, 그 전까지는 모든 NGINX Plus 릴리스에서 계속 사용할 수 있습니다. 그러나 NGINX Plus R29에 도입된 OpenTelemetry 모듈을 사용하는 것이 좋습니다.

NGINX Plus를 처음 사용하는 경우 지금 바로 30일 무료 체험을 시작하거나 NGINX STORE에 문의하여 사용 사례에 대해 논의할 수 있습니다.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required