Mercurial > hg > nginx-site

changeset 2992:6e094f915896

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 15 Aug 2023 12:36:26 +0100
parents 1f672755959a
children 1ae01ea2eca8
files xml/en/docs/http/ngx_http_api_module.xml xml/en/docs/http/ngx_http_api_module_head.xml xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml yaml/nginx_api.yaml
diffstat 5 files changed, 485 insertions(+), 36 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_api_module.xml
+++ b/xml/en/docs/http/ngx_http_api_module.xml
@@ -110,21 +110,22 @@ All API requests include
 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 @@ By default, the API is read-only.
 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 @@ redirect</link> happens during request p
 <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 @@ Possible responses:
 </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 @@ The total number of requests completed w
   }
 }</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">
--- a/xml/en/docs/http/ngx_http_api_module_head.xml
+++ b/xml/en/docs/http/ngx_http_api_module_head.xml
@@ -110,21 +110,22 @@ All API requests include
 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 @@ By default, the API is read-only.
 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 @@ redirect</link> happens during request p
 <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>
--- a/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml
+++ b/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml
@@ -62,12 +62,37 @@ Enables the MQTT protocol for the given 
 
 </directive>
 
+
+<directive name="mqtt_buffers">
+<syntax><value>number</value> <value>size</value></syntax>
+<default>100 1k</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.25.1</appeared-in>
+
+<para>
+Sets the <value>number</value> and <value>size</value> of the buffers
+used for handling MQTT messages,
+for a single connection.
+</para>
+
+</directive>
+
+
 <directive name="mqtt_rewrite_buffer_size">
 <syntax><value>size</value></syntax>
 <default>4k|8k</default>
 <context>server</context>
 
 <para>
+<note>
+This directive is obsolete since version 1.25.1.
+The <link id="mqtt_buffers"/>
+directive should be used instead.
+</note>
+</para>
+
+<para>
 Sets the <value>size</value> of the buffer
 used for writing a modified message.
 By default, the buffer size is equal to one memory page.
@@ -77,6 +102,7 @@ It can be made smaller, however.
 
 </directive>
 
+
 <directive name="mqtt_set_connect">
 <syntax><literal>field</literal> <value>value</value></syntax>
 <default/>
--- a/xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml
@@ -63,12 +63,37 @@ mqtt_set_connect username "$name";
 
 </directive>
 
+
+<directive name="mqtt_buffers">
+<syntax><value>число</value> <value>размер</value></syntax>
+<default>100 1k</default>
+<context>stream</context>
+<context>server</context>
+<appeared-in>1.25.1</appeared-in>
+
+<para>
+Задаёт <value>число</value> и <value>размер</value> буферов,
+необходимых для обработки MQTT-сообщений,
+для одного соединения.
+</para>
+
+</directive>
+
+
 <directive name="mqtt_rewrite_buffer_size">
 <syntax><value>размер</value></syntax>
 <default>4k|8k</default>
 <context>server</context>
 
 <para>
+<note>
+Эта директива устарела начиная с версии 1.25.1.
+Вместо неё следует использовать директиву
+<link id="mqtt_buffers"/>.
+</note>
+</para>
+
+<para>
 Задаёт <value>размер</value> буфера,
 в который будет записываться модифицированное сообщение.
 По умолчанию размер одного буфера равен размеру страницы памяти.
@@ -78,6 +103,7 @@ mqtt_set_connect username "$name";
 
 </directive>
 
+
 <directive name="mqtt_set_connect">
 <syntax><literal>поле</literal> <value>значение</value></syntax>
 <default/>
--- a/yaml/nginx_api.yaml
+++ b/yaml/nginx_api.yaml
@@ -1,6 +1,6 @@
 swagger: '2.0'
 info:
-  version: '8.0'
+  version: '9.0'
   title: NGINX Plus REST API
   description: NGINX Plus REST
     [API](https://nginx.org/en/docs/http/ngx_http_api_module.html)
@@ -9,11 +9,12 @@ info:
     key-value pairs management for
     [http](https://nginx.org/en/docs/http/ngx_http_keyval_module.html) and
     [stream](https://nginx.org/en/docs/stream/ngx_stream_keyval_module.html).
-basePath: /api/8
+basePath: /api/9
 tags:
   - name: General Info
   - name: Processes
   - name: Connections
+  - name: Workers
   - name: Slabs
   - name: Resolvers
   - name: SSL
@@ -2101,6 +2102,112 @@ paths:
           description: Method disabled (*MethodDisabled*)
           schema:
             $ref: '#/definitions/NginxError'
+  /workers/:
+    get:
+      tags:
+        - Workers
+        - Method GET
+      summary:  Return statistics for all worker processes
+      description: Returns statistics for all worker processes such as accepted, dropped, active, idle connections, total and current requests.
+      operationId: getWorkers
+      produces:
+        - application/json
+      parameters:
+        - in: query
+          name: fields
+          type: string
+          description: Limits which fields of worker process statistics will be output.
+      responses:
+        '200':
+          description: Success
+          schema:
+            $ref: '#/definitions/NginxWorkersMap'
+        '404':
+          description: |
+            Worker not found (*WorkerNotFound*),
+            unknown version (*UnknownVersion*)
+          schema:
+            $ref: '#/definitions/NginxError'
+    delete:
+      tags:
+        - Workers
+        - Method DELETE
+      summary: Reset statistics for all worker processes.
+      description: |
+        Resets statistics for all worker processes such as
+        accepted, dropped, active, idle connections, total and current requests.
+      operationId: deleteWorkersStat
+      produces:
+        - application/json
+      responses:
+        '204':
+          description: Success
+        '404':
+          description: |
+            Worker not found (*WorkerNotFound*),
+            unknown version (*UnknownVersion*)
+          schema:
+            $ref: '#/definitions/NginxError'
+        '405':
+          description: Method disabled (*MethodDisabled*)
+          schema:
+            $ref: '#/definitions/NginxError'
+  '/workers/{workerId}':
+    parameters:
+      - name: workerId
+        in: path
+        description: The ID of the worker process.
+        required: true
+        type: string
+    get:
+      tags:
+        - Workers
+        - Method GET
+      summary: Return status of a worker process
+      description: Returns status of a particular worker process.
+      operationId: getWorker
+      produces:
+        - application/json
+      parameters:
+        - in: query
+          name: fields
+          type: string
+          description: Limits which fields of worker process statistics will be output.
+      responses:
+        '200':
+          description: Success
+          schema:
+            $ref: '#/definitions/NginxWorker'
+        '404':
+          description: |
+            Worker not found (*WorkerNotFound*),
+            unknown version (*UnknownVersion*)
+          schema:
+            $ref: '#/definitions/NginxError'
+    delete:
+      tags:
+        - Workers
+        - Method DELETE
+      summary: Reset statistics for a worker process.
+      description: |
+        Resets statistics of accepted, dropped, active, idle connections,
+        as well as total and current requests.
+      operationId: deleteWorkerStat
+      produces:
+        - application/json
+      responses:
+        '204':
+          description: Success
+        '404':
+          description: |
+            Worker not found (*WorkerNotFound*),
+            unknown version (*UnknownVersion*)
+          schema:
+            $ref: '#/definitions/NginxError'
+        '405':
+          description: Method disabled (*MethodDisabled*)
+          schema:
+            $ref: '#/definitions/NginxError'
 ###
 ###DEFINITIONS
 ###
@@ -4622,6 +4729,97 @@ definitions:
           refused: 0
           timedout: 243
           unknown: 478
+  NginxWorker:
+    title: Worker process
+    description: |
+      Statistics per each worker process.
+    properties:
+      id:
+        type: integer
+        description: The ID of the worker process.
+      pid:
+        type: integer
+        description: The PID identifier of the worker process used by the operating system.
+      connections:
+        type: object
+        description: |
+          The number of accepted, dropped, active, and idle connections
+          per worker process.
+        properties:
+          accepted:
+            type: integer
+            description: |
+              The total number of client connections
+              accepted by the worker process.
+          dropped:
+            type: integer
+            description: |
+              The total number of client connections
+              dropped by the worker process.
+          active:
+            type: integer
+            description: |
+              The current number of active client connections
+              that are currently being handled by the worker process.
+          idle:
+            type: integer
+            description: |
+              The number of idle client connections
+              that are currently being handled by the worker process.
+      http:
+        type: object
+        properties:
+          requests:
+            type: object
+            description: The total number of client requests handled by the worker process.
+            properties:
+              total:
+                type: integer
+                description: The total number of client requests received by the worker process.
+              current:
+                type: integer
+                description: The current number of client requests that are currently being processed by the worker process.
+    example:
+      id: 0
+      pid: 32212
+      connections:
+        accepted: 1
+        dropped: 0
+        active: 1
+        idle: 0
+      http:
+        requests:
+          total: 15
+          current: 1
+  NginxWorkersMap:
+    title: Worker processes
+    description: nginx worker processes object.
+    type: object
+    additionalProperties:
+      $ref: '#/definitions/NginxWorker'
+    example:
+      - id: 0
+        pid: 32212
+        connections:
+          accepted: 1
+          dropped: 0
+          active: 1
+          idle: 0
+        http:
+          requests:
+            total: 19
+            current: 1
+      - id: 1
+        pid: 32214
+        connections:
+          accepted: 1
+          dropped: 0
+          active: 1
+          idle: 0
+        http:
+          requests:
+            total: 15
+            current: 0
   NginxError:
     title: Error
     description: |