From 9d811560fda19582d09310917445b8b269dce49a Mon Sep 17 00:00:00 2001
From: Andrew Clayton <a.clayton@nginx.com>
Date: Tue, 17 Dec 2024 22:04:09 +0000
Subject: [PATCH] configuration: Add settings/telemetry section

This is for OpenTelemetry (OTEL).

Signed-off-by: Andrew Clayton <a.clayton@nginx.com>
---
 source/configuration/index.rst | 59 ++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/source/configuration/index.rst b/source/configuration/index.rst
index b4d3bb69..29909bc8 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:
 
 **********