Graylog REST API 이용하기

Graylog REST API

• Graylog REST API는 Graylog에 저장된 로그를 확인할 수 있는 가장 효과적이고 확실한 방법이다. 일반적인 목적이라면 Graylog Web Interface 만으로 충분하지만 타시스템과 연계된 자동화를 수행할 경우 Graylog REST API를 통해 웹 인터페이스에 제공되는 것과 동일한 모든 작업을 수행할 수 있다. (실제로 Graylog Web Interface 또한 모든 기능이 Graylog REST API를 사용하여 작동한다.)
• Graylog REST API의 장점은 백엔드에 위치한 Elasticsearch의 클러스터나 인덱스 등의 로우 레벨 성격의 정보를 몰라도 원하는 로그를 조회할 수 있다는 것이다. 개발자는 로그 조회 기능 자체에 집중할 수 있다.
• Graylog REST API가 제공하는 모든 기능은 온라인 문서에서 확인할 수 있다. 운영 중인 Graylog 노드 주소 뒤에 /api/api-browser를 추가하여 브라우저에서 접속하면 온라인 문서를 확인할 수 있다.

인증

• Graylog REST API는 Basic Auth 방식의 사용자 인증을 지원한다. curl 요청시 아래와 같이 손쉽게 사용자 이름과 비밀번호를 입력하면 된다.
• 인증 정보가 외부에 유출되면 Graylog의 모든 것을 변경할 수 있으므로 권한을 조회 기능으로 제한하는 사용자 계정을 따로 발급하는 것이 보안상 권장된다.

curl --request GET \
  --url 'https://{graylog-server-node}/api/cluster?pretty=true' \
  --header 'Authorization: Basic c3VwZXI6Z2FzYW4z' \
  --header 'Accept: application/json'

CORS 허용하기

• Graylog Web Interface는 Gray REST API를 웹 브라우저 상에서 바로 AJAX로 호출할 수 있다. 이는 Graylog 서버에서 해당 Origin를 허용하는 CORS 정책이 기본적으로 설정되어 있기 때문이다. 만약 임의의 원격지에 AJAX 요청을 허가하려면 Graylog 서버 노드의 환경설정 파일의 아래 내용을 수정하면 된다.

$ nano /etc/graylog/server/server.conf
rest_enable_cors=true

조회 API 목록

• Graylog REST API의 수요는 대부분 단순 로그 조회에 해당할 것이다. 조회 기능은 로그의 대상 시간 범위를 검색하는 방식에 따라 크게 relative, absolute, keyword 3개로 구분되어 제공한다. 웹 인터페이스의 그 것과 완전히 동일하다.
• 각 방식에서 다시 8개의 공통된 조회 기능을 제공한다. 목록은 아래와 같다.

GET /search/universal/{relative|absolute|keyword}
GET /search/universal/{relative|absolute|keyword}/export
GET /search/universal/{relative|absolute|keyword}/fieldhistogram
GET /search/universal/{relative|absolute|keyword}/histogram
GET /search/universal/{relative|absolute|keyword}/stats
GET /search/universal/{relative|absolute|keyword}/terms
GET /search/universal/{relative|absolute|keyword}/terms-histogram
GET /search/universal/{relative|absolute|keyword}/termsstats

GET /search/universal/{time_frame_selector}/stats

• stats 조회는 특정 기간 범위에 대한 로그 통계를 산출할 수 있다.
• field 파라메터는 통계를 산출할 대상 필드명을 지정한다. 정확히 하나의 필드만 지정할 수 있으며 해당 필드가 존재하는 로그 만을 대상으로 통계를 산출한다.
• query 파라메터는 통계를 산출할 대상 로그에 대한 쿼리를 지정한다.
• from 파라메터에는 조회할 시간 범위의 시작 일시를 지정한다. (ex: 2018-05-01 00:00:00)
• to 파라메터에는 조회할 시간 범위의 종료 일시를 지정한다. (ex: 2018-05-02 00:00:00)
• 응답의 예는 아래와 같다. 필드 타입이 문자열일 경우 count, cardinality만 산출되며 필드 타입이 숫자일 경우 mean, min, max도 추가적으로 산출할 수 있다.

{
  "time": 31,
  "count": 600,
  "sum": 5791,
  "sum_of_squares": 415233,
  "mean": 9.651666666666667,
  "min": 1,
  "max": 225,
  "variance": 598.9003305555556,
  "std_deviation": 24.472440224782563,
  "cardinality": 53
}

GET /search/universal/{time_freame_selector}/terms

• terms 조회는 특정 기간 범위에 대한 특정 필드 단위의 로그 순위 및 카운트를 산출할 수 있다.
• field 파라메터는 순위 및 카운트를 산출할 대상 필드명을 지정한다. 정확히 하나의 필드 만을 지정할 수 있다. 예를 들어 request_url라는 필드를 명시하면 해당 필드에 기록된 전체 값의 목록, 각 값의 누적 카운트를 카운트 순위로 산출해준다.
• stacked_fields 파라메터는 특정 필드의 기준을 단일 필드에서 복합 필드로 확장해주는 역할을 한다. 생략이 가능한 옵션 파라메터이다. (ex: request_method)
• size 파라메터는 순위를 산출할 필드 값의 최대 개수를 지정한다. 내림차순으로 값이 큰 필드 값부터 산출된다. 생략이 가능한 옵션 파라메터이다. (ex: 5)
• query 파라메터는 순위 및 카운트를 산출할 대상 로그에 대한 쿼리를 지정한다.
• from 파라메터는 조회할 시간 범위의 시작 일시를 지정한다. (ex: 2018-05-01 00:00:00)
• to 파라메터는 조회할 시간 범위의 종료 일시를 지정한다. (ex: 2018-05-02 00:00:00)
• 응답의 예는 아래와 같다.

{
  "time": 21,
  "terms": {
    "/v1/users - GET": 146,
    "/v1/users/101 - GET": 313,
    "/v1/users - POST": 174,
    "/v1/users - PUT": 172,
    "/v1/users - DELETE": 79
  },
  "missing": 0,
  "other": 939,
  "total": 1823
}

• terms 응답 오브젝트에는 키로 {field_value} - {stacked_field_value} 문자열을, 값으로 카운트 숫자가 담겨있다. 응답되는 키의 순서는 특정 기준으로 정렬되지 않은채 응답됨을 고려해야 한다.
• total 응답 필드에는 해당 쿼리 조건으로 대상 필드가 조회된 카운트가 담겨 있다.
• other 응답 필드에는 응답에서 제외된 나머지 카운트가 담겨있다. 만약 챠트로 표현한다면 기타(etc)에 해당하는 숫자이다.

GET /search/universal/{time_frame_selector}/histogram

• histogram 조회는 특정 기간 범위에 대한 로그 통계를 연월일시분 단위로 쪼개어서 산출할 수 있다.
• query 파라메터는 통계를 산출할 대상 로그에 대한 쿼리를 지정한다.
• interval 파라메터는 로그 통계를 시간 단위로 쪼갤 기준을 지정한다. year, quarter, month, week, day, hour, minute가 가능하다. 아래 설명한 발견된 버그로 인해 day 옵션은 추천하지 않는다. (ex: hour)
• from 파라메터는 조회할 시간 범위의 시작 일시를 지정한다. (ex: 2018-05-01 00:00:00)
• to 파라메터는 조회할 시간 범위의 종료 일시를 지정한다. (ex: 2018-05-02: 00:00:00)
• 응답의 예는 아래와 같다.

{
  "interval": "hour",
  "results": {
    "1525100400": 43,
    "1525104000": 36,
    "1525107600": 43,
    "1525111200": 97,
    "1525114800": 32,
    "1525118400": 44,
    "1525122000": 1,
    "1525125600": 1,
    "1525129200": 3,
    "1525132800": 30,
    "1525136400": 104,
    "1525140000": 147,
    "1525143600": 84,
    "1525147200": 20,
    "1525150800": 246,
    "1525154400": 135,
    "1525158000": 196,
    "1525161600": 48,
    "1525165200": 69,
    "1525168800": 311,
    "1525172400": 15,
    "1525176000": 46,
    "1525179600": 21,
    "1525183200": 51
  },
  "time": 19
}

• results 응답 오브젝트에는 키로 {timestamp} 문자열이, 값에는 해당 시간대의 카운트 숫자가 담겨있다. timestamp 값은 GMT 기준이므로 해당하는 타임존으로 변환이 필요하다.

발견된 버그

• Asia/Seoul 타임존을 사용할 경우 interval을 사용하는 모든 조회 기능에서 day 옵션은 일자 범위가 잘못 산출되는 버그가 존재한다. 정식 버전에서 아직 해당 버그가 해결되지 않았으며 별도의 포크로 해결된 사례가 있다. [관련 링크] 버그 해결 전까지는 GET /search/universal/{time_frame_selector}/stats 기능을 일 단위(ex: from=2018-01-01 00:00:00&to=2018-01-02 00:00:00)로 개별 조회하여 가공하는 방법을 추천한다.

검색 가능한 필드 목록

• Graylog의 REST API로 검색 가능한 필드명은 웹 인터페이스에서 조회 가능한 것과 완전히 동일하며 query 문법 또한 완전히 동일하게 사용할 수 있다.
• 사용자 정의 필드와 별개로 검색은 가능하지만 웹 인터페이스에 노출되지 않는 유용한 필드들이 존재하는데 아래와 같다. 아래 필드를 적절히 이용하여 특정 애플리케이션이 발신한 로그를 선별하여 조회할 수 있다.

gl2_remote_ip

• gl2_remote_ip는 로그를 발신한 애플리케이션의 IP 주소를 저장한다. (ex: 192.168.0.1)

gl2_remote_port

• gl2_remote_port는 로그를 발신한 애플리케이션의 포트를 저장하다. (ex: 52932)

gl2_source_node

• gl2_source_node는 로그를 수신한 Graylog의 node_id를 저장한다. (ex: 2a182ef5-11e9-4663-a4fe-069d25139a4b)

gl2_source_input

• gl2_source_input은 로그를 수신한 input_id를 저장한다. (ex: 5a4af414c141494f1964bc91)

streams

• streams는 로그를 로그를 수신한 stream_id의 배열을 저장한다. (ex: 5a793d57db51c96bc061db3d)

_id

• _id는 최종적으로 Elasticsearch에 저장된 로그의 log_id를 저장한다. (ex: 2698c1a0-4d39-11e8-863d-98f2b38d5af4)

Chart.js를 이용한 2차 가공

• Graylog REST API를 이용하여 획득한 로그 데이터를 챠트로 가공하면 엔드 유저에게 어필할 수 있는 훌륭한 BI 정보로 탈바꿈할 수 있다. JavaScript에서 가장 많이 쓰이는 오픈 소스 챠트 라이브러리인 Chart.js를 이용하여 챠트로 변환할 수 있다. [관련 링크]
• 만약 2차 가공 역할의 언어 플랫폼이 Java 기반이라면 Chart.js 코드로 변환하는 작업은 상당히 번거로울 수 있다. Chart.java를 이용하면 이런 번거로운 작업을 손쉽게 Java의 타입 체킹의 도움을 받아 변환할 수 있다. [관련 링크]

Bootstrap을 이용한 대시보드 제작

• 앞서 언급한 Chart.js에서 더 나아가서 BI 수준의 대시보드를 제작할 수도 있다. Bootstrap 4 기반의 유려하고 직관적인 무료 대시보드 템플릿이 많이 존재한다. [관련 링크]
• Sufee Admin은 대시보드에 적합한 위젯 템플릿 모음을 제공하여 추천한다. Chart.js와 결합한 예제도 제공한다. [관련 링크]

관련 글

• Using the Graylog REST API