From cbba246c8f98da7cfec4dc00c836ab1ab8eeb5d1 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 17 Dec 2024 21:41:23 +0000 Subject: [PATCH 1/5] configuration: Add section regarding JSON formatted access logs Signed-off-by: Andrew Clayton --- source/configuration/index.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/source/configuration/index.rst b/source/configuration/index.rst index e6e2dc81..4ac2bbb1 100644 --- a/source/configuration/index.rst +++ b/source/configuration/index.rst @@ -5679,6 +5679,31 @@ to define the log format: } } +=============== +JSON log format +=============== + +Starting with NGINX Unit 1.34.0, **format** can instead be an object +describing JSON field name/value pairs, for example, + +.. code-block:: json + + { + "access_log": { + "path": "/tmp/access.log", + "format": { + "remote_addr": "$remote_addr", + "time_local": "$time_local", + "request_line": "$request_line", + "status": "$status", + "body_bytes_sent": "$body_bytes_sent", + "header_referer": "$header_referer", + "header_user_agent": "$header_user_agent" + } + } + } + +The JSON *values* can be strings, variables and JavaScript. ====================== Conditional access log @@ -5738,4 +5763,4 @@ Example with njs and the use of a template literal: "if": "`${uri == '/health' ? false : true}`", "path": "..." } - } \ No newline at end of file + } From 2a3ffacfbe6b1811f8807845c72d52fe7fffc763 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 17 Dec 2024 22:04:09 +0000 Subject: [PATCH 2/5] configuration: Add settings/telemetry section This is for OpenTelemetry (OTEL). Signed-off-by: Andrew Clayton --- source/configuration/index.rst | 59 ++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/source/configuration/index.rst b/source/configuration/index.rst index 4ac2bbb1..a36a6d9d 100644 --- a/source/configuration/index.rst +++ b/source/configuration/index.rst @@ -5444,6 +5444,12 @@ that stores instance-wide preferences. uploaded via the :doc:`control API <../controlapi>`. + * - **telemetry** + - Object: + OpenTelemetry configuration + + *(since 1.34.0)* + In turn, the **http** option exposes the following settings: .. list-table:: @@ -5584,6 +5590,59 @@ In turn, the **http** option exposes the following settings: **.webp**, **.woff2**, **.woff**, **.xml**, and **.zip**. +The **telemetry** option exposes the following settings: + +.. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - **endpoint** (required) + - The endpoint for the OpenTelemetry (OTEL) Collector. + + It takes a URL to either a gRPC or HTTP(S) endpoint. + + * - **protocol** (required) + - Determines the protocol used to communicate with the endpoint. + + Can be either *http(s)* or *grpc* + + * - **batch_size** + - Number of spans to cache before triggering a transaction with the + configured endpoint. This is optional. + + This allows the user to cache up to N spans before the OpenTelemetry + (OTEL) background thread sends spans over the network to the + collector. + + If specified, it must be a positive integer. + + * - **sampling_ratio** + - Percentage of requests to trace. + + This allows the user to only trace anywhere from 0% to 100% of + requests that hit Unit. In high throughput environments this + percentage should be lower. This allows the user to save space in + storing span data, and to collect request metrics like time to decode + headers and whatnot without storing massive amounts of duplicate + superfluous data. + + If specified, it must be a positive floating point number. + +Example: + +.. code-block:: json + + "settings": { + "telemetry": { + "batch_size": 20, + "endpoint": "http://example.com/v1/traces", + "protocol": "http", + "sampling_ratio": 1.0 + } + }, + .. _configuration-access-log: ********** From 1a33511ef32312816e29cd403f20ba8eeab19381 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 17 Dec 2024 16:32:27 +0000 Subject: [PATCH 3/5] Add 1.34.0 release page Signed-off-by: Andrew Clayton --- source/news/2024/index.rst | 9 ++ source/news/2024/unit-1.34.0-released.rst | 159 ++++++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 source/news/2024/unit-1.34.0-released.rst diff --git a/source/news/2024/index.rst b/source/news/2024/index.rst index 046b6c6a..5b1db006 100644 --- a/source/news/2024/index.rst +++ b/source/news/2024/index.rst @@ -4,6 +4,15 @@ News of 2024 News archive for the year 2024. +.. nxt_news_entry:: + :author: Unit Team + :description: Version 1.34.0 includes three new configuration options and a + CLI tool. + :email: unit-owner@nginx.org + :title: Unit 1.34.0 Released + :url: news/2024/unit-1.34.0-released + :date: 2024-12-19 + .. nxt_news_entry:: :author: Unit Team :description: Version 1.33.0 includes three new configuration options and a CLI tool. diff --git a/source/news/2024/unit-1.34.0-released.rst b/source/news/2024/unit-1.34.0-released.rst new file mode 100644 index 00000000..5cfcf149 --- /dev/null +++ b/source/news/2024/unit-1.34.0-released.rst @@ -0,0 +1,159 @@ +:orphan: + +#################### +Unit 1.34.0 Released +#################### + +We are pleased to announce the release of NGINX Unit 1.34.0. This release +includes a number of new features and changes: + +************************** +JSON formatted access logs +************************** + +This release introduces the ability to specify a JSON format for access logs. + +When defining an access log you can specify 'format' as an object defining +JSON field name/value pairs, e.g. + +.. code-block:: json + + { + "access_log": { + "path": "/tmp/access.log", + "format": { + "remote_addr": "$remote_addr", + "time_local": "$time_local", + "request_line": "$request_line", + "status": "$status", + "body_bytes_sent": "$body_bytes_sent", + "header_referer": "$header_referer", + "header_user_agent": "$header_user_agent" + } + } + } + +The JSON *values* support being strings, variables and JavaScript. + +******************** +OpenTelemetry (OTEL) +******************** + +This release includes initial support for OpenTelemtry (OTEL) + + +This support has been added via the OpenTelemetry Rust SDK and as such +requires cargo/rust to build. + +An example configuration looks like + +.. code-block:: json + + { + "listeners": { + "[::1]:8080": { + "pass": "routes" + } + }, + + "settings": { + "telemetry": { + "batch_size": 20, + "endpoint": "http://example.com/v1/traces", + "protocol": "http", + "sampling_ratio": 1 + } + }, + + "routes": [ + { + "match": { + "headers": { + "accept": "*text/html*" + } + }, + "action": { + "share": "/usr/share/unit/welcome/welcome.html" + } + }, { + "action": { + "share": "/usr/share/unit/welcome/welcome.md" + } + } + ] + } + +* **endpoint** + + The endpoint for the OpenTelemetry (OTEL) Collector. This is required. + + The value must be a URL to either a gRPC or HTTP endpoint. + +* **protocol** + + Determines the protocol used to communicate with the endpoint. This is + required. + + Can be either "http" or "grpc". + +* **batch_size** + + Number of spans to cache before triggering a transaction with the + configured endpoint. This is optional. + + This allows the user to cache up to N spans before the OpenTelemetry + (OTEL) background thread sends spans over the network to the collector. + + Must be a positive integer. + +* **sampling_ratio** + + Percentage of requests to trace. This is optional. + + This allows the user to only trace anywhere from 0% to 100% of requests + that hit Unit. In high throughput environments this percentage should be + lower. This allows the user to save space in storing span data, and to + collect request metrics like time to decode headers and whatnot without + storing massive amounts of duplicate superfluous data. + + Must be a positive floating point number. + + This support is disabled by default but can be enabled by passing --otel + to ./configure. + +*************************** +Changes to language modules +*************************** + +* The Perl language module no longer adds a 'new' constructor to parsed + scripts. It's not required and could interfere with scripts that were + trying to use 'new' themselves. + +********************** +Changes for developers +********************** + +* -funsigned-char + + We now compile Unit with -funsigned-char, this ensures we are using the + same char type on all platforms (what you get by default varies by + platform). + + This is also a first step in getting rid of (mostly at least) our usage of + u_char and using char instead, which better aligns with libc interfaces and + so on. + +************** +Full Changelog +************** + +.. code-block:: none + + Changes with Unit 1.34.0 19 Dec 2024 + + *) Feature: initial OpenTelemetry (OTEL) support. (Disabled by default). + + *) Feature: support for JSON formatted access logs. + + *) Bugfix: tweak the Perl language module to avoid breaking scripts in + some circumstances. From f309118778fc6ea834586df299564a634200c49b Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 17 Dec 2024 16:57:33 +0000 Subject: [PATCH 4/5] Update CHANGES.txt for 1.34.0 Signed-off-by: Andrew Clayton --- source/CHANGES.txt | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/CHANGES.txt b/source/CHANGES.txt index 0a821f21..c79ea040 100644 --- a/source/CHANGES.txt +++ b/source/CHANGES.txt @@ -1,4 +1,14 @@ +Changes with Unit 1.34.0 19 Dec 2024 + + *) Feature: initial OpenTelemetry (OTEL) support. (Disabled by default). + + *) Feature: support for JSON formatted access logs. + + *) Bugfix: tweak the Perl language module to avoid breaking scripts in + some circumstances. + + Changes with Unit 1.33.0 17 Sep 2024 *) Feature: make the number of router threads configurable. From 1746fabc00f2e5eb1de9f623fc82d34ebeb6481e Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 17 Dec 2024 17:36:33 +0000 Subject: [PATCH 5/5] conf.py: Update for 1.34.0 Signed-off-by: Andrew Clayton --- source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/conf.py b/source/conf.py index 829b3a29..2ea5702f 100644 --- a/source/conf.py +++ b/source/conf.py @@ -5,8 +5,8 @@ project = 'NGINX Unit' author = 'NGINX, Inc.' copyright = '2017-2024' -version = '1.33.0' -release_date = 'Sep 18, 2024' +version = '1.34.0' +release_date = 'Dec 19, 2024' release = version needs_sphinx = '6.2'