관찰 가능성 NGINX Unit에서 직접 확인해보세요!

관찰 가능성! 이제 NGINX Unit의 통계 엔진을 통해 지원합니다.

올해 3월, Unit 팀의 두 창립 멤버인 Valentin Bartenev와 Maxim Romanov는 NGINX Unit에 수년간의 작업과 수많은 창의성을 투입한 후 다른 기회로 옮기기로 결정했습니다.

그럼에도 불구하고 NGINX 공동 설립자 Igor Sysoev의 NGINX Unit에 대한 원래의 열망을 실현시키려는 우리의 약속과 마찬가지로 우리의 결의는 굳건합니다. 두 명의 최신 팀원인 Alejandro Colomar와 Andrew Clayton의 도착은 개발 노력을 강화하여 이제 NGINX Unit 버전 1.25에서 1.28까지의 주목할 만한 몇 가지 항목을 여러분과 공유할 수 있게 되었습니다.

목차

1. 관찰 가능성(Observability)은 이제 매우 중요합니다.
2. 더 많은 변수(Variable), 더 많은 사용 장소(Places to Use)
3. X-Forwarded-* 헤더(Header)에 대한 광범위한 지원
4. 개선된(Revamped) share 옵션
5. 관찰 가능성 다음의 계획: njs, URI 재작성(Rewrite), Action Chaining, OpenAPI

1. 관찰 가능성(Observability)은 이제 매우 중요합니다.

Unit의 주요 열망 중 하나는 항상 관찰 가능성(observability)이었고 버전 1.28.0에는 가장 기다려온 기능 중 하나인 통계 엔진(statistics engine)의 첫 번째 반복이 포함됩니다. output은 새로운 /status API endpoint에 노출됩니다.

$ curl --unix-socket /var/run/control.unit.sock http://localhost/status
{
    "connections": {
        "accepted": 1067,
        "active": 13,
        "idle": 4,
        "closed": 1050
    },

    "requests": {
        "total": 1307
    },

    "applications": {
        "wp": {
            "processes": {
                "running": 14,
                "starting": 0,
                "idle": 4
            },

            "requests": {
                "active": 10
            }
        }
    }
}

여기에 있는 대부분의 필드(field)는 자체 설명적(self‑descriptive)입니다. 연결(2행) 및 요청(9행)은 인스턴스 전체의 데이터를 제공하는 반면, 애플리케이션 객체(13행)는 /config/applications를 미러링(mirror)하여 애플리케이션과 특별히 관련된 프로세스 및 요청을 다룹니다.

3~6행은 NGINX Unit이 추적하는 연결(connection)의 네 가지 범주인 accepted, active, idle 및 closed를 보여줍니다. 프로세스 범주는 running, starting 및 idle 입니다(16-18행). 이러한 범주는 연결 및 프로세스의 내부 표현을 반영하므로 이제 서버만큼 이에 대해 알 수 있습니다.

간결해 보이죠? 지금으로서는 알 수 있는 것이 거의 전부입니다. 물론, 우리는 더 유용한 측정 항목을 노출하기 위해 노력하고 있습니다. 그러나 이미 명령줄(command line)에서 이 API를 query하여 서버에서 무슨 일이 일어나고 있는지 확인하고 output을 대시보드에 연결하거나 더 기발한 접근 방식을 선택할 수도 있습니다. 대시보드가 없으신가요? NGINX Unit팀의 계획 중 일부에는 내장된 것을 제공하는 것이 포함되어 있습니다.

2. 더 많은 변수(Variable), 더 많은 사용 장소(Places to Use)

버전 1.24 이후 도입된 변수 목록은 매우 광범위하며 $body_bytes_sent, $header_referer, $header_user_agent, $remote_addr, $request_line, $request_uri, $status 및 $time_local을 포함합니다.

이들 중 대부분은 다소 간단하지만 여기에 더 주목할만한 몇 가지가 있습니다.

  • $request_uri에는 브라우저 인코딩이 보존된 요청된 URI의 경로(path)와 쿼리(query)가 포함됩니다.
  • 비슷한 이름의 $request_line은 GET /docs/help.html HTTP/1.1과 같은 전체 요청을 저장하며 로깅(logging)을 위한 것입니다…
  • HTTP 응답 상태 코드를 포함하는 $status와 마찬가지로

눈치채셨나요? 우리는 응답(response)을 언급했습니다. 예, 우리는 그 영역으로 이동하고 있습니다. 이전 Unit 버전의 변수(variable)는 들어오는 요청(request)에 중점을 두었지만 이제는 $status 및 $body_bytes_sent와 같은 응답 속성도 캡처하는 변수가 있습니다.

변수를 사용하는 새로운 위치와 관련하여 가장 먼저 언급할 것은 새로운 사용자 지정 가능한 access log 형식입니다. NGINX Unit의 로그 항목에서 JSON을 사용하고 싶습니까? 간단한 경로 문자열을 지정하는 것 외에도 access_log 옵션은 로그 항목의 형식도 설정하는 개체가 될 수 있습니다.


{ 
    "access_log": {
        "path": "/var/log/unit/access.log", 
        "format": "{ \"remote_addr\":\"$remote_addr\", \"time\":\"$time_local\", \"request\":\"$request_line\", \"response\":\"$status\", \"header_referer\":\"$header_referer\", \"header_user_agent\":\"$header_user_agent\" }" 
    } 
}

따라서 원하는 방식으로 일반적인 로그 형식(log format)을 넘어갈 수 있습니다.

변수에 대한 두 번째 주목할만한 사용 사례는 route action의 location value입니다.

{ 
    "action": { 
        "return": 301, 
        "location": "https://$host$request_uri" 
    } 
 }

여기에서는 $request_uri를 사용하여 query part을 포함한 요청을 HTTPS를 통해 동일한 웹사이트로 릴레이(relay)합니다.

chroot 옵션은 이제 share 옵션과 마찬가지로 변수를 지원하며 이는 논리적입니다.


{ 
    "action": { 
        "share": "/www$uri",
        "chroot": "/www/data/$host/" 
    } 
}

NGINX Unit은 이제 동적 변수(dynamic variable)도 지원합니다. 요청 인수(Request argument), 쿠키(cookie) 및 헤더(header)는 변수(variable)로 노출됩니다. 예를 들어 쿼리 문자열(query string) Type=car&Color=red는 $arg_Type 및 $arg_Color라는 두 개의 인수 변수를 생성합니다. 런타임 시 이러한 변수는 동적 값(dynamic value)으로 확장됩니다. 존재하지 않는 변수(non-existent)를 참조하면 비어 있는 것으로 간주됩니다.

3. X-Forwarded-* 헤더(Header)에 대한 광범위한 지원

버전 1.25.0부터 NGINX Unit은 X-Forwarded-* 인식 정도를 포함하여 listener를 위한 일부 TLS 구성 기능을 제공했습니다. 이제 listener구성에서 클라이언트 IP 주소와 프로토콜 교체를 구성할 수 있습니다.

{
    "listeners": {
        "*:80": {
            "pass": "routes/my-app",
            "forwarded": {
                "client_ip": "X-Forwarded-For",
                "protocol": "X-Forwarded-Proto",
                "recursive": false,
                "source": [
                    "198.51.100.1-198.51.100.254",
                    "!198.51.100.128/26",
                    "203.0.113.195"
                ]
            }
        }
    },
    ...
}

참고: 이 새 구문(syntax)은 이전 client_ip 구문(syntax)을 더 이상 사용하지 않으며 향후 릴리스에서 제거됩니다.

4. 개선된(Revamped) share 옵션

NGINX Unit 버전 1.11.0은 정적 콘텐츠(static content)를 제공하기 위한 share 라우팅(routing) 옵션을 도입했습니다. NGINX의 root 지시문(directive)과 비슷합니다.

{
    "share": "/path/to/dir/"
}

처음에 share 옵션은 so-called 문서 root directory를 지정했습니다. 어떤 파일을 제공할지 결정하기 위해 Unit은 요청의 URI를 이 share 경로(path)에 추가하기만 하면 됩니다. 예를 들어 /some/file.html에 대한 간단한 GET 요청에 대한 응답으로 Unit은 /path/to/dir/some/file.html을 제공했습니다. 그래도 파일 경로(file path)를 더 세밀하게 제어해야 하는 경계 상황에 계속 부딪쳤기 때문에 진화하기로 결정되었습니다. 버전 1.26.0부터 share 옵션은 document root만이 아니라 공유 파일(shared file)의 전체 경로(entire path)를 지정합니다.

특정 파일(specific file)을 제공하시겠습니까?

{
    "share": "/path/to/a/file.html"
}

경로(path) 내에서 변수를 사용하시겠습니까? 문제 없습니다.

{
    "share": "/www/data/$host/app.html"
}

그러나 NGINX 및 이전 Unit 버전에서 이미 익숙한 동작을 모방하는 방법은 무엇입니까? 우리가 몇 단락 전에 쓸모없는 것으로 간주했던 document root를 알고 계십니까? 해결책이 있습니다.

이제 다음과 같이 구성을 다시 작성할 수 있습니다.

{
    "share": "/www/data/"
}

다음과 같이 요청된 URI를 path에 추가하지만 명시적으로!

{
    "share": "/www/data/$uri"
}

마지막으로 share 지시문(directive)은 이제 파일을 찾을 때까지 경로 배열(array of paths)을 수락(accept)할 수 있습니다.


{
    "share": [
        "/www/$host$uri",
        "/www/static$uri",
        "/www/app.html"
    ]
}

파일을 찾을 수 없으면 라우팅이 대체 작업(fallback action)으로 전달됩니다. fallback가 없으면 404(Not Found) 상태 코드가 반환됩니다.

5. 관찰 가능성 다음의 계획: njs, URI rewrite, Action Chaining, OpenAPI

이 글을 읽는 동안 NGINX Unit팀은 이미 다음 릴리스를 작업 중입니다. 여기 무슨 계획을 가지고 있는지 엿볼 수 있습니다.

먼저 NGINX에서 활발히 개발 중인 또 다른 주요 프로젝트인 NGINX JavaScript 모듈(njs)과 NGINX Unit을 통합하고 있습니다. 간단히 말해서, 이것은 NGINX Unit이 JavaScript 모듈 호출을 지원한다는 것을 의미합니다. 이걸 고려하세요.

var hellonjs = {}

hellonjs.hello = function(vars) {
    if ('unitvar' in vars) {
        return vars.unitvar;

    } else {
        return 'default';
    }
}

export default hellonjs

NGINX Unit에서 모듈을 가져온 후 구성으로 몇 가지 깔끔한 작업을 수행할 수 있습니다.

{
    "match": {
        "uri": "~(?<unitvar>.*)"
    },
    "action": {
        "share": "`/www/html${hellonjs.hello(vars)}`"
    }
}

또한, 항상 인기 있는 NGINX rewrite 지시문과 유사한 것을 도입하는 것을 목표로 하고 있습니다.

{
    "match": {
        "uri": "/app/old_path"
     },
     
    "action": {
        "rewrite": "/app/new_path",
        "pass": "routes"
    }
}

하지만 NGINX Unit팀의 계획은 여기서 멈추지 않습니다. NGINX Unit의 라우팅을 앱 자체의 output에 연결하는 것은 어떻습니까(AKA action chaining)?


{
    "action": [
        {
            "pass": "applications/auth_check"
        },
        {
            "pass": "applications/my_app"
        }
    ]
}

여기서 아이디어는 auth_check 앱이 들어오는 요청을 인증하고 결과를 나타내는 상태 코드를 반환한다는 것입니다. 인증에 성공하면 200 OK가 반환되고 요청이 my_app으로 전달됩니다.

또한 모든 NGINX Unit의 API와 그 정확한 기능을 정의하기 위해 OpenAPI 사양(specification)에 대해 작업하고 있습니다.

여전히 호기심을 충족시키기에 충분하지 않다면 로드맵을 참조하여 계획을 세밀하게 분석하십시오.

NGINX Unit 공식 커뮤니티(슬랙 채널)는 NGINX STORE – Unit Community 메뉴를 통해 가입 가능합니다.

NGINX Unit에 대한 최신 포스트와 소식을 빠르게 받으시고 싶으시면 아래 뉴스레터를 구독하세요.