Skip to main content
Version: 2.8.1

Syslog

Syslog

用途說明#

傳送請求及回應日誌至 Syslog。

note

啟用此插件前請務必要確認 Syslog daemon 有啟用，才會正常運作。

日誌格式請參考下方：日誌格式。

欄位配置說明#

啟用時可以看到以下畫面：

插件啟用配置圖

對應的配置說明如下：

參數類型預設值說明必填
log_levelstringinfo可選擇的日誌紀錄嚴重性層級。
任何請求之嚴重性比目前設定層級相等或更高的，都會記錄到系統日誌中。
可選的層級有：debug、info、notice、warning、err、crit、alert、emerg。		V
successful_severitystringinfo指派給所有成功的請求(回應狀態代碼 < 400) ，其可選擇的日誌紀錄嚴重性層級，可選的層級有：debug、info、notice、warning、err、crit、alert、emerg。

註：層級需 >= log_level所設定的層級，才會判斷紀錄，例如： log_level 設定為 info，則 successful_severity 需設定為 info 以上之層級。		V
client_errors_severitystringinfo指派給所有失敗的請求(回應狀態代碼 >= 400 且 < 500) ，其可選擇的日誌紀錄嚴重性層級，可選的層級有：debug、info、notice、warning、err、crit、alert、emerg。

註：層級需 >= log_level所設定的層級，才會判斷紀錄，例如： log_level 設定為 info，則 client_errors_severity 需設定為 info 以上之層級。		V
server_errors_severitystringinfo指派給所有失敗的請求(回應狀態代碼 >= 500)，其可選擇的日誌紀錄嚴重性層級，可選的層級有：debug、info、notice、warning、err、crit、alert、emerg。

註：層級需 >= log_level 所設定的層級，才會判斷紀錄，例如： log_level 設定為 info，則 server_errors_severity 需設定為 info 以上之層級。		V
custom_fields_by_luamapkey-value pairs 列表，其中 key 是日誌字段的名稱，value 是一段 Lua 代碼，其返回 value sets 或替換日誌字段 value。
facilitystring操作系統使用此欄位設定來決定如何處理每條日誌消息。
此欄位定義了日誌記錄時插件必須設置的設施。
可以填入的值為以下其一：auth、authpriv、cron、daemon、ftp、kern、lpr、mail、news、syslog、user、uucp、local0、local1、local2、local3、local4、local5、local6、local7。
系統預設使用 user。

用法示例#

日誌格式#

日誌使用 JSON 的格式來組成，說明如下：

  • request 包含有關客戶端發送的請求。
  • response 包含發送給客戶端的回應。
  • tries 包含負載均衡器對此請求進行的（成功和失敗）列表。
  • route 包含請求所對應之特定的 GOC API Gateway 路由設定資料。
  • service 包含請求所對應之 GOC API Gateway 路由關聯的服務設定資料。
  • authenticated_entity 如果已啟動身份認證插件，則會包含認證憑據。
  • workspaces 包含與請求的路由所屬的工作區資料。目前版本的 services 及 routes 資訊內的 ws_id 欄位會對應其所屬的 workspace ID 資訊。
  • consumer 如果已啟動身份認證插件，則會包含認證的用戶設定資料。
  • latencies 包含有關延遲的一些數據：
    • proxy 是最終服務處理請求所花費的時間。
    • kong 是運行所有插件所需的內部延遲。
    • request 是從客戶端讀取第一個字節到將最後一個字節發送到客戶端之間經過的時間。對於檢測速度較慢的客戶端很有用。
  • client_ip 包含原始客戶端 IP 地址。
  • started_at 包含開始處理請求的時間的 UTC 時區時戳。

範例：

{
"latencies": {
"request": 515,
"kong": 58,
"proxy": 457
},
"service": {
"host": "httpbin.org",
"created_at": 1614232642,
"connect_timeout": 60000,
"id": "167290ee-c682-4ebf-bdea-e49a3ac5e260",
"protocol": "http",
"read_timeout": 60000,
"port": 80,
"path": "/anything",
"updated_at": 1614232642,
"write_timeout": 60000,
"retries": 5,
"ws_id": "54baa5a9-23d6-41e0-9c9a-02434b010b25"
},
"request": {
"querystring": {},
"size": 138,
"uri": "/log",
"url": "http://localhost:8000/log",
"headers": {
"host": "localhost:8000",
"accept-encoding": "gzip, deflate",
"user-agent": "HTTPie/2.4.0",
"accept": "*/*",
"connection": "keep-alive"
},
"method": "GET"
},
"tries": [
{
"balancer_latency": 0,
"port": 80,
"balancer_start": 1614232668399,
"ip": "18.211.130.98"
}
],
"client_ip": "192.168.144.1",
"upstream_uri": "/anything",
"response": {
"headers": {
"content-type": "application/json",
"date": "Thu, 25 Feb 2021 05:57:48 GMT",
"connection": "close",
"access-control-allow-credentials": "true",
"content-length": "503",
"server": "gunicorn/19.9.0",
"via": "kong/2.2.1.0-enterprise-edition",
"x-kong-proxy-latency": "57",
"x-kong-upstream-latency": "457",
"access-control-allow-origin": "*"
},
"status": 200,
"size": 827
},
"route": {
"id": "78f79740-c410-4fd9-a998-d0a60a99dc9b",
"paths": [
"/log"
],
"protocols": [
"http"
],
"strip_path": true,
"created_at": 1614232648,
"ws_id": "54baa5a9-23d6-41e0-9c9a-02434b010b25",
"request_buffering": true,
"updated_at": 1614232648,
"preserve_host": false,
"regex_priority": 0,
"response_buffering": true,
"https_redirect_status_code": 426,
"path_handling": "v0",
"service": {
"id": "167290ee-c682-4ebf-bdea-e49a3ac5e260"
}
},
"started_at": 1614232668342
}

Custom Fields by Lua#

custom_fields_by_lua 配置允許使用 Lua 代碼動態修改日誌字段。

以下是刪除日誌中現有路由字段的範例配置：

custom_fields_by_lua.route="return nil"

同樣也可以添加新字段：

custom_fields_by_lua.header="return kong.request.get_header('h1')"

限制#

Lua 代碼運行在一個受限的沙箱環境中，其行為受 untrusted_lua 配置屬性的約束。

為了提高安全性，沙盒在 Lua 代碼的執行方式中包含幾個限制。 以下功能不可用，因為它們可以用來濫用系統：

  • string.rep：可用於在一次操作中分配數百萬 bytes。
  • {set|get}metatable：可用於修改全局對象（字符串、數字）的 metatables。
  • collectgarbage：可以被濫用來扼殺其他 workers 的效能。
  • _G：是根節點，可以訪問所有函數。它被臨時 table 所屏蔽。
  • load{file|string}：被認為是不安全的，因為它可以授予對全局環境的訪問權限。
  • raw{get|set|equal}：可能不安全，因為沙盒依賴於一些 metatable 操作。
  • string.dump：可以顯示機密的 server 信息（比如 functions 的實作內容）。
  • math.randomseed：可以影響主機系統。 GOC API Gateway 已經正確地為隨機數生成器提供 seed。
  • 所有 os.*（os.clock、os.difftime 和 os.time 除外）。 os.execute 可以顯著改變主機系統。
  • io.*：提供對硬碟驅動器的訪問。
  • dofile|require：提供對硬碟驅動器的訪問。

排除 require 意味著插件只能使用 PDK functions，像是： kong.*。

ngx.* 抽象方法也可用，但不能保證在插件的未來版本中支援。

除上述限制外：

  • 所有提供的模塊（如 string 或 table）都是唯讀的，不能修改。
  • 禁用 Bytecode 執行。

此外，由於代碼在 log phase 中運行，因此只能使用該 phase 可用的 PDK 方法。

在全局啟用插件#

  1. 從網站左邊 Menu 中 外掛插件 頁面中，點選右上角的 新增外掛插件 ：

全局啟用畫面

  1. 點選後，選擇 日誌 頁籤，並啟用 Syslog，填寫內容參考欄位配置說明，設定成功後，任何請求(不分服務、路由、用戶)的日誌都會記錄到 Syslog 上。

在服務端上啟用插件#

  1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的服務，假設為 google，點選對應的編輯按鈕：

服務啟用畫面1

  1. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

服務啟用畫面2

點選後，選擇 日誌 頁籤，並啟用 Syslog，填寫內容參考欄位配置說明，設定成功後，僅有此服務(範例為google)請求的日誌會記錄到 Syslog 上。

在路由端上啟用插件#

可以由兩種方式來選擇路由，並啟用插件：

方式一：路由列表#

  1. 從網站左邊 Menu 中 服務 > 路由列表 頁面中，選擇要啟用此插件的路由，假設為 google，點選對應的編輯按鈕 ：

路由啟用畫面1

方式二：服務 > 服務列表 > 路由列表#

  1. 從網站左邊 Menu 中 服務 > 服務列表 頁面中，選擇要啟用此插件的路由 所屬之服務(假設為 google)，點選對應的編輯按鈕。

在編輯畫面中，點選上方的 路由 頁籤，選擇要啟用此插件的路由(假設為 google)，點選對應的編輯按鈕：

路由啟用畫面2

  1. 承第1步，點擊上述兩種方式之一的編輯按鈕後，在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

路由啟用畫面3

點選新增外掛插件 按鈕後，選擇 日誌 頁籤，並啟用 Syslog，填寫內容參考欄位配置說明，設定成功後，僅有此路由(範例為google)請求的日誌會記錄到 Syslog 上。

在用戶端上啟用插件#

  1. 從網站左邊 Menu 中 訂閱用戶 > 用戶列表 頁面中，選擇要啟用此插件的用戶，假設為 portaladmin，點選對應的編輯按鈕 ：

用戶啟用畫面1

  1. 在編輯畫面中，點選上方的 外掛插件 頁籤，再點選頁籤內容上方的 新增外掛插件 按鈕：

用戶啟用畫面2

點選後，選擇 日誌 頁籤，並啟用 Syslog，填寫內容參考欄位配置說明，設定成功後，僅有此用戶(範例為 portaladmin)請求的日誌會記錄到 Syslog 上。

驗證#

  1. 請先確認 syslogd 的服務有啟用，假設目前以 docker container 方式運行，輸入以下 command：

    若無法找到目前啟動的 syslog 服務，如下：

    $ ps aux | grep 'syslog'
    38 root 0:00 grep syslog

    則需自行開啟 syslog：

    $ syslogd

    正常有開啟 syslog 的話會顯示如下：

    $ ps aux | grep 'syslog'
    42 root 0:00 syslogd
    44 root 0:00 grep syslog

  2. 啟用插件，將 log_level 設定為 info，而 successful_severity 設定為 notice，並透過 GOC API Gateway 去呼叫服務，範例如下（使用 curl 命令來測試）：

    curl -XGET < GOC API Gateway protocol>://< GOC API Gateway ip>:< GOC API Gateway port>/api/v2/users/ \
    -H 'X-API-HOST: gocv3' \
    -H 'X-API-KEY: 7338ebd5-a29c-469a-8501-ad861e1821c8' \
    -uadmin:password -i
    HTTP/1.1 200 OK
    [{"id":"2513b24e-21da-4c8a-ae41-26c1e5c96bcd","username":"demo222","email":"xxx@xxx.com","display_name":"demo222","create_time":"2020-08-21T08:55:28Z"},{"id":"25a52372-c8ce-4d02-b175-7eae8ee18ad1","username":"jop","email":"j.op@aaa.com"...(略)

    因此次請求是成功回應(狀態碼 < 400)，所以會比較 successful_severity 的層級是否 >= log_level 的層級，有符合的話，即記錄日誌到 Syslog 內。

  3. GOC API Gateway 在取得服務的回應後，會將該次的請求 & 回應之日誌，寫入 Syslog 內，假設目前以 docker container 方式運行，路徑檔案為 /var/log/messages。

    如下圖所示，即為設定驗證成功。 從下圖可以清楚地看到，Syslog 所記錄的日誌確實為 successful_severity 所設定的 notice 層級。

    Syslog驗證畫面1