diff xml/en/docs/http/ngx_http_api_module.xml @ 2992:6e094f915896

Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 15 Aug 2023 12:36:26 +0100
parents a85e4d126bc7
children
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_api_module.xml	Thu Jul 06 18:12:53 2023 +0100
+++ b/xml/en/docs/http/ngx_http_api_module.xml	Tue Aug 15 12:36:26 2023 +0100
@@ -110,21 +110,22 @@
 a supported API <link id="api_version">version</link> in the URI.
 Examples of API requests with this configuration:
 <example>
-http://127.0.0.1/api/8/
-http://127.0.0.1/api/8/nginx
-http://127.0.0.1/api/8/connections
-http://127.0.0.1/api/8/http/requests
-http://127.0.0.1/api/8/http/server_zones/server_backend
-http://127.0.0.1/api/8/http/caches/cache_backend
-http://127.0.0.1/api/8/http/upstreams/backend
-http://127.0.0.1/api/8/http/upstreams/backend/servers/
-http://127.0.0.1/api/8/http/upstreams/backend/servers/1
-http://127.0.0.1/api/8/http/keyvals/one?key=arg1
-http://127.0.0.1/api/8/stream/
-http://127.0.0.1/api/8/stream/server_zones/server_backend
-http://127.0.0.1/api/8/stream/upstreams/
-http://127.0.0.1/api/8/stream/upstreams/backend
-http://127.0.0.1/api/8/stream/upstreams/backend/servers/1
+http://127.0.0.1/api/9/
+http://127.0.0.1/api/9/nginx
+http://127.0.0.1/api/9/connections
+http://127.0.0.1/api/9/workers
+http://127.0.0.1/api/9/http/requests
+http://127.0.0.1/api/9/http/server_zones/server_backend
+http://127.0.0.1/api/9/http/caches/cache_backend
+http://127.0.0.1/api/9/http/upstreams/backend
+http://127.0.0.1/api/9/http/upstreams/backend/servers/
+http://127.0.0.1/api/9/http/upstreams/backend/servers/1
+http://127.0.0.1/api/9/http/keyvals/one?key=arg1
+http://127.0.0.1/api/9/stream/
+http://127.0.0.1/api/9/stream/server_zones/server_backend
+http://127.0.0.1/api/9/stream/upstreams/
+http://127.0.0.1/api/9/stream/upstreams/backend
+http://127.0.0.1/api/9/stream/upstreams/backend/servers/1
 </example>
 </para>
 
@@ -155,14 +156,14 @@
 All API requests should contain a supported API version in the URI.
 If the request URI equals the location prefix,
 the list of supported API versions is returned.
-The current API version is “<literal>8</literal>”.
+The current API version is “<literal>9</literal>”.
 </para>
 
 <para>
 The optional “<literal>fields</literal>” argument in the request line
 specifies which fields of the requested objects will be output:
 <example>
-http://127.0.0.1/api/8/nginx?fields=version,build
+http://127.0.0.1/api/9/nginx?fields=version,build
 </example>
 </para>
 
@@ -208,6 +209,11 @@
 <list type="bullet">
 
 <listitem>
+The <link id="workers_">/workers/</link> data
+were added in <link id="api_version">version</link> 9.
+</listitem>
+
+<listitem>
 Detailed failure counters were added to SSL statistics
 in <link id="api_version">version</link> 8 (1.23.2).
 </listitem>
@@ -2009,6 +2015,99 @@
 </listitem>
 </list>
 </tag-desc>
+<tag-name id="workers_" name="/workers/">
+<literal>/workers/</literal>
+</tag-name>
+<tag-desc>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getWorkers">
+<literal>GET</literal> - Return statistics for all worker processes
+<para>Returns statistics for all worker processes such as accepted, dropped, active, idle connections, total and current requests.</para>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+Limits which fields of worker process statistics will be output.</tag-desc>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>200 - Success, returns a collection of "<link id="def_nginx_worker">Worker process</link>" objects for all workers</listitem>
+<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
+unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+<listitem id="deleteWorkersStat">
+<literal>DELETE</literal> - Reset statistics for all worker processes.
+<para>Resets statistics for all worker processes such as
+accepted, dropped, active, idle connections, total and current requests.</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>204 - Success</listitem>
+<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
+unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+</list>
+</tag-desc>
+<tag-name id="workers_worker_id" name="/workers/{workerId}">
+<literal>/workers/{workerId}</literal>
+</tag-name>
+<tag-desc>
+Parameters common for all methods:
+<list type="tag">
+<tag-name><literal>workerId</literal>
+(<literal>string</literal>, required)</tag-name>
+<tag-desc>
+The ID of the worker process.</tag-desc>
+</list>
+<para>Supported methods:</para>
+<list type="bullet" compact="yes">
+<listitem id="getWorker">
+<literal>GET</literal> - Return status of a worker process
+<para>Returns status of a particular worker process.</para>
+<para>
+Request parameters:
+<list type="tag">
+<tag-name><literal>fields</literal>
+(<literal>string</literal>, optional)</tag-name>
+<tag-desc>
+Limits which fields of worker process statistics will be output.</tag-desc>
+</list>
+</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>200 - Success, returns <link id="def_nginx_worker">Worker process</link></listitem>
+<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
+unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+<listitem id="deleteWorkerStat">
+<literal>DELETE</literal> - Reset statistics for a worker process.
+<para>Resets statistics of accepted, dropped, active, idle connections,
+as well as total and current requests.</para>
+<para>
+Possible responses:
+</para>
+<list type="bullet">
+<listitem>204 - Success</listitem>
+<listitem>404 - Worker not found (<literal>WorkerNotFound</literal>),
+unknown version (<literal>UnknownVersion</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+<listitem>405 - Method disabled (<literal>MethodDisabled</literal>), returns <link id="def_nginx_error">Error</link></listitem>
+</list>
+</listitem>
+</list>
+</tag-desc>
 </list>
 </para>
 </section>
@@ -4346,6 +4445,100 @@
   }
 }</example>
 </listitem>
+<listitem id="def_nginx_worker">
+<para>Worker process:</para>
+Statistics per each worker process.<list type="tag">
+<tag-name>
+<literal>id</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The ID of the worker process.
+</tag-desc>
+<tag-name>
+<literal>pid</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The PID identifier of the worker process used by the operating system.
+</tag-desc>
+<tag-name>
+<literal>connections</literal></tag-name>
+<tag-desc>
+The number of accepted, dropped, active, and idle connections
+per worker process.<list type="tag">
+<tag-name>
+<literal>accepted</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of client connections
+accepted by the worker process.
+</tag-desc>
+<tag-name>
+<literal>dropped</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of client connections
+dropped by the worker process.
+</tag-desc>
+<tag-name>
+<literal>active</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The current number of active client connections
+that are currently being handled by the worker process.
+</tag-desc>
+<tag-name>
+<literal>idle</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The number of idle client connections
+that are currently being handled by the worker process.
+</tag-desc>
+</list>
+</tag-desc>
+<tag-name>
+<literal>http</literal></tag-name>
+<tag-desc>
+<list type="tag">
+<tag-name>
+<literal>requests</literal></tag-name>
+<tag-desc>
+The total number of client requests handled by the worker process.<list type="tag">
+<tag-name>
+<literal>total</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The total number of client requests received by the worker process.
+</tag-desc>
+<tag-name>
+<literal>current</literal> (<literal>integer</literal>)
+</tag-name>
+<tag-desc>
+The current number of client requests that are currently being processed by the worker process.
+</tag-desc>
+</list>
+</tag-desc>
+</list>
+</tag-desc>
+</list>
+<para>Example:</para>
+<example>
+{
+  "id" : 0,
+  "pid" : 32212,
+  "connections" : {
+    "accepted" : 1,
+    "dropped" : 0,
+    "active" : 1,
+    "idle" : 0
+  },
+  "http" : {
+    "requests" : {
+      "total" : 15,
+      "current" : 1
+    }
+  }
+}</example>
+</listitem>
 <listitem id="def_nginx_error">
 <para>Error:</para>
 nginx error object.<list type="tag">