Mercurial > hg > nginx-site
changeset 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 | 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 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">
--- a/xml/en/docs/http/ngx_http_api_module_head.xml Thu Jul 06 18:12:53 2023 +0100 +++ b/xml/en/docs/http/ngx_http_api_module_head.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>
--- a/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml Thu Jul 06 18:12:53 2023 +0100 +++ b/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml Tue Aug 15 12:36:26 2023 +0100 @@ -62,12 +62,37 @@ </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 @@ </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 Thu Jul 06 18:12:53 2023 +0100 +++ b/xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml Tue Aug 15 12:36:26 2023 +0100 @@ -63,12 +63,37 @@ </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 @@ </directive> + <directive name="mqtt_set_connect"> <syntax><literal>поле</literal> <value>значение</value></syntax> <default/>
--- a/yaml/nginx_api.yaml Thu Jul 06 18:12:53 2023 +0100 +++ b/yaml/nginx_api.yaml Tue Aug 15 12:36:26 2023 +0100 @@ -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 @@ 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 @@ 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 @@ 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: |