You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2020/12/01 06:39:30 UTC
[GitHub] [apisix] membphis commented on a change in pull request #2884: feat: server info
membphis commented on a change in pull request #2884:
URL: https://github.com/apache/apisix/pull/2884#discussion_r533100323
##########
File path: doc/zh-cn/plugins/server-info.md
##########
@@ -0,0 +1,104 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+- [English](../../plugins/server-info.md)
+
+# Summary
+
+- [**插件简介**](#插件简介)
+- [插件属性](#插件属性)
+- [**插件接口**](#插件接口)
+- [启用插件](#启用插件)
+- [测试插件](#测试插件)
+- [禁用插件](#禁用插件)
+- [注意事项](#注意事项)
+
+## 插件简介
+
+`server-info` 是 `APISIX` 提供的一款查询其服务基本信息的插件。
+
+## 插件属性
+
+无
+
+## 插件接口
+
+此插件提供了接口 `/apisix/server_info`，可以通过 [interceptors](../plugin-interceptors.md) 来保护该接口。
+
+## 启用插件
+
+在配置文件 `apisix/conf/config.yaml` 的插件列表中添加 `server-info`, 即可启用该插件。
+
+```
+plugins: # plugin list
+ - example-plugin
+ - limit-req
+ - node-status
+ - server-info
+ - jwt-auth
+ - zipkin
+ ......
+```
+
+在启动/重启 APISIX 之后，即可通过访问 `/apisix/server_info` 来获取服务基本信息。
+
+## 测试插件
+
+```bash
+curl http://127.0.0.1:9080/apisix/admin/server_info -s | jq
Review comment:
need to update the path
##########
File path: t/plugin/server-info.t
##########
@@ -0,0 +1,69 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+use t::APISIX 'no_plan';
+
+master_on();
+repeat_each(1);
+no_long_string();
+no_root_location();
+no_shuffle();
+
+run_tests;
+
+__DATA__
+
+=== TEST 1: sanity check
+--- config
+location /t {
+ content_by_lua_block {
+ -- let the server info to be reported
+ ngx.sleep(5.1)
+ local json_decode = require("cjson.safe").decode
+ local t = require("lib.test_admin").test
+ local code, _, body = t('/apisix/server_info', ngx.HTTP_GET)
+ if code >= 300 then
+ ngx.status = code
+ end
+
+ local keys = {}
+ body = json_decode(body)
+ for k in pairs(body) do
+ keys[#keys + 1] = k
+ end
+
+ table.sort(keys)
+ for i = 1, #keys do
+ ngx.say(keys[i], ": ", body[keys[i]])
+ end
+ }
+}
+--- request
+GET /t
+--- response_body eval
+qr{^etcd_version: [\d\.]+
+hostname: [a-zA-Z\-0-9]+
+id: [a-zA-Z\-0-9]+
+last_report_time: \d+
+up_time: \d+
+version: [\d\.]+
+$}
+--- timeout: 6
+--- no_error_log
+[error]
+
Review comment:
one blank line is enough at the end of file
##########
File path: apisix/server_info.lua
##########
@@ -0,0 +1,168 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require = require
+local core = require("apisix.core")
+
+local type = type
+local ngx_time = ngx.time
+
+local boot_time = os.time()
+local internal_status = ngx.shared.internal_status
+
+local _M = {}
+
+if not internal_status then
+ error("lua_shared_dict \"internal_status\" not configured")
+end
+
+
+local function is_privileged()
+ local process_type = require("ngx.process").type()
+ return process_type == "privileged agent" or process_type == "single"
+end
+
+-- server information will be saved into shared memory only if the key
+-- "server_info" not exist if excl is true.
+local function save(data, excl)
+ local handler = excl and internal_status.add or internal_status.set
+
+ local ok, err = handler(internal_status, "server_info", data)
+ if not ok then
+ if excl and err == "exists" then
+ return true
+ end
+
+ return nil, err
+ end
+
+ return true
+end
+
+
+local function encode_and_save(server_info, excl)
+ local data, err = core.json.encode(server_info)
+ if not data then
+ return nil, err
+ end
+
+ return save(data, excl)
+end
+
+
+local function report()
+ local server_info, err = _M.get()
+ if not server_info then
+ core.log.error("failed to get server_info: ", err)
+ return nil, err
+ end
+
+ if server_info.etcd_version == "unknown" then
+ local res, err = core.etcd.server_version()
+ if not res then
+ core.log.error("failed to fetch etcd version: ", err)
+ return nil, err
+
+ elseif type(res.body) ~= "table" then
+ core.log.error("failed to fetch etcd version: bad version info")
+ return nil, "bad etcd version info"
+ else
+ server_info.etcd_version = res.body.etcdcluster
+ end
+ end
+
+ server_info.last_report_time = ngx_time()
+
+ local data, err = core.json.encode(server_info)
+ if not data then
+ core.log.error("failed to encode server_info: ", err)
+ return nil, err
+ end
+
+ local key = "/data_plane/server_info/" .. server_info.id
+ local ok, err = core.etcd.set(key, data, 180)
+ if not ok then
+ core.log.error("failed to report server info to etcd: ", err)
+ return nil, err
+ end
+
+ local ok, err = save(data, false)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ return nil, err
+ end
+end
+
+
+local function uninitialized_server_info()
+ return {
+ etcd_version = "unknown",
+ hostname = core.utils.gethostname(),
+ id = core.id.get(),
+ version = core.version.VERSION,
+ up_time = ngx_time() - boot_time,
+ last_report_time = -1,
+ }
+end
+
+
+function _M.init_worker()
+ if not is_privileged() then
+ return
+ end
+
+ local ok, err = encode_and_save(uninitialized_server_info(), true)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ end
+
+ local opts = {
+ check_interval = 5, -- in seconds
Review comment:
and we should allow the user to specify this field
##########
File path: apisix/server_info.lua
##########
@@ -0,0 +1,168 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require = require
+local core = require("apisix.core")
+
+local type = type
+local ngx_time = ngx.time
+
+local boot_time = os.time()
+local internal_status = ngx.shared.internal_status
+
+local _M = {}
+
+if not internal_status then
+ error("lua_shared_dict \"internal_status\" not configured")
+end
+
+
+local function is_privileged()
+ local process_type = require("ngx.process").type()
+ return process_type == "privileged agent" or process_type == "single"
+end
+
+-- server information will be saved into shared memory only if the key
+-- "server_info" not exist if excl is true.
+local function save(data, excl)
+ local handler = excl and internal_status.add or internal_status.set
+
+ local ok, err = handler(internal_status, "server_info", data)
+ if not ok then
+ if excl and err == "exists" then
+ return true
+ end
+
+ return nil, err
+ end
+
+ return true
+end
+
+
+local function encode_and_save(server_info, excl)
+ local data, err = core.json.encode(server_info)
+ if not data then
+ return nil, err
+ end
+
+ return save(data, excl)
+end
+
+
+local function report()
+ local server_info, err = _M.get()
+ if not server_info then
+ core.log.error("failed to get server_info: ", err)
+ return nil, err
+ end
+
+ if server_info.etcd_version == "unknown" then
+ local res, err = core.etcd.server_version()
+ if not res then
+ core.log.error("failed to fetch etcd version: ", err)
+ return nil, err
+
+ elseif type(res.body) ~= "table" then
+ core.log.error("failed to fetch etcd version: bad version info")
+ return nil, "bad etcd version info"
+ else
+ server_info.etcd_version = res.body.etcdcluster
+ end
+ end
+
+ server_info.last_report_time = ngx_time()
+
+ local data, err = core.json.encode(server_info)
+ if not data then
+ core.log.error("failed to encode server_info: ", err)
+ return nil, err
+ end
+
+ local key = "/data_plane/server_info/" .. server_info.id
+ local ok, err = core.etcd.set(key, data, 180)
+ if not ok then
+ core.log.error("failed to report server info to etcd: ", err)
+ return nil, err
+ end
+
+ local ok, err = save(data, false)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ return nil, err
+ end
+end
+
+
+local function uninitialized_server_info()
+ return {
+ etcd_version = "unknown",
+ hostname = core.utils.gethostname(),
+ id = core.id.get(),
+ version = core.version.VERSION,
+ up_time = ngx_time() - boot_time,
+ last_report_time = -1,
+ }
+end
+
+
+function _M.init_worker()
+ if not is_privileged() then
+ return
+ end
+
+ local ok, err = encode_and_save(uninitialized_server_info(), true)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ end
+
+ local opts = {
+ check_interval = 5, -- in seconds
Review comment:
`5` seconds is short, I think 10 mins should be good
##########
File path: apisix/server_info.lua
##########
@@ -0,0 +1,168 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require = require
+local core = require("apisix.core")
+
+local type = type
+local ngx_time = ngx.time
+
+local boot_time = os.time()
+local internal_status = ngx.shared.internal_status
+
+local _M = {}
+
+if not internal_status then
+ error("lua_shared_dict \"internal_status\" not configured")
+end
+
+
+local function is_privileged()
+ local process_type = require("ngx.process").type()
+ return process_type == "privileged agent" or process_type == "single"
+end
+
+-- server information will be saved into shared memory only if the key
+-- "server_info" not exist if excl is true.
+local function save(data, excl)
+ local handler = excl and internal_status.add or internal_status.set
+
+ local ok, err = handler(internal_status, "server_info", data)
+ if not ok then
+ if excl and err == "exists" then
+ return true
+ end
+
+ return nil, err
+ end
+
+ return true
+end
+
+
+local function encode_and_save(server_info, excl)
+ local data, err = core.json.encode(server_info)
+ if not data then
+ return nil, err
+ end
+
+ return save(data, excl)
+end
+
+
+local function report()
+ local server_info, err = _M.get()
+ if not server_info then
+ core.log.error("failed to get server_info: ", err)
+ return nil, err
+ end
+
+ if server_info.etcd_version == "unknown" then
+ local res, err = core.etcd.server_version()
+ if not res then
+ core.log.error("failed to fetch etcd version: ", err)
+ return nil, err
+
+ elseif type(res.body) ~= "table" then
+ core.log.error("failed to fetch etcd version: bad version info")
+ return nil, "bad etcd version info"
+ else
+ server_info.etcd_version = res.body.etcdcluster
+ end
+ end
+
+ server_info.last_report_time = ngx_time()
+
+ local data, err = core.json.encode(server_info)
+ if not data then
+ core.log.error("failed to encode server_info: ", err)
+ return nil, err
+ end
+
+ local key = "/data_plane/server_info/" .. server_info.id
Review comment:
we can not use `data_plane` here. CP will write the server info too.
how about `/nodes/server_info/{node_id}`?
##########
File path: doc/zh-cn/plugins/server-info.md
##########
@@ -0,0 +1,104 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+- [English](../../plugins/server-info.md)
+
+# Summary
+
+- [**插件简介**](#插件简介)
+- [插件属性](#插件属性)
+- [**插件接口**](#插件接口)
+- [启用插件](#启用插件)
+- [测试插件](#测试插件)
+- [禁用插件](#禁用插件)
+- [注意事项](#注意事项)
+
+## 插件简介
+
+`server-info` 是 `APISIX` 提供的一款查询其服务基本信息的插件。
+
+## 插件属性
+
+无
+
+## 插件接口
+
+此插件提供了接口 `/apisix/server_info`，可以通过 [interceptors](../plugin-interceptors.md) 来保护该接口。
+
+## 启用插件
+
+在配置文件 `apisix/conf/config.yaml` 的插件列表中添加 `server-info`, 即可启用该插件。
+
+```
+plugins: # plugin list
+ - example-plugin
+ - limit-req
+ - node-status
+ - server-info
+ - jwt-auth
+ - zipkin
+ ......
+```
+
+在启动/重启 APISIX 之后，即可通过访问 `/apisix/server_info` 来获取服务基本信息。
+
+## 测试插件
+
+```bash
+curl http://127.0.0.1:9080/apisix/admin/server_info -s | jq
+{
+ "up_time": 5,
+ "last_report_time": 1606551536,
+ "id": "71cb4999-4349-475d-aa39-c703944a63d3",
+ "etcd_version": "3.5.0",
+ "version": "2.0",
+ "hostname": "gentoo"
+}
+```
+
+服务信息中每一项的含义如下：
+
+| 名称 | 类型 | 描述 |
+|---------|------|-------------|
+| up_time | integer | APISIX 服务实例当前的运行时间, 如果对 APSIX
+进行热更新操作，该值将被重置；普通的 reload 操作不会影响该值。 |
+| last_report_time | integer | 最近一次服务信息上报的时间 （UNIX 时间戳）。|
+| id | string | APISIX 服务实例 id 。|
+| etcd_version | string | etcd 集群的版本信息，如果 APISIX 和 etcd 集群之间存在网络分区，该值将设置为 `"unknown"`。|
+| version | string | APISIX 版本信息。 |
+| hostname | string | APISIX 所部署的机器或 pod 的主机名信息。|
+
+## 禁用插件
+
+通过移除配置文件 `apisix/conf/config.yaml` 插件列表中的 `server-info`，即可方便地禁用该插件。
+
+```
+plugins: # plugin list
+ - example-plugin
+ - limit-req
+ - node-status
+ - jwt-auth
+ - zipkin
+ ......
+```
+
+## 注意事项
+
+当使用 etcd 作为 APISIX 的数据中心的说话，服务信息将被周期性地上报到 etcd（目前的上报间隔是 5
Review comment:
"当使用 etcd 作为 APISIX 的数据中心的说话"
I can not understand it
##########
File path: apisix/server_info.lua
##########
@@ -0,0 +1,168 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements. See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License. You may obtain a copy of the License at
+--
+-- http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local require = require
+local core = require("apisix.core")
+
+local type = type
+local ngx_time = ngx.time
+
+local boot_time = os.time()
+local internal_status = ngx.shared.internal_status
+
+local _M = {}
+
+if not internal_status then
+ error("lua_shared_dict \"internal_status\" not configured")
+end
+
+
+local function is_privileged()
+ local process_type = require("ngx.process").type()
+ return process_type == "privileged agent" or process_type == "single"
+end
+
+-- server information will be saved into shared memory only if the key
+-- "server_info" not exist if excl is true.
+local function save(data, excl)
+ local handler = excl and internal_status.add or internal_status.set
+
+ local ok, err = handler(internal_status, "server_info", data)
+ if not ok then
+ if excl and err == "exists" then
+ return true
+ end
+
+ return nil, err
+ end
+
+ return true
+end
+
+
+local function encode_and_save(server_info, excl)
+ local data, err = core.json.encode(server_info)
+ if not data then
+ return nil, err
+ end
+
+ return save(data, excl)
+end
+
+
+local function report()
+ local server_info, err = _M.get()
+ if not server_info then
+ core.log.error("failed to get server_info: ", err)
+ return nil, err
+ end
+
+ if server_info.etcd_version == "unknown" then
+ local res, err = core.etcd.server_version()
+ if not res then
+ core.log.error("failed to fetch etcd version: ", err)
+ return nil, err
+
+ elseif type(res.body) ~= "table" then
+ core.log.error("failed to fetch etcd version: bad version info")
+ return nil, "bad etcd version info"
+ else
+ server_info.etcd_version = res.body.etcdcluster
+ end
+ end
+
+ server_info.last_report_time = ngx_time()
+
+ local data, err = core.json.encode(server_info)
+ if not data then
+ core.log.error("failed to encode server_info: ", err)
+ return nil, err
+ end
+
+ local key = "/data_plane/server_info/" .. server_info.id
+ local ok, err = core.etcd.set(key, data, 180)
+ if not ok then
+ core.log.error("failed to report server info to etcd: ", err)
+ return nil, err
+ end
+
+ local ok, err = save(data, false)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ return nil, err
+ end
+end
+
+
+local function uninitialized_server_info()
+ return {
+ etcd_version = "unknown",
+ hostname = core.utils.gethostname(),
+ id = core.id.get(),
+ version = core.version.VERSION,
+ up_time = ngx_time() - boot_time,
+ last_report_time = -1,
+ }
+end
+
+
+function _M.init_worker()
+ if not is_privileged() then
+ return
+ end
+
+ local ok, err = encode_and_save(uninitialized_server_info(), true)
+ if not ok then
+ core.log.error("failed to encode and save server info: ", err)
+ end
+
+ local opts = {
+ check_interval = 5, -- in seconds
+ }
+
+ if core.config ~= require("apisix.core.config_etcd") then
Review comment:
need some comment for why call `return` here
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org