튜토리얼: NGINX를 사용하여 애플리케이션에 대한 OpenTelemetry 구성
웹 애플리케이션과 인프라를 더욱 효과적으로 추적할 수 있는 도구를 찾고 있다면 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을 탐색하여 더 나은 결과를 얻는 데 어떻게 도움이 될 수 있는지 확인해 보세요.
메모: nginx_otel_module을 설치하고 시작하는 방법에 대한 자세한 지침은 GitHub 페이지 로 이동하세요.
튜토리얼 개요
이 블로그에서는 NGINX Plus에서 OpenTelemetry를 구성하는 방법과 Jaeger 도구를 사용하여 추적을 수집하고 시각화하는 방법에 대한 단계별 가이드를 따라할 수 있습니다. OpenTelemetry는 대기 시간, 요청 세부 정보, 응답 데이터 등의 귀중한 정보를 포함하여 요청 경로에 대한 포괄적인 보기를 제공하는 강력한 도구입니다. 이는 성능을 최적화하고 잠재적인 문제를 식별하는 데 매우 유용할 수 있습니다. 일을 단순화하기 위해, 우리는 OpenTelemetry 모듈, 애플리케이션, Jaeger를 모두 하나의 인스턴스로 설정했습니다. 아래 다이어그램에서 보실 수 있습니다.
튜토리얼을 완료하려면 다음 섹션의 단계를 따르세요.
- 필수 조건
- NGINX Plus 배포 및 OpenTelemetry 모듈 설치
- Jaeger와
echo애플리케이션 배포 - 추적을 위해 NGINX에서 OpenTelemetry 구성
- 구성 테스트
필수 조건
- Linux/Unix 환경 또는 호환 가능한 환경
- NGINX Plus 구독
- Linux 명령줄 및 JavaScript에 대한 기본적인 지식
- 도커
- Node.js 19.x 이상
- 컬
NGINX Plus 배포 및 OpenTelemetry 모듈 설치
NGINX 인스턴스를 성공적으로 배포하려면 적절한 환경을 선택하는 것이 중요합니다. 이 튜토리얼에서는 NGINX Plus를 배포하고 NGINX 동적 모듈을 설치하는 방법을 안내합니다.
- 지원되는 운영 체제 에 NGINX Plus를 설치하세요 .
ngx_otel_module을설치하세요 . OpenTelemetry를 활성화하려면 NGINX 구성 디렉토리에 동적 모듈을 추가합니다.- 모듈을 활성화하려면 NGINX를 다시 로드하세요.
로드_모듈 모듈/ngx_otel_module.so;
nginx -t && nginx -s 다시 로드
Jaeger와 echo 애플리케이션 배포
추적을 보려면 다양한 옵션을 사용할 수 있습니다. 이 튜토리얼에서는 Jaeger를 사용하여 OpenTelemetry 데이터를 수집하고 분석합니다. Jaeger는 추적 데이터를 수집하고 시각화하기 위한 효율적이고 사용자 친화적인 인터페이스를 제공합니다. 데이터 수집 후에는 간단한 Docker 애플리케이션인 mendhak/http-https-echo를 배포합니다. 이 애플리케이션은 JavaScript에 대한 요청 속성을 JSON 형식으로 반환합니다.
docker-compose를사용하여 Jaeger와http-echo애플리케이션을 배포합니다. 아래 구성을 복사하여 원하는 디렉토리에 저장하면docker-compose파일을 만들 수 있습니다.버전: '3' 서비스: jaeger: 이미지: jaegertracing/all-in-one:1.41 컨테이너 이름: jaeger 포트: - "16686:16686" - "4317:4317" - "4318:4318" 환경: COLLECTOR_OTLP_ENABLED: true http-echo: 이미지: mendhak/http-https-echo 환경: - HTTP_PORT=8888 - HTTPS_PORT=9999 포트: - "4500:8888" - "8443:9999"- Jaeger 올인원 추적 및
http-echo애플리케이션을 설치합니다. 다음 명령을 실행하세요: - docker
ps -a명령을 실행하여 컨테이너가 설치되었는지 확인합니다.
'docker-compose up -d'
$docker ps -a
컨테이너 ID 이미지 명령 생성 상태
포트 이름
5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" 30시간 전 업 30시간 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일 전 업 30시간 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) 형식으로 추적 내용을 내보내면 이 문제를 빠르게 해결할 수 있습니다. 다음 섹션에서 NGINX를 구성하여 Jaeger로 추적 내용을 보내는 방법을 알아보겠습니다.
추적을 위해 NGINX에서 OpenTelemetry 구성
이 섹션에서는 키-값 저장소를 사용하여 NGINX Plus에서 OpenTelemetry 지시문을 설정하는 방법을 단계별로 보여줍니다. 이 강력한 구성을 통해 트래픽을 정확하게 모니터링하고 분석하여 애플리케이션 성능을 최적화할 수 있습니다. 이 섹션을 마치면 NGINX OpenTelemetry 모듈을 사용하여 애플리케이션 성능을 추적하는 방법을 확실히 이해하게 될 것입니다.
NGINX 구성 파일을 사용하면 원격 측정 수집을 설정하고 구성하는 것이 아주 쉽습니다. ngx_otel_module을 사용하면 사용자는 애플리케이션의 문제를 빠르게 식별하고 해결하는 데 도움이 되는 강력하고 프로토콜을 인식하는 추적 도구에 액세스할 수 있습니다. 이 모듈은 귀하의 애플리케이션 개발 및 관리 툴셋에 귀중한 추가 기능이며, 귀하의 애플리케이션의 성능을 향상시키는 데 도움이 될 것입니다. 다른 OpenTelemetry 샘플 구성을 구성하는 방법에 대해 자세히 알아보려면 ngx_otel_module 설명서를 참조하세요.
OpenTelemetry 지시문 및 변수
NGINX에는 사용자의 특정 요구 사항에 맞춰 더욱 최적화된 OpenTelemetry 배포를 달성하는 데 도움이 되는 새로운 지침이 있습니다. 이러한 지침은 애플리케이션의 성능을 향상시키고 그 어느 때보다 더 효율적으로 만들기 위해 설계되었습니다.
모듈 지침:
otel_exporter–엔드포인트,간격,배치 크기,배치 수를포함하여 OpenTelemetry 데이터의 매개변수를 설정합니다. 이러한 매개변수는 데이터를 성공적으로 내보내는 데 매우 중요하며 정확하게 정의되어야 합니다.otel_service_name– OpenTelemetry 리소스에 대한 서비스 이름 속성을 설정하여 구성과 추적을 개선합니다.otel_trace– 이제 변수를 지정하여 OpenTelemetry 추적을 활성화하거나 비활성화할 수 있습니다. 이를 통해 추적 설정을 유연하게 관리할 수 있습니다.otel_span_name– OpenTelemetry 스팬의 이름은 기본적으로 요청의 위치 이름으로 설정됩니다. 이름은 사용자 정의가 가능하며 필요에 따라 변수를 포함할 수 있다는 점도 주목할 만합니다.
구성 예제
다음은 NGINX Plus 키-값 저장소를 사용하여 NGINX에서 OpenTelemetry를 구성하는 방법의 예입니다. NGINX Plus 키-값 저장 모듈은 OpenTelemetry 범위와 기타 OpenTelemetry 속성을 동적으로 구성할 수 있는 귀중한 사용 사례를 제공하여 추적 및 디버깅 프로세스를 간소화합니다.
키-값 저장소를 사용하여 OpenTelemetry 추적을 동적으로 활성화하는 예는 다음과 같습니다.
http {
키밸 "otel.trace" $trace_switch 존=이름;
서버 {
위치 / {
otel_trace $trace_switch;
otel_trace_context 주입;
proxy_pass http://backend;
}
위치 /api {
api 쓰기=켜짐;
}
}
}
다음으로 키-값 저장소를 사용하여 OpenTelemetry 추적을 동적으로 비활성화하는 예는 다음과 같습니다.
위치 /api {
api write=off;
}
다음은 NGINX OpenTelemetry span 속성 구성의 예입니다.
사용자 nginx;
작업자 프로세스 자동;
모듈 로드 모듈/ngx_otel_module.so;
오류 로그 /var/log/nginx 디버그;
pid /var/run/nginx.pid;
이벤트 {
작업자 연결 1024;
}
http {
키밸 "otel.span.attr" $trace_attr 영역=데모;
키밸_영역 영역=데모:64k 상태=/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"';
mime.types 포함;
기본 유형 애플리케이션/json;
업스트림 에코 {
서버 로컬 호스트:4500;
존 에코 64k;
}
otel_service_name nginx;
otel_exporter {
엔드포인트 로컬 호스트:4317;
}
서버 {
수신 4000;
otel_trace 켜짐;
otel_span_name otel;
위치 /도시 {
proxy_set_header "연결" "" ;
proxy_set_header 호스트 $host;
otel_span_attr 데모 $trace_attr;
otel_trace_context 주입;
proxy_pass http://echo;
}
위치 /api {
api write=on;
}
위치 = /dashboard.html {
root /usr/share/nginx/html;
}
}
}
구성을 저장하고 NGINX를 다시 시작하려면 다음 코드를 입력하세요.
nginx -s 다시 로드
마지막으로 NGINX Plus API에 span 속성을 추가하는 방법은 다음과 같습니다.
curl -X POST -d '{"otel.span.attr": "<span 속성 이름>"}' http://localhost:4000/api/6/http/keyvals/<존 이름>
구성 테스트
이제 아래 단계에 따라 구성을 테스트할 수 있습니다.
- 추적 데이터를 생성하려면 먼저 터미널 창을 엽니다. 다음으로, 이 명령을 입력하여 데이터를 생성하세요.
$ curl -i 로컬호스트:4000/도시출력은 다음과 같습니다.
HTTP/1.1 200 OK 서버: nginx/1.25.3 날짜: 수, 2023년 11월 29일 20:25:04 GMT 콘텐츠 유형: application/json; charset=utf-8 콘텐츠 길이: 483 연결: keep-alive X-Powered-By: 익스프레스 ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I" { "경로": "/도시", "헤더": { "호스트": "로컬호스트", "연결": "닫기", "사용자 에이전트": "curl/7.81.0", "수락": "*/*", "추적 부모": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00" }, "메소드": "GET", "body": "", "fresh": false, "hostname": "localhost", "ip": "::ffff:172.18.0.1", "ips": [], "protocol": "http", "query": {}, "subdomains": [], "xhr": false, "os": { "hostname": "e55d9c00a158" }, "connection": {} - 이제 OTLP 내보내기 기능이 제대로 작동하는지 확인하고 추적에 액세스할 수 있는지 확인해야 합니다. 먼저 브라우저를 열고
http://localhost:16686에서 Jaeger UI에 접속하세요. 페이지가 로드되면 제목 표시줄에 있는 검색 버튼을 클릭하세요. 여기서 서비스 필드의 드롭다운 메뉴에서 NGINX 로 시작하는 서비스를 선택합니다. 그런 다음 작업 이라는 드롭다운 메뉴에서 Otel 이라는 이름의 작업을 선택합니다. 문제를 더 쉽게 식별하려면 '추적 찾기' 버튼을 클릭해 추적을 시각화하세요. - 특정 추적에 대한 더욱 자세하고 포괄적인 분석을 보려면 사용 가능한 개별 추적 중 하나를 클릭하세요. 이를 통해 선택한 추적에 대한 귀중한 통찰력을 얻을 수 있습니다. 아래 추적에서는 OpenTelemetry 지시어 span 속성과 추적의 비지시어를 모두 검토하여 해당 데이터를 더 잘 이해할 수 있습니다.
데모 – OTel– OpenTelemetry span 속성 이름http.status_code 필드 – 200– 성공적인 생성을 나타냅니다.otel.library.name – nginx– OpenTelemetry 서비스 이름
태그 에서 다음과 같은 속성을 볼 수 있습니다.
결론
NGINX는 이제 복잡한 애플리케이션 환경에서 요청과 응답을 추적하는 데 있어 중요한 개발인 OpenTelemetry에 대한 기본 제공 지원 기능을 제공합니다. 이 기능은 프로세스를 간소화하고 원활한 통합을 보장하여 개발자가 자신의 애플리케이션을 모니터링하고 최적화하기가 훨씬 쉬워집니다.
NGINX Plus R18에서 도입된 OpenTracing 모듈은 더 이상 지원되지 않으며 NGINX Plus R34부터 제거되지만, 그때까지 모든 NGINX Plus 릴리스에서 계속 사용할 수 있습니다. 하지만 NGINX Plus R29에 도입 된 OpenTelemetry 모듈을 사용하는 것이 좋습니다.
NGINX Plus를 처음 사용하시는 경우 오늘 30일 무료 체험판을 시작하거나 당사에 문의하여 사용 사례에 대해 논의해보세요 .
"이 블로그 게시물에는 더 이상 사용할 수 없거나 더 이상 지원되지 않는 제품이 참조될 수 있습니다. 사용 가능한 F5 NGINX 제품과 솔루션에 대한 최신 정보를 보려면 NGINX 제품군을 살펴보세요. NGINX는 이제 F5의 일부가 되었습니다. 이전의 모든 NGINX.com 링크는 F5.com의 유사한 NGINX 콘텐츠로 리디렉션됩니다."