From 4807120f21f27a66fbf7e1917fbc72fe4df8115c Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 8 Oct 2026 20:42:20 +0000 Subject: [PATCH 1/4] docs(influxdb): document InfluxDB OSS v2.10 options, metrics, and compaction throughput --- .../v2/reference/cli/influxd/upgrade.md | 2 + .../influxdb/v2/reference/config-options.md | 198 +++++++++++++++++- .../v2/reference/internals/metrics.md | 18 ++ .../influxdb/v2/reference/internals/shards.md | 7 +- .../v2/reference/release-notes/influxdb.md | 26 +++ 5 files changed, 239 insertions(+), 12 deletions(-) diff --git a/content/influxdb/v2/reference/cli/influxd/upgrade.md b/content/influxdb/v2/reference/cli/influxd/upgrade.md index 7476393bb0..079cab687e 100644 --- a/content/influxdb/v2/reference/cli/influxd/upgrade.md +++ b/content/influxdb/v2/reference/cli/influxd/upgrade.md @@ -24,6 +24,8 @@ This command performs the following actions: If the configuration file is not available, the 1.x database folder can be passed via th `--v1-dir` flag. 2. Copies and upgrades 1.x database files. +In InfluxDB OSS v2.10 and later, the upgrade maps the 1.x `coordinator.max-time-range` option to [`influxql-max-time-range`](/influxdb/v2/reference/config-options/#influxql-max-time-range). + The target 2.x database directory is specified by the `--engine-path` option. If changed, the bolt path can be specified by the `--bolt-path` option. diff --git a/content/influxdb/v2/reference/config-options.md b/content/influxdb/v2/reference/config-options.md index bd907ec801..d4d8cdeb07 100644 --- a/content/influxdb/v2/reference/config-options.md +++ b/content/influxdb/v2/reference/config-options.md @@ -143,10 +143,13 @@ To configure InfluxDB, use the following configuration options when starting the - [http-idle-timeout](#http-idle-timeout) - [http-read-header-timeout](#http-read-header-timeout) - [http-read-timeout](#http-read-timeout) +- [http-user-query-bytes-enabled](#http-user-query-bytes-enabled) +- [http-user-write-bytes-enabled](#http-user-write-bytes-enabled) - [http-write-timeout](#http-write-timeout) - [influxql-max-select-buckets](#influxql-max-select-buckets) - [influxql-max-select-point](#influxql-max-select-point) - [influxql-max-select-series](#influxql-max-select-series) +- [influxql-max-time-range](#influxql-max-time-range) - [instance-id](#instance-id) - [log-level](#log-level) - [metrics-disabled](#metrics-disabled) @@ -796,6 +799,115 @@ http-read-timeout = "10s" --- +### http-user-query-bytes-enabled +_Available in InfluxDB OSS v2.10 and later._ + +Enable per-user query response byte counting. +When enabled, the `/metrics` endpoint exposes the `http_query_user_response_bytes` counter with the `user_id` and `endpoint` labels. +For more information, see [HTTP API statistics](/influxdb/v2/reference/internals/metrics/#http-api-statistics). + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +| :----------- | :------------------- | :---------------- | +| `--http-user-query-bytes-enabled` | `INFLUXD_HTTP_USER_QUERY_BYTES_ENABLED` | `http-user-query-bytes-enabled` | + +###### influxd flag + + +```sh +influxd --http-user-query-bytes-enabled=true +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_USER_QUERY_BYTES_ENABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-user-query-bytes-enabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-user-query-bytes-enabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-user-query-bytes-enabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + +### http-user-write-bytes-enabled +_Available in InfluxDB OSS v2.10 and later._ + +Enable per-user write request byte counting. +When enabled, the `/metrics` endpoint exposes the `http_write_user_request_bytes` counter with the `user_id` and `endpoint` labels. +For more information, see [HTTP API statistics](/influxdb/v2/reference/internals/metrics/#http-api-statistics). + +InfluxDB doesn't count requests that don't have a valid user ID. +In InfluxDB 1.x, these requests are counted as `(anonymous)`. + +**Default:** `false` + +| influxd flag | Environment variable | Configuration key | +| :----------- | :------------------- | :---------------- | +| `--http-user-write-bytes-enabled` | `INFLUXD_HTTP_USER_WRITE_BYTES_ENABLED` | `http-user-write-bytes-enabled` | + +###### influxd flag + + +```sh +influxd --http-user-write-bytes-enabled=true +``` + +###### Environment variable +```sh +export INFLUXD_HTTP_USER_WRITE_BYTES_ENABLED=true +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +http-user-write-bytes-enabled: true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +http-user-write-bytes-enabled = true +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "http-user-write-bytes-enabled": true +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + ### http-write-timeout Maximum duration to wait before timing out writes of the response. It doesn't let Handlers decide the duration on a per-request basis. @@ -1024,6 +1136,67 @@ influxql-max-select-series = 0 --- +### influxql-max-time-range +_Available in InfluxDB OSS v2.10 and later._ + +Maximum time range, as a duration, that an InfluxQL `SELECT` or `EXPLAIN` statement can query. +`0` disables the limit. +This option doesn't apply to Flux queries. + +If a query exceeds the limit, InfluxDB returns the following error: + +```text +max-time-range limit exceeded: (/) +``` + +The `influxd upgrade` command maps the InfluxDB 1.x `coordinator.max-time-range` option to this option. + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +| :----------- | :------------------- | :---------------- | +| `--influxql-max-time-range` | `INFLUXD_INFLUXQL_MAX_TIME_RANGE` | `influxql-max-time-range` | + +###### influxd flag + + +```sh +influxd --influxql-max-time-range=72h +``` + +###### Environment variable +```sh +export INFLUXD_INFLUXQL_MAX_TIME_RANGE=72h +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +influxql-max-time-range: 72h +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +influxql-max-time-range = "72h" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "influxql-max-time-range": "72h" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + ### instance-id Identifies edge nodes during replication, and prevents collisions if two edge nodes write the same `measurement,tagset`. @@ -2194,21 +2367,25 @@ storage-compact-full-write-cold-duration = "4h0m0s" ### storage-compact-throughput Sustained rate limit (in bytes per second) that TSM compactions can write to disk. -InfluxDB also supports a separate burst limit (`storage-compact-throughput-burst`). -In InfluxDB OSS v2, the sustained and burst compaction throughput values are currently the same. -To tune compaction write throughput, set `storage-compact-throughput-burst` and verify the effective values in the `Compaction settings` log entry at startup. +In InfluxDB OSS v2.10 and later, this setting is independent of the burst limit (`storage-compact-throughput-burst`). +If the burst limit is lower than the sustained limit, InfluxDB raises the burst limit to match the sustained limit. +To verify the effective values, check the `Compaction settings` log entry at startup. -Example log entry: - -```text -Compaction settings {"max_concurrent_compactions": 7, "throughput_bytes_per_second": 50331648, "throughput_bytes_per_second_burst": 50331648} -``` +In earlier versions, you can't set this option with a flag, and the sustained and burst limits use the same value. +To tune compaction write throughput in earlier versions, set `storage-compact-throughput-burst`. **Default:** `50331648` | influxd flag | Environment variable | Configuration key | | :----------- | :------------------- | :---------------- | -| _Not available_ | `INFLUXD_STORAGE_COMPACT_THROUGHPUT` | `storage-compact-throughput` | +| `--storage-compact-throughput` | `INFLUXD_STORAGE_COMPACT_THROUGHPUT` | `storage-compact-throughput` | + +###### influxd flag + + +```sh +influxd --storage-compact-throughput=50331648 +``` ###### Environment variable ```sh @@ -2246,7 +2423,8 @@ storage-compact-throughput = 50331648 ### storage-compact-throughput-burst Maximum rate limit (in bytes per second) that TSM compactions can write to disk. -In InfluxDB OSS v2, this setting also effectively controls the sustained compaction throughput. +In InfluxDB OSS v2.10 and later, this setting is independent of the sustained limit (`storage-compact-throughput`). +In earlier versions, this setting also controls the sustained compaction throughput. #### Scale compaction throughput diff --git a/content/influxdb/v2/reference/internals/metrics.md b/content/influxdb/v2/reference/internals/metrics.md index a6b543cfb6..3da67e763b 100644 --- a/content/influxdb/v2/reference/internals/metrics.md +++ b/content/influxdb/v2/reference/internals/metrics.md @@ -448,6 +448,7 @@ http_api_requests_total{handler="platform",method="DELETE",path="/api/v2/authori ### Query request bytes Count of bytes received. +In InfluxDB OSS v2.10 and later, the `http_query_request_count`, `http_query_request_bytes`, and `http_query_response_bytes` metrics include the legacy `/query` endpoint. #### Example @@ -481,6 +482,23 @@ Count of bytes returned by the query endpoint. http_query_response_bytes{endpoint="/api/v2/query",org_id="48c88459ee424a04",status="200"} 103 ``` +### Query user response bytes + +The `http_query_user_response_bytes` counter: total number of bytes returned in query responses, by user and endpoint. +InfluxDB exposes this counter only when you enable [`http-user-query-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled). +Available in InfluxDB OSS v2.10 and later. + +Labels: `user_id`, `endpoint` + +### Write user request bytes + +The `http_write_user_request_bytes` counter: total number of bytes in write requests, by user and endpoint. +InfluxDB exposes this counter only when you enable [`http-user-write-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled). +InfluxDB doesn't count requests that don't have a valid user ID. +Available in InfluxDB OSS v2.10 and later. + +Labels: `user_id`, `endpoint` + ## InfluxDB object and query statistics ### Buckets total diff --git a/content/influxdb/v2/reference/internals/shards.md b/content/influxdb/v2/reference/internals/shards.md index 25a0e1319b..209c0ccc9f 100644 --- a/content/influxdb/v2/reference/internals/shards.md +++ b/content/influxdb/v2/reference/internals/shards.md @@ -130,13 +130,16 @@ InfluxDB schedules compactions preferentially, using the following guidelines: The following configuration settings are especially beneficial for systems with irregular loads, because they limit compactions during periods of high usage, and let compactions catch up during periods of lower load: - [`storage-compact-full-write-cold-duration`](/influxdb/v2/reference/config-options/#storage-compact-full-write-cold-duration) +- [`storage-compact-throughput`](/influxdb/v2/reference/config-options/#storage-compact-throughput) - [`storage-compact-throughput-burst`](/influxdb/v2/reference/config-options/#storage-compact-throughput-burst) - [`storage-max-concurrent-compactions`](/influxdb/v2/reference/config-options/#storage-max-concurrent-compactions) - [`storage-max-index-log-file-size`](/influxdb/v2/reference/config-options/#storage-max-index-log-file-size) - [`storage-series-file-max-concurrent-snapshot-compactions`](/influxdb/v2/reference/config-options/#storage-series-file-max-concurrent-snapshot-compactions) -In InfluxDB OSS v2, `storage-compact-throughput-burst` effectively controls both the sustained and burst compaction throughput. -Use it to scale compaction write throughput as you scale CPU and disk. +In InfluxDB OSS v2.10 and later, `storage-compact-throughput` sets the sustained compaction throughput and `storage-compact-throughput-burst` sets the burst compaction throughput. +If the burst value is lower than the sustained value, InfluxDB raises the burst value to match. +In earlier versions, `storage-compact-throughput-burst` controls both values. +Use these settings to scale compaction write throughput as you scale CPU and disk. In systems with stable loads, if compactions interfere with other operations, typically, the system is undersized for its load, and configuration changes won't help much. diff --git a/content/influxdb/v2/reference/release-notes/influxdb.md b/content/influxdb/v2/reference/release-notes/influxdb.md index e690a968b5..16a27e158c 100644 --- a/content/influxdb/v2/reference/release-notes/influxdb.md +++ b/content/influxdb/v2/reference/release-notes/influxdb.md @@ -8,6 +8,32 @@ menu: weight: 101 --- +## v2.10.0 {date="TBD"} + +### Features + +- Add the [`influxql-max-time-range`](/influxdb/v2/reference/config-options/#influxql-max-time-range) option to limit the time range of InfluxQL `SELECT` and `EXPLAIN` statements. + A query that exceeds the limit fails with a `max-time-range limit exceeded` error. + The default (`0`) disables the limit. + The limit doesn't apply to Flux queries. + `influxd upgrade` maps the 1.x `coordinator.max-time-range` option to this option. +- Add the [`http-user-write-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled) option. + When enabled, the `/metrics` endpoint exposes the `http_write_user_request_bytes` counter with the `user_id` and `endpoint` labels. + InfluxDB doesn't count requests that don't have a valid user ID. +- Add the [`http-user-query-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled) option. + When enabled, the `/metrics` endpoint exposes the `http_query_user_response_bytes` counter with the `user_id` and `endpoint` labels. +- Add the [`--storage-compact-throughput`](/influxdb/v2/reference/config-options/#storage-compact-throughput) flag. + Sustained and burst compaction throughput are now independent. + If the burst value is lower than the sustained value, InfluxDB raises the burst value to match. +- Add adaptive sizing and statistics to the TSI tag-value series ID cache. +- Update the `/health` and `/ready` endpoints and add the `--health-auth-mode` and `--startup-error-linger` options. + For API changes, see the [InfluxDB OSS v2 API reference](/influxdb/v2/api/). + +### Bug Fixes + +- Report `http_write_request_bytes` for the legacy `/write` endpoint. Previously, the metric reported `0`. +- Include the legacy `/query` endpoint in the `http_query_request_count`, `http_query_request_bytes`, and `http_query_response_bytes` metrics. + ## v2.9.1 {date="2026-05-11"} ### Bug Fixes From 6279fa69d85658ebda97823add75074a5249ddbe Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 8 Oct 2026 17:15:31 -0500 Subject: [PATCH 2/4] docs(influxdb): link compaction throughput options and lead metrics with version What changed: Cross-link storage-compact-throughput and storage-compact-throughput-burst. Move the v2.10 availability note to the first paragraph of the per-user query and write bytes metric sections. Why: Review feedback. Readers can jump between related options, and see version availability before the description. Impact: Two v2 reference pages; no behavior change. Verification: Pre-commit hooks. --- content/influxdb/v2/reference/config-options.md | 4 ++-- content/influxdb/v2/reference/internals/metrics.md | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/influxdb/v2/reference/config-options.md b/content/influxdb/v2/reference/config-options.md index d4d8cdeb07..caab28f328 100644 --- a/content/influxdb/v2/reference/config-options.md +++ b/content/influxdb/v2/reference/config-options.md @@ -2367,7 +2367,7 @@ storage-compact-full-write-cold-duration = "4h0m0s" ### storage-compact-throughput Sustained rate limit (in bytes per second) that TSM compactions can write to disk. -In InfluxDB OSS v2.10 and later, this setting is independent of the burst limit (`storage-compact-throughput-burst`). +In InfluxDB OSS v2.10 and later, this setting is independent of the burst limit ([`storage-compact-throughput-burst`](#storage-compact-throughput-burst)). If the burst limit is lower than the sustained limit, InfluxDB raises the burst limit to match the sustained limit. To verify the effective values, check the `Compaction settings` log entry at startup. @@ -2423,7 +2423,7 @@ storage-compact-throughput = 50331648 ### storage-compact-throughput-burst Maximum rate limit (in bytes per second) that TSM compactions can write to disk. -In InfluxDB OSS v2.10 and later, this setting is independent of the sustained limit (`storage-compact-throughput`). +In InfluxDB OSS v2.10 and later, this setting is independent of the sustained limit ([`storage-compact-throughput`](#storage-compact-throughput)). In earlier versions, this setting also controls the sustained compaction throughput. #### Scale compaction throughput diff --git a/content/influxdb/v2/reference/internals/metrics.md b/content/influxdb/v2/reference/internals/metrics.md index 3da67e763b..4213d88603 100644 --- a/content/influxdb/v2/reference/internals/metrics.md +++ b/content/influxdb/v2/reference/internals/metrics.md @@ -484,18 +484,20 @@ http_query_response_bytes{endpoint="/api/v2/query",org_id="48c88459ee424a04",sta ### Query user response bytes +Available in InfluxDB OSS v2.10 and later. + The `http_query_user_response_bytes` counter: total number of bytes returned in query responses, by user and endpoint. InfluxDB exposes this counter only when you enable [`http-user-query-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-query-bytes-enabled). -Available in InfluxDB OSS v2.10 and later. Labels: `user_id`, `endpoint` ### Write user request bytes +Available in InfluxDB OSS v2.10 and later. + The `http_write_user_request_bytes` counter: total number of bytes in write requests, by user and endpoint. InfluxDB exposes this counter only when you enable [`http-user-write-bytes-enabled`](/influxdb/v2/reference/config-options/#http-user-write-bytes-enabled). InfluxDB doesn't count requests that don't have a valid user ID. -Available in InfluxDB OSS v2.10 and later. Labels: `user_id`, `endpoint` From 3e192caf5d75866f78277e8ba4201cb463961fc0 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 9 Oct 2026 10:41:54 -0500 Subject: [PATCH 3/4] docs(influxdb): document v2.10 health options, exit codes, and max-time-range errors What changed: - Add health-auth-mode and startup-error-linger to the config options reference, and explain how hardening-enabled restricts /health and /ready details. - Document that influxql-max-time-range errors return HTTP 200 with the error in results[].error, and that a query with no lower time bound exceeds any non-zero limit. - Add an exit codes section to the influxd reference, with a systemd RestartPreventExitStatus example. - Add a restricted health check details section to the enable-hardening page. - Link the new options and exit codes from the v2.10 release notes. - Add the six v2.10 flags to data/influxd_flags.yml. Why: influxdata/DAR#800 acceptance criteria. The behavior was verified against a local build of main-2.x (310ee146d9). Impact: InfluxDB OSS v2 reference, admin, and release notes pages only. Verification: Ran a live influxd for the max-time-range, startup failure, linger, and health-auth-mode cases. Confirmed the environment variable names with print-config. Code-block lint and link checks pass, and the pages render on a local Hugo server. --- .../v2/admin/security/enable-hardening.md | 23 +++ .../v2/reference/cli/influxd/_index.md | 37 ++++ .../influxdb/v2/reference/config-options.md | 160 +++++++++++++++++- .../v2/reference/release-notes/influxdb.md | 13 +- data/influxd_flags.yml | 18 ++ 5 files changed, 245 insertions(+), 6 deletions(-) diff --git a/content/influxdb/v2/admin/security/enable-hardening.md b/content/influxdb/v2/admin/security/enable-hardening.md index 05fd736d5b..7acab82a80 100644 --- a/content/influxdb/v2/admin/security/enable-hardening.md +++ b/content/influxdb/v2/admin/security/enable-hardening.md @@ -23,6 +23,7 @@ when starting InfluxDB. ## Security features - [Private IP Validation](#private-ip-validation) +- [Restricted health check details](#restricted-health-check-details) ### Private IP Validation @@ -48,3 +49,25 @@ If your environment requires that these authenticated HTTP requests be made to p omit the use of `--hardening-enabled` and consider instead setting up egress firewalling to limit which hosts InfluxDB is allowed to connect. {{% /note %}} + +### Restricted health check details + +_Available in InfluxDB OSS v2.10 and later._ + +The `/health` and `/ready` endpoints report check messages that can include +file system paths, permission errors, and other configuration details. +With hardening enabled, InfluxDB returns these details only to callers with operator permissions. +Other callers receive check names and statuses only. + +The HTTP status code doesn't change, so liveness and readiness probes without credentials keep working. + +To control this behavior separately from other hardening features, +use the [`health-auth-mode` configuration option](/influxdb/v2/reference/config-options/#health-auth-mode). +For example, if your monitoring reads check messages from `/health`, +keep full responses with hardening enabled: + + + +```sh +influxd --hardening-enabled --health-auth-mode=disabled +``` diff --git a/content/influxdb/v2/reference/cli/influxd/_index.md b/content/influxdb/v2/reference/cli/influxd/_index.md index 482b38e8aa..70eaa88a02 100644 --- a/content/influxdb/v2/reference/cli/influxd/_index.md +++ b/content/influxdb/v2/reference/cli/influxd/_index.md @@ -43,3 +43,40 @@ For information about other available InfluxDB configuration methods, see {{< cli/influxd-flags >}} + +## Exit codes + +_Available in InfluxDB OSS v2.10 and later._ + +When the `influxd` server fails to start, its exit code tells you whether restarting can help. +The codes follow the BSD `sysexits.h` convention. + +| Code | Name | Meaning | Restart helps? | +| ---: | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ | +| 0 | `EX_OK` | Startup and shutdown succeeded, including a shutdown requested by a signal. | — | +| 1 | — | An error with no category. Subcommands such as `inspect`, `upgrade`, and `recovery` report all failures with this code. | Unknown | +| 64 | `EX_USAGE` | The command line is wrong: an unknown flag, a flag value that can't be parsed, or an unexpected argument. | No | +| 65 | `EX_DATAERR` | The data on disk isn't readable by this version--for example, InfluxDB 1.x `_series` or `index` directories under `--engine-path`. | No | +| 66 | `EX_NOINPUT` | A path doesn't exist or is the wrong type--for example, `--engine-path` points to a file, or a parent directory is missing. | No | +| 69 | `EX_UNAVAILABLE` | A required resource is in use: the `--http-bind-address` port, an existing `--pid-file`, or a dependency that refused the connection. | Only after the conflict clears | +| 70 | `EX_SOFTWARE` | Startup failed without an operating system cause. Read the error and the log. | No | +| 71 | `EX_OSERR` | The operating system ran out of file descriptors or memory. | After you raise the limits | +| 73 | `EX_CANTCREAT` | A file can't be created or extended: the disk is full, a quota is exhausted, or the file system is read-only. | After you free space or make the file system writable | +| 74 | `EX_IOERR` | An I/O error occurred while reading or writing, usually from hardware or a failing file system. | No | +| 75 | `EX_TEMPFAIL` | An operation didn't finish: a dependency timed out, `SIGINT` interrupted startup, or shutdown exceeded its time limit. | Yes | +| 77 | `EX_NOPERM` | Permission was denied on a data directory, PID file, TLS certificate, or privileged port. | No | +| 78 | `EX_CONFIG` | A configuration value is wrong--for example, 1.x keys in a 2.x configuration file, a configuration file that can't be parsed, or an invalid option value. | No | + +To retrieve the startup error from the `/health` and `/ready` endpoints before `influxd` exits, +set [`startup-error-linger`](/influxdb/v2/reference/config-options/#startup-error-linger). + +### Prevent restart loops with systemd + +If `influxd` exits with a code that a restart can't fix, systemd restarts it into the same failure. +To stop restarting on those codes, add `RestartPreventExitStatus` to the `influxd` service unit: + +```ini +[Service] +Restart=on-failure +RestartPreventExitStatus=64 65 66 70 74 77 78 +``` diff --git a/content/influxdb/v2/reference/config-options.md b/content/influxdb/v2/reference/config-options.md index caab28f328..f727c6ffd1 100644 --- a/content/influxdb/v2/reference/config-options.md +++ b/content/influxdb/v2/reference/config-options.md @@ -139,6 +139,7 @@ To configure InfluxDB, use the following configuration options when starting the - [feature-flags](#feature-flags) - [flux-log-enabled](#flux-log-enabled) - [hardening-enabled](#hardening-enabled) +- [health-auth-mode](#health-auth-mode) - [http-bind-address](#http-bind-address) - [http-idle-timeout](#http-idle-timeout) - [http-read-header-timeout](#http-read-header-timeout) @@ -169,6 +170,7 @@ To configure InfluxDB, use the following configuration options when starting the - [session-length](#session-length) - [session-renew-disabled](#session-renew-disabled) - [sqlite-path](#sqlite-path) +- [startup-error-linger](#startup-error-linger) - [storage-cache-max-memory-size](#storage-cache-max-memory-size) - [storage-cache-snapshot-memory-size](#storage-cache-snapshot-memory-size) - [storage-cache-snapshot-write-cold-duration](#storage-cache-snapshot-write-cold-duration) @@ -546,7 +548,14 @@ flux-log-enabled = "true" Enable [additional security features](/influxdb/v2/admin/security/enable-hardening/) in InfluxDB. + +In InfluxDB OSS v2.10 and later, hardening also restricts the detail that the +`/health` and `/ready` endpoints return to callers without operator permissions. +To keep full `/health` and `/ready` responses with hardening enabled, +set [`health-auth-mode`](#health-auth-mode) to `disabled`. + **Default:** `false` + | influxd flag | Environment variable | Configuration key | | :-------------------- | :-------------------------- | :------------------ | | `--hardening-enabled` | `INFLUXD_HARDENING_ENABLED` | `hardening-enabled` | @@ -591,6 +600,79 @@ hardening-enabled = true --- +### health-auth-mode +_Available in InfluxDB OSS v2.10 and later._ + +Controls whether the `/health` and `/ready` endpoints require operator permissions +to return check details. + +By default, `/health` and `/ready` don't require authentication and return full check details. +After a failed startup, check messages contain the raw error text, +which can include file system paths and other configuration details. +To hide these details from callers without operator permissions, set this option to `required`. + +This option never changes the HTTP status code, +so liveness and readiness probes without credentials keep working. +A caller without operator permissions receives a reduced response body: +check names and statuses, without messages or build information. +If startup fails before InfluxDB can verify tokens, +every caller receives the reduced response body. + +Valid values: + +- `auto`: Restrict details only when [`hardening-enabled`](#hardening-enabled) is `true`. +- `required`: Always restrict details. +- `disabled`: Never restrict details, even when `hardening-enabled` is `true`. + +Write the value explicitly, for example `--health-auth-mode=required`. +`true` and `false` aren't valid values. + +**Default:** `auto` + +| influxd flag | Environment variable | Configuration key | +| :----------- | :------------------- | :---------------- | +| `--health-auth-mode` | `INFLUXD_HEALTH_AUTH_MODE` | `health-auth-mode` | + +###### influxd flag + + +```sh +influxd --health-auth-mode=required +``` + +###### Environment variable +```sh +export INFLUXD_HEALTH_AUTH_MODE=required +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +health-auth-mode: required +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +health-auth-mode = "required" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "health-auth-mode": "required" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + ### http-bind-address Bind address for the InfluxDB HTTP API. Customize the URL and port for the InfluxDB API and UI. @@ -1143,12 +1225,19 @@ Maximum time range, as a duration, that an InfluxQL `SELECT` or `EXPLAIN` statem `0` disables the limit. This option doesn't apply to Flux queries. -If a query exceeds the limit, InfluxDB returns the following error: +A query with no upper time bound is measured up to `now()`. +A query with no lower time bound covers all time, so it exceeds any non-zero limit. -```text -max-time-range limit exceeded: (/) +If a statement exceeds the limit, InfluxDB returns an HTTP `200` response +and reports the error for that statement in `results[].error`: + +```json +{"results":[{"statement_id":0,"error":"max-time-range limit exceeded: (1h59m59.999999999s/1h0m0s)"}]} ``` +The error has the format `max-time-range limit exceeded: (/)`. +Check `results[].error` in your client--the HTTP status code doesn't indicate the error. + The `influxd upgrade` command maps the InfluxDB 1.x `coordinator.max-time-range` option to this option. **Default:** `0` @@ -2165,6 +2254,71 @@ sqlite-path = "~/.influxdbv2/influxd.sqlite" --- +### startup-error-linger +_Available in InfluxDB OSS v2.10 and later._ + +Duration to keep the `/health` and `/ready` endpoints serving after a failed startup +before `influxd` exits. +Use this window to retrieve the startup error from `/health` or `/ready`, +for example, when a container orchestrator restarts `influxd` before you can read its logs. + +During the window, `/health` and `/ready` return `503` with the failing checks, +and every other path returns `503` with `{"status":"starting"}`. +After the window, `influxd` exits with the [exit code](/influxdb/v2/reference/cli/influxd/#exit-codes) +for the failure. + +`0` exits immediately. +The maximum is `30m`. + +Check messages can include file system paths and other configuration details. +To restrict them to callers with operator permissions, see [`health-auth-mode`](#health-auth-mode). + +**Default:** `0` + +| influxd flag | Environment variable | Configuration key | +| :----------- | :------------------- | :---------------- | +| `--startup-error-linger` | `INFLUXD_STARTUP_ERROR_LINGER` | `startup-error-linger` | + +###### influxd flag + + +```sh +influxd --startup-error-linger=5m +``` + +###### Environment variable +```sh +export INFLUXD_STARTUP_ERROR_LINGER=5m +``` + +###### Configuration file +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[YAML](#) +[TOML](#) +[JSON](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```yml +startup-error-linger: 5m +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```toml +startup-error-linger = "5m" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```json +{ + "startup-error-linger": "5m" +} +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +--- + ### storage-cache-max-memory-size Maximum size (in bytes) a shard's cache can reach before it starts rejecting writes. diff --git a/content/influxdb/v2/reference/release-notes/influxdb.md b/content/influxdb/v2/reference/release-notes/influxdb.md index 16a27e158c..386a963b2b 100644 --- a/content/influxdb/v2/reference/release-notes/influxdb.md +++ b/content/influxdb/v2/reference/release-notes/influxdb.md @@ -13,7 +13,7 @@ weight: 101 ### Features - Add the [`influxql-max-time-range`](/influxdb/v2/reference/config-options/#influxql-max-time-range) option to limit the time range of InfluxQL `SELECT` and `EXPLAIN` statements. - A query that exceeds the limit fails with a `max-time-range limit exceeded` error. + A statement that exceeds the limit returns a `max-time-range limit exceeded` error in `results[].error` with an HTTP `200` response. The default (`0`) disables the limit. The limit doesn't apply to Flux queries. `influxd upgrade` maps the 1.x `coordinator.max-time-range` option to this option. @@ -26,8 +26,15 @@ weight: 101 Sustained and burst compaction throughput are now independent. If the burst value is lower than the sustained value, InfluxDB raises the burst value to match. - Add adaptive sizing and statistics to the TSI tag-value series ID cache. -- Update the `/health` and `/ready` endpoints and add the `--health-auth-mode` and `--startup-error-linger` options. - For API changes, see the [InfluxDB OSS v2 API reference](/influxdb/v2/api/). +- Update the `/health` and `/ready` endpoints. + During startup, `/ready` returns `503` with the readiness checks that haven't passed. + Both endpoints report an `uptime` value and more detail for each check. +- Add the [`health-auth-mode`](/influxdb/v2/reference/config-options/#health-auth-mode) option + to restrict `/health` and `/ready` check details to callers with operator permissions. + [`hardening-enabled`](/influxdb/v2/reference/config-options/#hardening-enabled) now also restricts these details. +- Add the [`startup-error-linger`](/influxdb/v2/reference/config-options/#startup-error-linger) option + to keep `/health` and `/ready` serving after a failed startup, so you can retrieve the error. +- Add [`influxd` exit codes](/influxdb/v2/reference/cli/influxd/#exit-codes) that indicate whether restarting can fix a failed startup. ### Bug Fixes diff --git a/data/influxd_flags.yml b/data/influxd_flags.yml index da78291da3..8699060882 100644 --- a/data/influxd_flags.yml +++ b/data/influxd_flags.yml @@ -29,6 +29,9 @@ - flag: "--hardening-enabled" added: 2.2 +- flag: "--health-auth-mode" + added: "2.10" + - flag: "-h, --help" added: 2.0 nolink: true @@ -45,6 +48,12 @@ - flag: "--http-read-timeout" added: 2.0 +- flag: "--http-user-query-bytes-enabled" + added: "2.10" + +- flag: "--http-user-write-bytes-enabled" + added: "2.10" + - flag: "--http-write-timeout" added: 2.0 @@ -57,6 +66,9 @@ - flag: "--influxql-max-select-series" added: 2.0 +- flag: "--influxql-max-time-range" + added: "2.10" + - flag: "--instance-id" added: 2.3 @@ -116,6 +128,9 @@ - flag: "--sqlite-path" added: 2.1 +- flag: "--startup-error-linger" + added: "2.10" + - flag: "--storage-cache-max-memory-size" added: 2.0 @@ -128,6 +143,9 @@ - flag: "--storage-compact-full-write-cold-duration" added: 2.0 +- flag: "--storage-compact-throughput" + added: "2.10" + - flag: "--storage-compact-throughput-burst" added: 2.0 From 4aa6337a8c1863cda17062ef183bff7a6528fa79 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 15 Oct 2026 15:23:49 -0500 Subject: [PATCH 4/4] docs(influxdb): add v2.10.0 release notes (#7911) * sync(api): update InfluxDB OSS v2 and Cloud v2 specs for v2.10 What changed: - Resynced both specs from influxdata/openapi master. - Adds the v2.10 `/ready` and `/health` schemas from influxdata/openapi#661: measure groups (`progress`, `failures`), `uptime`, the `/ready` 503 response, and `version` and `commit` on `/health`. - Adds the Routes keys from influxdata/openapi#658. - Doesn't add `onConflict`. influxdata/openapi#663 removed it upstream. Why: the `docs-release/influxdb-oss` branch is still at v2.9.0, so this fetches OSS from master with `getswagger.sh v2 -b`. Supersedes influxdata/docs-v2#7699, #7841, and #7286. * chore(influxdb): bump InfluxDB OSS v2 latest to v2.10.0 Sets latest to v2.10 and latest_patches.v2 to 2.10.0 in data/products.yml. Leaves latest_cli.v2 at 2.8.0, because no new influx CLI release ships with v2.10. * feat(api): exclude schema properties that InfluxDB Cloud doesn't return What changed: - post-process-specs.ts applies a new content/exclude.yml overlay that removes listed schema properties from the published spec. Stale entries log a warning and don't fail the build. - The InfluxDB Cloud denylist removes the Routes keys that Cloud 2 doesn't return: backup, plugins, restore, scrapers, setup, sources, swagger, and system. - The Cloud Setup tag now explains that Cloud doesn't support initial setup: GET /api/v2/setup always returns {"allowed": false}. - Documented exclude.yml in the API docs README, and added test 16. Why: The upstream influxdata/openapi contract shares the Routes schema between OSS and Cloud, so the Cloud reference listed routes that Cloud doesn't serve. influxdata/openapi#658 adds more OSS-only keys. Internal clients might rely on the full contract, so docs-v2 filters at publish time instead of asking upstream to remove the keys. Impact: The published InfluxDB Cloud v2 API reference only. The committed spec stays a raw upstream mirror. Verification: GET /api/v2 on a production Cloud 2 org (2026-10-08) doesn't return the excluded keys. post-process-specs tests pass (57 of 57). Running the script on influxdb/cloud removes 3 properties from the current spec; the other 5 arrive with influxdata/openapi#658. * test(api): drop redundant exit-code assertion from exclude overlay test A failed run writes no build spec, so the readYaml call that follows already fails the test. * docs(influxdb): add v2.10.0 release notes Enhance the raw GitHub release draft into Google Developer Documentation style: action-oriented descriptions, docs links for options already documented in this release cycle, and no PR links or usernames. Filters internal-only changes (tests, WAL context cleanup, build flags, CI artifact storage) that don't affect users. --- api-docs/README.md | 24 +-- api-docs/influxdb/cloud/content/exclude.yml | 20 +++ .../cloud/influxdb-cloud-v2-openapi.yaml | 99 +++++++++-- api-docs/influxdb/cloud/tags.yml | 11 +- .../influxdb/v2/influxdb-oss-v2-openapi.yaml | 160 ++++++++++++++++-- api-docs/scripts/dist/post-process-specs.js | 62 ++++++- .../scripts/dist/test-post-process-specs.js | 63 ++++++- api-docs/scripts/post-process-specs.ts | 54 ++++++ api-docs/scripts/test-post-process-specs.ts | 68 ++++++++ .../v2/reference/release-notes/influxdb.md | 17 +- data/products.yml | 4 +- 11 files changed, 531 insertions(+), 51 deletions(-) create mode 100644 api-docs/influxdb/cloud/content/exclude.yml diff --git a/api-docs/README.md b/api-docs/README.md index 3b24918006..bc558da1b0 100755 --- a/api-docs/README.md +++ b/api-docs/README.md @@ -317,12 +317,13 @@ in each product's `api-docs/` directory. Each product directory can contain overlay files that the `post-process-specs.ts` script applies to the bundled spec before article generation: -| Overlay | Location | Behavior | -| --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- | -| `content/info.yml` | `{product}/content/info.yml` | Merges each field into `spec.info`, preserving fields not in the overlay | -| `content/servers.yml` | `{product}/content/servers.yml` | Replaces `spec.servers` entirely | -| `content/page.yml` | `{product}/content/page.yml` | Sets the API landing page `description` and optional `body_extra` (e.g., callout blocks) | -| `tags.yml` | Colocated with spec | Renames tags, sets descriptions and `x-related`, drops unsupported tags | +| Overlay | Location | Behavior | +| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `content/info.yml` | `{product}/content/info.yml` | Merges each field into `spec.info`, preserving fields not in the overlay | +| `content/servers.yml` | `{product}/content/servers.yml` | Replaces `spec.servers` entirely | +| `content/page.yml` | `{product}/content/page.yml` | Sets the API landing page `description` and optional `body_extra` (e.g., callout blocks) | +| `content/exclude.yml` | `{product}/content/exclude.yml` | Removes schema properties the product doesn't return (`schemaProperties: {Schema: [prop, ...]}`). Denylist: list only properties verified absent on a live instance | +| `tags.yml` | Colocated with spec | Renames tags, sets descriptions and `x-related`, drops unsupported tags | For example, to customize the Info section for the Cloud Serverless API reference, edit `influxdb3/cloud-serverless/content/info.yml`. @@ -468,11 +469,12 @@ The post-processor looks for content files in two locations, in order: For products with multiple APIs (e.g., Cloud Dedicated has both data and management APIs), the spec-specific directory takes precedence. -| Overlay | Behavior | -| ------------- | ---------------------------------------------------------------------------------------- | -| `info.yml` | Merges each field into `spec.info`, preserving fields not in the overlay | -| `servers.yml` | Replaces `spec.servers` entirely | -| `tags.yml` | Colocated with spec (not in `content/`). Renames tags, sets descriptions and `x-related` | +| Overlay | Behavior | +| ------------- | ------------------------------------------------------------------------------------------- | +| `info.yml` | Merges each field into `spec.info`, preserving fields not in the overlay | +| `servers.yml` | Replaces `spec.servers` entirely | +| `exclude.yml` | Removes listed schema properties. To remove whole endpoints, use `drop: true` in `tags.yml` | +| `tags.yml` | Colocated with spec (not in `content/`). Renames tags, sets descriptions and `x-related` | #### Reviewing tags across products diff --git a/api-docs/influxdb/cloud/content/exclude.yml b/api-docs/influxdb/cloud/content/exclude.yml new file mode 100644 index 0000000000..1a4e82ab22 --- /dev/null +++ b/api-docs/influxdb/cloud/content/exclude.yml @@ -0,0 +1,20 @@ +# Schema properties that the upstream influxdata/openapi contract lists for +# InfluxDB Cloud, but that Cloud doesn't return. post-process-specs.ts removes +# them from the published spec. This is a denylist: list only properties +# verified absent on a live Cloud instance. +# +# To remove a whole endpoint, set `drop: true` on its tag in ../tags.yml. + +schemaProperties: + # GET /api/v2 on Cloud 2 (verified 2026-10-08) doesn't return these keys. + # backup, restore, plugins, scrapers, and swagger arrive with + # influxdata/openapi#658; Cloud serves telegraf plugins as telegraf.plugins. + Routes: + - backup + - plugins + - restore + - scrapers + - setup + - sources + - swagger + - system diff --git a/api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml b/api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml index 139e2e2709..53782ba870 100644 --- a/api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml +++ b/api-docs/influxdb/cloud/influxdb-cloud-v2-openapi.yaml @@ -14349,14 +14349,24 @@ components: - type type: object HealthCheck: + additionalProperties: + $ref: '#/components/schemas/HealthCheckMeasure' + description: | + A health check. + A check can also report measure groups, such as `progress` or `failures`. + Each key other than `name`, `status`, `message`, and `checks` whose value + is an object is a measure group. properties: checks: items: $ref: '#/components/schemas/HealthCheck' type: array commit: + description: Build commit. Returned only at the top level. type: string message: + description: | + Status detail. For a failing check, may contain the raw error text. type: string name: type: string @@ -14366,11 +14376,29 @@ components: - fail type: string version: + description: Build version. Returned only at the top level. type: string required: - name - status type: object + HealthCheckMeasure: + additionalProperties: + type: number + description: | + A measure group: one or more numeric values that share a unit. + Durations are float seconds with `unit: seconds`. + example: + completed: 94 + total: 200 + unit: shards + properties: + unit: + example: shards + type: string + required: + - unit + type: object HeatmapViewProperties: properties: adaptiveZoomHide: @@ -16282,6 +16310,13 @@ components: type: object Ready: properties: + checks: + description: | + Ready gates that haven't passed. + Omitted when `status` is `ready`. + items: + $ref: '#/components/schemas/HealthCheck' + type: array started: example: '2019-03-13T10:09:33.891196-04:00' format: date-time @@ -16289,10 +16324,15 @@ components: status: enum: - ready + - starting type: string up: example: 14m45.911966424s type: string + uptime: + allOf: + - $ref: '#/components/schemas/HealthCheckMeasure' + description: Time since `started`, in float seconds. type: object RegexpLiteral: description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 @@ -16482,12 +16522,21 @@ components: authorizations: format: uri type: string + backup: + format: uri + type: string buckets: format: uri type: string + checks: + format: uri + type: string dashboards: format: uri type: string + delete: + format: uri + type: string external: properties: statusFeed: @@ -16497,12 +16546,24 @@ components: flags: format: uri type: string + labels: + format: uri + type: string me: format: uri type: string + notificationEndpoints: + format: uri + type: string + notificationRules: + format: uri + type: string orgs: format: uri type: string + plugins: + format: uri + type: string query: properties: analyze: @@ -16518,6 +16579,12 @@ components: format: uri type: string type: object + restore: + format: uri + type: string + scrapers: + format: uri + type: string setup: format: uri type: string @@ -16530,6 +16597,9 @@ components: sources: format: uri type: string + swagger: + format: uri + type: string system: properties: debug: @@ -16541,6 +16611,9 @@ components: metrics: format: uri type: string + ready: + format: uri + type: string type: object tasks: format: uri @@ -17871,12 +17944,15 @@ components: properties: defaultValue: description: Default value that will be provided for the reference when no value is provided - nullable: true oneOf: - - type: string - - type: integer - - type: number - - type: boolean + - nullable: true + type: string + - nullable: true + type: integer + - nullable: true + type: number + - nullable: true + type: boolean envRefKey: description: Key identified as environment reference and is the key identified in the template type: string @@ -17885,12 +17961,15 @@ components: type: string value: description: Value provided to fulfill reference - nullable: true oneOf: - - type: string - - type: integer - - type: number - - type: boolean + - nullable: true + type: string + - nullable: true + type: integer + - nullable: true + type: number + - nullable: true + type: boolean required: - resourceField - envRefKey diff --git a/api-docs/influxdb/cloud/tags.yml b/api-docs/influxdb/cloud/tags.yml index 8691c4bc39..a58249d586 100644 --- a/api-docs/influxdb/cloud/tags.yml +++ b/api-docs/influxdb/cloud/tags.yml @@ -240,9 +240,18 @@ tags: Security and access endpoints: description: | Endpoints for managing authentication and access control in InfluxDB Cloud. + # GET /api/v2/setup returns {"allowed": false} on Cloud 2 (verified + # 2026-10-08), so the endpoints stay documented with this caveat. Setup: description: | - Configure an initial InfluxDB Cloud instance, including creating the initial user, organization, and bucket. + Check whether an InfluxDB instance allows initial setup. + + InfluxDB Cloud doesn't support initial setup. + Every InfluxDB Cloud account already has a user and an organization, + so `GET /api/v2/setup` always returns `{"allowed": false}`, + and the `POST` setup endpoints don't apply to InfluxDB Cloud. + To set up an InfluxDB OSS 2.x instance, see the + [InfluxDB OSS v2 setup endpoints](/influxdb/v2/api/setup/). Signin: description: | Create a user session by signing in with username and password credentials. diff --git a/api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml b/api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml index 8fd864270d..f0a47246f9 100644 --- a/api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml +++ b/api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml @@ -4514,7 +4514,14 @@ paths: - Config /health: get: - description: Returns the health of the instance. + description: | + Returns the health of the instance. + + `--health-auth-mode` and `--hardening-enabled` reduce the response body + for callers without operator permissions. + Those callers don't receive check messages, measure groups, `version`, + or `commit`. + The status code never changes. operationId: GetHealth parameters: - $ref: '#/components/parameters/TraceSpan' @@ -4522,6 +4529,18 @@ paths: '200': content: application/json: + example: + checks: + - failures: + count: 0 + unit: shards + name: shards + status: pass + commit: 310ee146d9 + message: healthy + name: influxdb + status: pass + version: v2.10.0 schema: $ref: '#/components/schemas/HealthCheck' description: | @@ -4532,7 +4551,9 @@ paths: application/json: schema: $ref: '#/components/schemas/HealthCheck' - description: The instance is unhealthy. + description: | + The instance is unhealthy. + `message` contains the message of the first failing check. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -7993,6 +8014,12 @@ paths: --header "Authorization: Token INFLUX_API_TOKEN" /ready: get: + description: | + Returns the readiness of the instance. + + `--health-auth-mode` and `--hardening-enabled` can withhold `checks` + from callers without operator permissions. + They never change the status code. operationId: GetReady parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8000,9 +8027,39 @@ paths: '200': content: application/json: + example: + started: '2026-05-26T15:42:30.123456789Z' + status: ready + up: 1m32.4s + uptime: + unit: seconds + value: 92.4 schema: $ref: '#/components/schemas/Ready' description: The instance is ready + '503': + content: + application/json: + example: + checks: + - message: loading shards 47.0% (94 / 200) + name: shards + progress: + completed: 94 + total: 200 + unit: shards + status: fail + started: '2026-05-26T15:42:30.123456789Z' + status: starting + up: 1.2s + uptime: + unit: seconds + value: 1.2 + schema: + $ref: '#/components/schemas/Ready' + description: | + The instance is starting or shutting down. + `checks` contains only the ready gates that haven't passed. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -15266,14 +15323,24 @@ components: - type type: object HealthCheck: + additionalProperties: + $ref: '#/components/schemas/HealthCheckMeasure' + description: | + A health check. + A check can also report measure groups, such as `progress` or `failures`. + Each key other than `name`, `status`, `message`, and `checks` whose value + is an object is a measure group. properties: checks: items: $ref: '#/components/schemas/HealthCheck' type: array commit: + description: Build commit. Returned only at the top level. type: string message: + description: | + Status detail. For a failing check, may contain the raw error text. type: string name: type: string @@ -15283,11 +15350,29 @@ components: - fail type: string version: + description: Build version. Returned only at the top level. type: string required: - name - status type: object + HealthCheckMeasure: + additionalProperties: + type: number + description: | + A measure group: one or more numeric values that share a unit. + Durations are float seconds with `unit: seconds`. + example: + completed: 94 + total: 200 + unit: shards + properties: + unit: + example: shards + type: string + required: + - unit + type: object HeatmapViewProperties: properties: adaptiveZoomHide: @@ -16905,6 +16990,13 @@ components: type: object Ready: properties: + checks: + description: | + Ready gates that haven't passed. + Omitted when `status` is `ready`. + items: + $ref: '#/components/schemas/HealthCheck' + type: array started: example: '2019-03-13T10:09:33.891196-04:00' format: date-time @@ -16912,10 +17004,15 @@ components: status: enum: - ready + - starting type: string up: example: 14m45.911966424s type: string + uptime: + allOf: + - $ref: '#/components/schemas/HealthCheckMeasure' + description: Time since `started`, in float seconds. type: object RegexpLiteral: description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 @@ -17329,12 +17426,21 @@ components: authorizations: format: uri type: string + backup: + format: uri + type: string buckets: format: uri type: string + checks: + format: uri + type: string dashboards: format: uri type: string + delete: + format: uri + type: string external: properties: statusFeed: @@ -17344,12 +17450,24 @@ components: flags: format: uri type: string + labels: + format: uri + type: string me: format: uri type: string + notificationEndpoints: + format: uri + type: string + notificationRules: + format: uri + type: string orgs: format: uri type: string + plugins: + format: uri + type: string query: properties: analyze: @@ -17365,6 +17483,12 @@ components: format: uri type: string type: object + restore: + format: uri + type: string + scrapers: + format: uri + type: string setup: format: uri type: string @@ -17377,6 +17501,9 @@ components: sources: format: uri type: string + swagger: + format: uri + type: string system: properties: debug: @@ -17388,6 +17515,9 @@ components: metrics: format: uri type: string + ready: + format: uri + type: string type: object tasks: format: uri @@ -18771,12 +18901,15 @@ components: properties: defaultValue: description: Default value that will be provided for the reference when no value is provided - nullable: true oneOf: - - type: string - - type: integer - - type: number - - type: boolean + - nullable: true + type: string + - nullable: true + type: integer + - nullable: true + type: number + - nullable: true + type: boolean envRefKey: description: Key identified as environment reference and is the key identified in the template type: string @@ -18785,12 +18918,15 @@ components: type: string value: description: Value provided to fulfill reference - nullable: true oneOf: - - type: string - - type: integer - - type: number - - type: boolean + - nullable: true + type: string + - nullable: true + type: integer + - nullable: true + type: number + - nullable: true + type: boolean required: - resourceField - envRefKey diff --git a/api-docs/scripts/dist/post-process-specs.js b/api-docs/scripts/dist/post-process-specs.js index bfa8ecd57e..2cd4f74c89 100644 --- a/api-docs/scripts/dist/post-process-specs.js +++ b/api-docs/scripts/dist/post-process-specs.js @@ -34,13 +34,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? ( }) : function(o, v) { o["default"] = v; }); -var __importStar = (this && this.__importStar) || function (mod) { - if (mod && mod.__esModule) return mod; - var result = {}; - if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k); - __setModuleDefault(result, mod); - return result; -}; +var __importStar = (this && this.__importStar) || (function () { + var ownKeys = function(o) { + ownKeys = Object.getOwnPropertyNames || function (o) { + var ar = []; + for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k; + return ar; + }; + return ownKeys(o); + }; + return function (mod) { + if (mod && mod.__esModule) return mod; + var result = {}; + if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]); + __setModuleDefault(result, mod); + return result; + }; +})(); Object.defineProperty(exports, "__esModule", { value: true }); const fs = __importStar(require("fs")); const path = __importStar(require("path")); @@ -165,6 +175,43 @@ function applyServersOverlay(spec, specDir, productAbsDir, label) { log(`${label}: applied ${servers.length} server(s) from ${path.relative(productAbsDir, serversPath)}`); return true; } +/** + * Apply exclude.yml overlay to the spec. Removes schema properties that the + * upstream contract lists but the product doesn't serve, so the published + * reference describes only live behavior. Remove whole endpoints with + * `drop: true` in tags.yml instead. + * + * @returns true if any properties were removed. + */ +function applyExcludeOverlay(spec, specDir, productAbsDir, label) { + const excludePath = resolveContentFile('exclude.yml', specDir, productAbsDir); + if (!excludePath) + return false; + const exclude = loadYaml(excludePath); + if (!exclude?.schemaProperties) + return false; + const schemas = spec.components + ?.schemas; + let removed = 0; + for (const [schemaName, props] of Object.entries(exclude.schemaProperties)) { + const schema = schemas?.[schemaName]; + if (!schema?.properties) { + log(`WARN ${label}: exclude.yml schema '${schemaName}' not found`); + continue; + } + for (const prop of props) { + if (!(prop in schema.properties)) + continue; + delete schema.properties[prop]; + removed++; + } + if (schema.required) { + schema.required = schema.required.filter((p) => !props.includes(p)); + } + } + log(`${label}: removed ${removed} schema propert${removed === 1 ? 'y' : 'ies'} from ${path.relative(productAbsDir, excludePath)}`); + return removed > 0; +} // --------------------------------------------------------------------------- // Mirror-product presentation transforms // @@ -510,6 +557,7 @@ function processProduct(apiDocsRoot, productDir) { } applyInfoOverlay(spec, specDir, productAbsDir, label); applyServersOverlay(spec, specDir, productAbsDir, label); + applyExcludeOverlay(spec, specDir, productAbsDir, label); const tagConfigPath = path.join(specDir, 'tags.yml'); if (fs.existsSync(tagConfigPath)) { applyTagConfig(spec, tagConfigPath, label); diff --git a/api-docs/scripts/dist/test-post-process-specs.js b/api-docs/scripts/dist/test-post-process-specs.js index aa798ce047..997f99a0de 100644 --- a/api-docs/scripts/dist/test-post-process-specs.js +++ b/api-docs/scripts/dist/test-post-process-specs.js @@ -27,13 +27,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? ( }) : function(o, v) { o["default"] = v; }); -var __importStar = (this && this.__importStar) || function (mod) { - if (mod && mod.__esModule) return mod; - var result = {}; - if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k); - __setModuleDefault(result, mod); - return result; -}; +var __importStar = (this && this.__importStar) || (function () { + var ownKeys = function(o) { + ownKeys = Object.getOwnPropertyNames || function (o) { + var ar = []; + for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k; + return ar; + }; + return ownKeys(o); + }; + return function (mod) { + if (mod && mod.__esModule) return mod; + var result = {}; + if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]); + __setModuleDefault(result, mod); + return result; + }; +})(); Object.defineProperty(exports, "__esModule", { value: true }); const fs = __importStar(require("fs")); const path = __importStar(require("path")); @@ -344,6 +354,44 @@ function testServersOverlay() { cleanup(root); } } +// 16. Exclude overlay removes listed schema properties +function testExcludeOverlay() { + const { root, specDir, specPath, buildSpecPath } = createTmpRoot(); + try { + writeYaml(specPath, makeSpec([], [], { + components: { + schemas: { + Routes: { + properties: { + buckets: { type: 'string' }, + backup: { type: 'string' }, + system: { type: 'object' }, + }, + required: ['buckets', 'backup'], + }, + }, + }, + })); + const contentDir = path.join(specDir, 'content'); + fs.mkdirSync(contentDir, { recursive: true }); + writeYaml(path.join(contentDir, 'exclude.yml'), { + schemaProperties: { + Routes: ['backup', 'system', 'notInSpec'], + Missing: ['anything'], + }, + }); + const { stderr } = runScript(root, 'influxdb3/core'); + const spec = readYaml(buildSpecPath); + const routes = spec.components.schemas.Routes; + assert('16b. listed properties removed', !('backup' in routes.properties) && !('system' in routes.properties), `properties: ${Object.keys(routes.properties).join(', ')}`); + assert('16c. unlisted properties kept', 'buckets' in routes.properties, 'buckets missing'); + assert('16d. removed properties dropped from required', JSON.stringify(routes.required) === JSON.stringify(['buckets']), `required: ${JSON.stringify(routes.required)}`); + assert('16e. warns on missing schema', stderr.includes("exclude.yml schema 'Missing' not found"), 'no warning for missing schema'); + } + finally { + cleanup(root); + } +} // 11. Info overlay preserves fields not in overlay function testInfoOverlayPreservesFields() { const { root, specDir, specPath, buildSpecPath } = createTmpRoot(); @@ -536,6 +584,7 @@ const tests = [ ['13. Combined: info + servers + tags', testCombinedOverlaysAndTags], ['14. Mirror-product presentation transforms', testMirrorProductTransforms], ['15. Non-mirror product unaffected', testNonMirrorProductUnaffected], + ['16. Exclude overlay removes schema properties', testExcludeOverlay], ]; console.log('\npost-process-specs tests\n'); for (const [name, fn] of tests) { diff --git a/api-docs/scripts/post-process-specs.ts b/api-docs/scripts/post-process-specs.ts index 1ffcc39ec2..6259a1437b 100644 --- a/api-docs/scripts/post-process-specs.ts +++ b/api-docs/scripts/post-process-specs.ts @@ -253,6 +253,59 @@ function applyServersOverlay( return true; } +/** Shape of an `exclude.yml` overlay. */ +interface ExcludeYml { + /** Schema name -> property names the product doesn't return. */ + schemaProperties?: Record; +} + +/** + * Apply exclude.yml overlay to the spec. Removes schema properties that the + * upstream contract lists but the product doesn't serve, so the published + * reference describes only live behavior. Remove whole endpoints with + * `drop: true` in tags.yml instead. + * + * @returns true if any properties were removed. + */ +function applyExcludeOverlay( + spec: OpenApiSpec, + specDir: string, + productAbsDir: string, + label: string +): boolean { + const excludePath = resolveContentFile('exclude.yml', specDir, productAbsDir); + if (!excludePath) return false; + + const exclude = loadYaml(excludePath); + if (!exclude?.schemaProperties) return false; + + const schemas = (spec.components as { schemas?: Record }) + ?.schemas; + let removed = 0; + for (const [schemaName, props] of Object.entries(exclude.schemaProperties)) { + const schema = schemas?.[schemaName] as + | { properties?: Record; required?: string[] } + | undefined; + if (!schema?.properties) { + log(`WARN ${label}: exclude.yml schema '${schemaName}' not found`); + continue; + } + for (const prop of props) { + if (!(prop in schema.properties)) continue; + delete schema.properties[prop]; + removed++; + } + if (schema.required) { + schema.required = schema.required.filter((p) => !props.includes(p)); + } + } + + log( + `${label}: removed ${removed} schema propert${removed === 1 ? 'y' : 'ies'} from ${path.relative(productAbsDir, excludePath)}` + ); + return removed > 0; +} + // --------------------------------------------------------------------------- // Mirror-product presentation transforms // @@ -680,6 +733,7 @@ function processProduct(apiDocsRoot: string, productDir: string): void { } applyInfoOverlay(spec, specDir, productAbsDir, label); applyServersOverlay(spec, specDir, productAbsDir, label); + applyExcludeOverlay(spec, specDir, productAbsDir, label); const tagConfigPath = path.join(specDir, 'tags.yml'); if (fs.existsSync(tagConfigPath)) { diff --git a/api-docs/scripts/test-post-process-specs.ts b/api-docs/scripts/test-post-process-specs.ts index 828520311f..ee193b7125 100644 --- a/api-docs/scripts/test-post-process-specs.ts +++ b/api-docs/scripts/test-post-process-specs.ts @@ -505,6 +505,73 @@ function testServersOverlay(): void { } } +// 16. Exclude overlay removes listed schema properties +function testExcludeOverlay(): void { + const { root, specDir, specPath, buildSpecPath } = createTmpRoot(); + try { + writeYaml( + specPath, + makeSpec([], [], { + components: { + schemas: { + Routes: { + properties: { + buckets: { type: 'string' }, + backup: { type: 'string' }, + system: { type: 'object' }, + }, + required: ['buckets', 'backup'], + }, + }, + }, + }) + ); + + const contentDir = path.join(specDir, 'content'); + fs.mkdirSync(contentDir, { recursive: true }); + writeYaml(path.join(contentDir, 'exclude.yml'), { + schemaProperties: { + Routes: ['backup', 'system', 'notInSpec'], + Missing: ['anything'], + }, + }); + + const { stderr } = runScript(root, 'influxdb3/core'); + + const spec = readYaml<{ + components: { + schemas: Record< + string, + { properties: Record; required?: string[] } + >; + }; + }>(buildSpecPath); + const routes = spec.components.schemas.Routes!; + assert( + '16b. listed properties removed', + !('backup' in routes.properties) && !('system' in routes.properties), + `properties: ${Object.keys(routes.properties).join(', ')}` + ); + assert( + '16c. unlisted properties kept', + 'buckets' in routes.properties, + 'buckets missing' + ); + assert( + '16d. removed properties dropped from required', + JSON.stringify(routes.required) === JSON.stringify(['buckets']), + `required: ${JSON.stringify(routes.required)}` + ); + assert( + '16e. warns on missing schema', + stderr.includes("exclude.yml schema 'Missing' not found"), + 'no warning for missing schema' + ); + } finally { + cleanup(root); + } +} + // 11. Info overlay preserves fields not in overlay function testInfoOverlayPreservesFields(): void { const { root, specDir, specPath, buildSpecPath } = createTmpRoot(); @@ -812,6 +879,7 @@ const tests: Array<[string, () => void]> = [ ['13. Combined: info + servers + tags', testCombinedOverlaysAndTags], ['14. Mirror-product presentation transforms', testMirrorProductTransforms], ['15. Non-mirror product unaffected', testNonMirrorProductUnaffected], + ['16. Exclude overlay removes schema properties', testExcludeOverlay], ]; console.log('\npost-process-specs tests\n'); diff --git a/content/influxdb/v2/reference/release-notes/influxdb.md b/content/influxdb/v2/reference/release-notes/influxdb.md index 0547104d69..66c08742ba 100644 --- a/content/influxdb/v2/reference/release-notes/influxdb.md +++ b/content/influxdb/v2/reference/release-notes/influxdb.md @@ -8,7 +8,7 @@ menu: weight: 101 --- -## v2.10.0 {date="TBD"} +## v2.10.0 {date="2026-10-15"} ### Features @@ -35,12 +35,27 @@ weight: 101 - Add the [`startup-error-linger`](/influxdb/v2/reference/config-options/#startup-error-linger) option to keep `/health` and `/ready` serving after a failed startup, so you can retrieve the error. - Add [`influxd` exit codes](/influxdb/v2/reference/cli/influxd/#exit-codes) that indicate whether restarting can fix a failed startup. +- Set a `Strict-Transport-Security` header on responses when hardening is enabled. +- Add partial results support to `SHOW MEASUREMENTS`. A query that hits a limit returns the measurements found so far instead of failing. +- Split the `tsm1` `FileStore` lock into separate fast and slow locks to reduce contention during compaction. ### Bug Fixes +- Release TSM cursor references once when a Flux query is canceled, instead of leaking them. +- Prevent a compaction level regression when compacting TSM files at mixed levels. +- Fix a race in shard loading. +- Require check names to be unique and nonempty. +- Remove a shard's per-shard Prometheus series when InfluxDB deletes the shard. - Report `http_write_request_bytes` for the legacy `/write` endpoint. Previously, the metric reported `0`. - Include the legacy `/query` endpoint in the `http_query_request_count`, `http_query_request_bytes`, and `http_query_response_bytes` metrics. +### Maintenance + +- Upgrade Go to 1.26.9. +- Upgrade Flux to v0.201.0. +- Update the InfluxDB UI to v2.10.0. +- Update containerd from 1.7.35 to 1.7.36. + ## v2.9.1 {date="2026-05-11"} ### Bug Fixes diff --git a/data/products.yml b/data/products.yml index 82d3bd8217..8cdf424349 100644 --- a/data/products.yml +++ b/data/products.yml @@ -302,9 +302,9 @@ influxdb: - v2 - v1 supports_flux: true - latest: v2.9 + latest: v2.10 latest_patches: - v2: 2.9.1 + v2: 2.10.0 v1: 1.13.0 latest_cli: v2: 2.8.0