튜토리얼: NGINX를 사용하여 애플리케이션에 OpenTelemetry 구성하기

Akash Ananthanarayanan기술 마케팅 매니저 | F5 NGINX

웹 애플리케이션과 인프라를 더욱 효과적으로 추적할 도구를 찾고 있다면 OpenTelemetry가 적합할 수 있습니다. 기존 OpenTelemetry NGINX 커뮤니티 모듈을 사용해 NGINX 서버를 계측하면 메트릭, 트레이스, 로그를 수집하고 서버 상태를 더욱 명확하게 파악할 수 있습니다. 이를 통해 문제를 해결하고 웹 애플리케이션을 최적화하여 성능을 향상할 수 있습니다. 하지만 이 기존 커뮤니티 모듈은 추적에 필요한 성능 오버헤드로 인해 서버의 응답 시간을 늦출 수도 있습니다. 또한 이 과정에서 추가 리소스가 소모되어 CPU 및 메모리 사용량이 증가할 수 있습니다. 게다가 모듈을 설치하고 구성하는 작업도 번거로울 수 있습니다.

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

NGINX 네이티브 OpenTelemetry 모듈은 NGINX Plus에 별도로 패키징할 필요가 없는 동적 모듈입니다. API 및 키-값 저장소 모듈을 비롯한 다양한 기능을 제공합니다. 이러한 기능은 함께 작동하여 NGINX Plus 인스턴스의 성능을 모니터링하고 최적화하기 위한 완전한 솔루션을 제공합니다. ngx_otel_module을 사용하면 웹 애플리케이션의 성능에 관한 유용한 인사이트를 얻고 이를 개선하기 위한 조치를 취할 수 있습니다. 더 나은 결과를 달성하는 데 어떻게 도움이 되는지 알아보려면 ngx_otel_module을 살펴보시기를 적극 권장합니다.

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

튜토리얼 개요

이 블로그에서는 NGINX Plus에서 OpenTelemetry를 구성하고 Jaeger 도구를 사용하여 트레이스를 수집하고 시각화하는 방법을 단계별로 안내합니다. OpenTelemetry는 지연 시간, 요청 세부 정보, 응답 데이터 등 유용한 정보를 포함하여 요청 경로를 종합적으로 파악할 수 있게 해주는 강력한 도구입니다. 이는 성능을 최적화하고 잠재적인 문제를 식별하는 데 매우 유용합니다. 구성을 간소화하기 위해 OpenTelemetry 모듈, 애플리케이션, Jaeger를 하나의 인스턴스에 모두 설정했으며, 아래 다이어그램에서 이를 확인할 수 있습니다.

그림 1: NGINX OpenTelemetry 아키텍처 개요

이 튜토리얼을 완료하려면 다음 섹션의 단계를 따르세요:

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

사전 요구 사항

• Linux/Unix 환경 또는 이와 호환되는 환경
• NGINX Plus 구독
• Linux 명령줄 및 JavaScript에 대한 기본적인 이해
• Docker
• Node.js 19.x 이상
• Curl

NGINX Plus 배포 및 OpenTelemetry 모듈 설치

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

1. NGINX Plus 설치하기: 지원되는 운영 체제.
2. Install ngx_otel_module을 설치합니다. OpenTelemetry를 활성화하려면 NGINX 구성 디렉터리에 동적 모듈을 추가합니다:

load_module modules/ngx_otel_module.so;

1. 모듈을 활성화하려면 NGINX를 다시 로드합니다:

nginx -t && nginx -s reload

Jaeger와 echo 애플리케이션 배포

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

1. Use 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"

1. Jaeger 올인원 추적 및 http-echo 애플리케이션을 설치하려면 다음 명령어를 실행하세요:

'docker-compose up -d'

1. 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에 액세스할 수 있습니다. 현재 시스템 추적 데이터가 콘솔로 전송되고 있으므로 바로 확인하지 못할 수도 있습니다. 하지만 걱정하지 마세요! 추적 데이터를 OpenTelemetry 프로토콜(OTLP) 형식으로 내보내면 이 문제를 빠르게 해결할 수 있습니다. 다음 섹션에서는 추적 데이터를 Jaeger로 전송하도록 NGINX를 구성하면서 이 방법을 알아보겠습니다.

추적을 위해 NGINX에서 OpenTelemetry 구성

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

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

OpenTelemetry 지시문 및 변수

NGINX에는 특정 요구 사항에 맞게 OpenTelemetry 배포를 한층 더 최적화할 수 있도록 지원하는 새로운 지시어가 추가되었습니다. 이러한 지시어는 애플리케이션의 성능을 향상하고 그 어느 때보다 효율적으로 운영할 수 있도록 설계되었습니다.

모듈 지시어:

1. otel_exporter – 다음을 포함한 OpenTelemetry 데이터의 매개변수를 설정합니다: endpoint, interval, batch size, batch count. 이러한 매개변수는 데이터를 성공적으로 내보내는 데 매우 중요하므로 정확하게 정의해야 합니다.
2. otel_service_name – 구성 및 추적을 개선하기 위해 OpenTelemetry 리소스의 서비스 이름 속성을 설정합니다.
3. otel_trace – 이제 변수를 지정하여 OpenTelemetry 추적을 활성화하거나 비활성화할 수 있습니다. 이를 통해 추적 설정을 유연하게 관리할 수 있습니다.
4. otel_span_name – OpenTelemetry 스팬의 이름은 기본적으로 요청의 로케이션 이름으로 설정됩니다. 이 이름은 사용자 지정이 가능하며 필요에 따라 변수를 포함할 수 있습니다.

구성 예시

다음은 NGINX Plus 키-값 저장소를 사용하여 NGINX에서 OpenTelemetry를 구성하는 방법의 예입니다. NGINX Plus 키-값 저장소 모듈을 활용하면 OpenTelemetry 스팬과 기타 OpenTelemetry 속성을 동적으로 구성할 수 있어 추적 및 디버깅 프로세스를 간소화할 수 있습니다.

다음은 키-값 저장소를 사용하여 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;
          } 
      }
  }

다음은 키-값 저장소를 사용하여 OpenTelemetry 추적을 동적으로 비활성화하는 예시입니다:

location /api {
              api write=off;
          } 

다음은 NGINX OpenTelemetry 스팬 속성 구성의 예입니다:

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>

구성 테스트

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

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": {}

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

그림 2: Jaeger 대시보드

1. 특정 트레이스를 더욱 상세하고 종합적으로 분석하려면 사용 가능한 개별 트레이스 중 하나를 클릭하세요. 그러면 선택한 트레이스에 관한 유용한 정보를 확인할 수 있습니다. 아래 트레이스에서는 OpenTelemetry 지시문의 스팬 속성과 트레이스의 비지시문을 모두 검토하여 해당 데이터를 더 잘 이해할 수 있습니다.
   • demo – OTel – OpenTelemetry 스팬 속성 이름
   • http.status_code 필드 – 200 – 성공적으로 생성되었음을 나타냅니다
   • otel.library.name – nginx – OpenTelemetry 서비스 이름

그림 3: OpenTelemetry 트레이스 상세 분석

Under 태그에서 다음 속성을 확인할 수 있습니다:

결론

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

NGINX Plus R18에서 도입된 OpenTracing 모듈은 현재 지원이 중단되었으며 NGINX Plus R34부터 제거될 예정이지만, 그때까지는 모든 NGINX Plus 릴리스에서 계속 사용할 수 있습니다. 다만 NGINX Plus R29에서 도입된 OpenTelemetry 모듈을 사용하는 것이 좋습니다.

NGINX Plus를 처음 사용하신다면 지금 30일 무료 체험을 시작하거나 문의하여 사용 사례를 상담해 보세요.

작성자 소개

Akash Ananthanarayanan기술 마케팅 매니저 | F5 NGINX

Akash Ananthanarayanan의 다른 블로그 게시물