$ opm get Moesif/lua-resty-moesif

NGINX 的 Moesif 插件

NGINX Lua 插件，用于将 API 调用日志记录到 Moesif 以进行 API 分析和监控。

此插件支持任何安装了 OpenResty 的 NGINX 开源版和 NGINX Plus 变体，包括基于 OpenResty 构建的 API 网关，例如 3Scale API 网关。

Github 仓库

如何安装

确保已安装 lua-nginx-module。如果您运行的是 OpenResty 镜像，则它已安装。

如果您使用的是 NGINX Plus，请 按照这些说明操作。

安装 Moesif Luarock

    luarocks install --server=http://luarocks.org/manifests/moesif lua-resty-moesif

如何使用（通用 OpenResty）

编辑您的 nginx.conf 文件以添加 Moesif 插件。

如有必要，请将 /usr/local/openresty/luajit/share/lua/5.1/resty 替换为正确的 lua 插件安装路径。可以使用 find / -name "moesif" -type d 找到它。如果有多个路径，只需选择一个。

> NGINX 仅支持在同一部分中使用一次 log_by_lua* 之类的指令。如果您已经在使用 Moesif 使用的相同 NGINX 指令，则可能需要调整您的配置。 请参阅 OpenResty 文档。

    lua_shared_dict moesif_conf 5m;
    
    init_by_lua_block {
       local config = ngx.shared.moesif_conf;
       config:set("application_id", "Your Moesif Application Id")
    }
    
    lua_package_cpath ";;${prefix}?.so;${prefix}src/?.so;/usr/share/lua/5.1/lua/resty/moesif/?.so;/usr/share/lua/5.1/?.so;/usr/lib64/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.so;/usr/local/share/lua/5.1/resty/moesif/?.so";
    lua_package_path ";;${prefix}?.lua;${prefix}src/?.lua;/usr/share/lua/5.1/lua/resty/moesif/?.lua;/usr/share/lua/5.1/?.lua;/usr/lib64/lua/5.1/?.lua;/usr/lib/lua/5.1/?.lua;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.lua;/usr/local/share/lua/5.1/resty/moesif/?.lua";
    
    server {
      listen 80;
      resolver 8.8.8.8;
    
      # Define the variables Moesif requires
      set $moesif_user_id nil;
      set $moesif_company_id nil;
      set $moesif_req_body nil;
      set $moesif_res_body nil;
    
      # Optionally, set moesif_user_id and moesif_company_id such from
      # a request header or NGINX var to identify customer
      header_filter_by_lua_block  { 
        ngx.var.moesif_user_id = ngx.req.get_headers()["X-User-Id"]
        ngx.var.moesif_company_id = ngx.req.get_headers()["X-Company-Id"]
      }
    
      # Add Moesif plugin. You may need to update install path
    
      access_by_lua_file /usr/local/openresty/luajit/share/lua/5.1/resty/moesif/read_req_body.lua;
      body_filter_by_lua_file /usr/local/openresty/luajit/share/lua/5.1/resty/moesif/read_res_body.lua;
      log_by_lua_file /usr/local/openresty/luajit/share/lua/5.1/resty/moesif/send_event.lua;
    
      # Sample Hello World API
      location /api {
         add_header Content-Type "application/json";
         return 200 '{\r\n  \"message\": \"Hello World\",\r\n  \"completed\": true\r\n}';
      }
    }

如何使用（3Scale API 网关）

安装 3Scale API 网关 的 Moesif 插件与普通安装相同，但有两处更改

1. 添加 3scale 特定的配置选项以从 3scale 管理 API 获取其他用户上下文

2. 将 send_event.lua 替换为 send_event_3Scale.lua

编辑您的 nginx.conf 文件以添加 Moesif 插件。

如有必要，请将 /usr/share/lua/5.1/lua/resty 替换为正确的 lua 插件安装路径。可以使用 find / -name "moesif" -type d 找到它。如果有多个路径，只需选择一个。

> NGINX 仅支持在同一部分中使用一次 log_by_lua* 之类的指令。如果您已经在使用 Moesif 使用的相同 NGINX 指令，则可能需要调整您的配置。 请参阅 OpenResty 文档。

以下是 3scale 的示例配置

    lua_shared_dict moesif_conf 5m;
    lua_shared_dict user_id_cache 5m;
    lua_shared_dict company_id_cache 5m;
    
    init_by_lua_block {
       local config = ngx.shared.moesif_conf;
       config:set("application_id", "Your Moesif Application Id")
       config:set("3scale_domain", "YOUR_ACCOUNT-admin.3scale.net")
       config:set("3scale_access_token", "Your 3scale Access Token")
    }
    
    lua_package_cpath ";;${prefix}?.so;${prefix}src/?.so;/usr/share/lua/5.1/lua/resty/moesif/?.so;/usr/share/lua/5.1/?.so;/usr/lib64/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.so";
    lua_package_path ";;${prefix}?.lua;${prefix}src/?.lua;/usr/share/lua/5.1/lua/resty/moesif/?.lua;/usr/share/lua/5.1/?.lua;/usr/lib64/lua/5.1/?.lua;/usr/lib/lua/5.1/?.lua;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.lua";
    
    server {
      listen 80;
      resolver 8.8.8.8;
    
      # Customer identity variables that Moesif will read downstream
      # Set automatically from 3scale management API
      set $moesif_user_id "";
      set $moesif_company_id "";
    
      # Request/Response body variable that Moesif will use downstream
      set $moesif_req_body "";
      set $moesif_res_body "";
    
      access_by_lua_file /usr/share/lua/5.1/lua/resty/moesif/read_req_body.lua;
      body_filter_by_lua_file /usr/share/lua/5.1/lua/resty/moesif/read_res_body.lua;
      log_by_lua_file /usr/share/lua/5.1/lua/resty/moesif/send_event_3Scale.lua;
    
      # Sample Hello World API
      location /api {
          add_header Content-Type "application/json";
          return 200 '{\r\n  \"message\": \"Hello World\",\r\n  \"completed\": true\r\n}';
      }
    }

配置选项

启动时一次设置的静态选项，例如在 init_by_lua_block 中。

application_id__

(必需)，字符串，用于向 Moesif 进行身份验证的应用程序 ID。

disable_capture_request_body__

(可选) 布尔值，禁用请求正文日志记录的选项。默认值为 false。

disable_capture_response_body__

(可选) 布尔值，禁用响应正文日志记录的选项。默认值为 false。

request_header_masks__

(可选) 字符串，用于屏蔽特定请求标头字段的选项。用逗号分隔多个字段，例如 "header_a, header_b"

request_body_masks__

(可选) 字符串，用于屏蔽特定请求正文字段的选项。用逗号分隔多个字段，例如 "field_a, field_b"

response_header_masks__

(可选) 字符串，用于屏蔽特定响应标头字段的选项。用逗号分隔多个字段，例如 "header_a, header_b"

response_body_masks__

(可选) 字符串，用于屏蔽特定响应正文字段的选项。用逗号分隔多个字段，例如 "field_a, field_b"

disable_transaction_id__

(可选) 布尔值，设置为 true 将阻止插入 <code>X-Moesif-Transaction-Id</code> 标头。默认值为 false。

debug__

(可选) 布尔值，如果遇到集成问题，请设置为 true 以打印调试日志。

authorization_header_name__

(可选) 字符串，用于在 Moesif 中识别用户的请求标头字段名称。默认为 authorization。也支持逗号分隔的字符串。我们将按顺序检查标头，例如 "X-Api-Key,Authorization"。

authorization_user_id_field__

(可选) 字符串，用于在 Moesif 中从授权标头解析用户的字段名称。默认为 sub。

3Scale 特定选项

如果您使用 send_event_3Scale.lua 为 3Scale API 网关 安装了此插件，则可以使用其他静态选项

3scale_domain__

(必需)，字符串，您的完整 3Scale 管理域，例如 YOUR_ACCOUNT-admin.3scale.net。

3scale_access_token__

(必需)，字符串，一个管理员 ACCESS_TOKEN，您可以从 3scale 管理门户获取。

3scale_user_id_name__

(可选) 字符串，3scale 应用程序 XML 实体中用于在 Moesif 中识别用户的 3scale 字段名称。默认为 id，但其他有效示例包括 user_account_id 和 service_id。 更多信息。

3scale_auth_api_key__

(可选) 字符串，如果您将 3scale 配置为通过单个 userkey_ 字符串进行身份验证，请在此处设置字段名称。默认为 user_key。 更多信息。

3scale_auth_app_id__

(可选) 字符串，如果您将 3scale 配置为通过 appid_ 和 appkey_ 对进行身份验证，请在此处设置 app_id 字段名称。默认为 app_id。如果设置，则需要设置 3scale_auth_app_key_pair。 更多信息。

3scale_auth_app_key_pair__

(可选) 字符串，如果您将 3scale 配置为通过 appid_ 和 appkey_ 对进行身份验证，请在此处设置 app_key 字段名称。默认为 app_key。如果设置，则需要设置 3scale_auth_app_id。 更多信息。

动态变量

每个 HTTP 请求的动态变量。在 ngx.var 字典上设置这些变量，例如在 header_filter_by_lua_block 或 body_filter_by_lua_block 中。

    header_filter_by_lua_block  { 
      -- Read user id from request query param
      ngx.var.moesif_user_id     = ngx.req.arg_user_id
      
      -- Read version from request header
      ngx.var.moesif_api_version = ngx.req.get_headers()["X-API-Version"]
    }
    
    body_filter_by_lua_block  { 
      -- Read company id from response header
      ngx.var.moesif_company_id  = ngx.resp.get_headers()["X-Company-Id"]
    }

moesif_user_id__

(可选) 字符串，将 API 请求属性分配给各个用户，以便您可以跟踪谁在调用您的 API。这也可以与 ngx.var.moesif_company_id 结合使用以跟踪帐户级别的使用情况。如果您为 3scale 安装了此插件，则无需设置此字段，因为它会自动处理

moesif_company_id__

(可选) 字符串，将 API 请求属性分配给公司或帐户，以便您可以跟踪谁在调用您的 API。这可以与 ngx.var.moesif_company_id 结合使用。如果您为 3scale 安装了此插件，则无需设置此字段，因为它会自动处理

moesif_api_version__

(可选) 布尔值，您要为此请求添加的可选 API 版本。

moesif_log_event__

(可选) 布尔值，如果设置为 false，则跳过捕获该位置上下文的 API 调用。默认情况下，将捕获所有 API 调用。例如，当在某个位置上下文中 set $moesif_log_event false; 时，Moesif 将不会记录该位置的 API 调用。

故障排除

未记录响应正文

如果您发现响应正文未在 Moesif 中记录，则您的设置可能需要一个内部 proxy_pass，可以通过在您的 nginx.conf 中添加几行代码来添加。

对于以下示例服务器

    server {
      listen 80;
      resolver 8.8.8.8;
    
      # Sample Hello World API
      location /api {
         add_header Content-Type "application/json";
         return 200 '{\r\n  \"message\": \"Hello World\",\r\n  \"completed\": true\r\n}';
      }
    }

包含 proxy_pass 的服务器如下所示

    server {
      listen 80;
      resolver 8.8.8.8;
    
      # Sample Hello World API
      location /api {
        proxy_pass http://127.0.0.1:80/internal;
      }
    
      location /internal {
          add_header Content-Type "application/json";
          return 200 '{\r\n  \"message\": \"Hello World\",\r\n  \"completed\": true\r\n}';
      }
    }

示例

基于 OpenResty 的快速入门教程，提供了一个 Moesif 集成示例

恭喜！如果一切正常，Moesif 现在应该可以跟踪与您之前指定的路由匹配的所有网络请求。如果您在设置方面遇到任何问题，请联系 support@moesif.com。

其他集成

要查看有关集成选项的更多文档，请访问 集成选项。

POD 错误

您好！以上文档存在一些编码错误，如下所述：

大约在第 154 行

未终止的 B<...> 序列

大约在第 159 行

未终止的 B<...> 序列

大约在第 164 行

未终止的 B<...> 序列

大约在第 169 行

未终止的 B<...> 序列

大约在第 174 行

未终止的 B<...> 序列

大约在第 179 行

未终止的 B<...> 序列

大约在第 184 行

未终止的 B<...> 序列

大约在第 189 行

未终止的 B<...> 序列

大约在第 194 行

未终止的 B<...> 序列

大约在第 199 行

未终止的 B<...> 序列

大约在第 204 行

未终止的 B<...> 序列

大约在第 216 行

未终止的 B<...> 序列

大约在第 221 行

未终止的 B<...> 序列

大约在第 226 行

未终止的 B<...> 序列

大约在第 232 行

未终止的 B<...> 序列

大约在第 238 行

未终止的 B<...> 序列

大约在第 244 行

未终止的 B<...> 序列

大约在第 271 行

未终止的 B<...> 序列

大约在第 277 行

未终止的 B<...> 序列

大约在第 283 行

未终止的 B<...> 序列

大约在第 288 行

未终止的 B<...> 序列