From 20d89296a70d0d21ababa945f81cd9ca06440e72 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Dec 2025 16:40:46 +0000 Subject: [PATCH 1/3] Initial plan From 29c1a51b49a3599321c11c21b99fe1e0b8bf9a1b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Dec 2025 16:48:54 +0000 Subject: [PATCH 2/3] docs: move perf-debug example output to query command reference Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> --- .../reference/cli/influxctl/query.md | 94 +++++++++++++++++++ .../reference/cli/influxctl/query.md | 94 +++++++++++++++++++ content/shared/influxctl/release-notes.md | 46 --------- 3 files changed, 188 insertions(+), 46 deletions(-) diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md index 4c83125680..d65e5fcba0 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md @@ -76,6 +76,7 @@ influxctl query [flags] | | `--enable-system-tables` | Enable ability to query system tables | | | `--format` | Output format (`table` _(default)_ or `json`) | | | `--language` | Query language (`sql` _(default)_ or `influxql`) | +| | `--perf-debug` | Output performance statistics and gRPC response trailers instead of query results | | | `--time-format` | Time format for table output (`rfc3339nano` _(default)_ or `unixnano`) | | | `--token` | Database token with read permissions on the queried database | | `-h` | `--help` | Output command help | @@ -92,6 +93,7 @@ _Also see [`influxctl` global flags](/influxdb3/cloud-dedicated/reference/cli/in - [Query InfluxDB 3 and return results in JSON format](#query-influxdb-3-and-return-results-in-json-format) - [Query InfluxDB 3 and return results with Unix nanosecond timestamps](#query-influxdb-3-and-return-results-with-unix-nanosecond-timestamps) - [Query InfluxDB 3 using credentials from the connection profile](#query-influxdb-3-using-credentials-from-the-connection-profile) +- [Output query performance statistics](#output-query-performance-statistics) - [Query data from InfluxDB 3 system tables](#query-data-from-influxdb-3-system-tables) In the examples below, replace the following: @@ -407,6 +409,93 @@ influxctl query "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'" ``` {{% /influxdb/custom-timestamps %}} +### Output query performance statistics + +Use the `--perf-debug` flag to output performance statistics and gRPC response +trailers instead of query results. +This is useful for debugging query performance and understanding query execution. + +{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Table format](#) +[JSON format](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --perf-debug \ + --format table \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --perf-debug \ + --format json \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +{{< expand-wrapper >}} +{{% expand "View example table-formatted performance statistics" %}} +``` ++--------------------------+----------+ +| Metric | Value | ++--------------------------+----------+ +| Client Duration | 1.222 s | +| Output Rows | 20 | +| Output Size | 647 B | ++--------------------------+----------+ +| Compute Duration | 37.2 ms | +| Execution Duration | 243.8 ms | +| Ingester Latency Data | 0 | +| Ingester Latency Plan | 0 | +| Ingester Partition Count | 0 | +| Ingester Response | 0 B | +| Ingester Response Rows | 0 | +| Max Memory | 70 KiB | +| Parquet Files | 1 | +| Partitions | 1 | +| Planning Duration | 9.6 ms | +| Queue Duration | 286.6 µs | ++--------------------------+----------+ +``` +{{% /expand %}} +{{% expand "View example JSON-formatted performance statistics" %}} +```json +{ + "client_duration_secs": 1.101, + "compute_duration_secs": 0.037, + "execution_duration_secs": 0.247, + "ingester_latency_data": 0, + "ingester_latency_plan": 0, + "ingester_partition_count": 0, + "ingester_response_bytes": 0, + "ingester_response_rows": 0, + "max_memory_bytes": 71744, + "output_bytes": 647, + "output_rows": 20, + "parquet_files": 1, + "partitions": 1, + "planning_duration_secs": 0.009, + "queue_duration_secs": 0 +} +``` +{{% /expand %}} +{{< /expand-wrapper >}} + ### Query data from InfluxDB 3 system tables > [!Note] @@ -460,6 +549,11 @@ cat ./query.sql | influxctl query \ {{% expand "View command updates" %}} +#### v2.12.0 {date="2025-12-09"} + +- Add `--perf-debug` flag to output performance statistics and gRPC response + trailers instead of query results. + #### v2.9.0 {date="2024-05-06"} - Add `--time-format` flag to specify which timestamp format to use in the diff --git a/content/influxdb3/clustered/reference/cli/influxctl/query.md b/content/influxdb3/clustered/reference/cli/influxctl/query.md index d09a45f2d5..e3ad09c50d 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/query.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/query.md @@ -74,6 +74,7 @@ influxctl query [flags] | | `--enable-system-tables` | Enable ability to query system tables | | | `--format` | Output format (`table` _(default)_ or `json`) | | | `--language` | Query language (`sql` _(default)_ or `influxql`) | +| | `--perf-debug` | Output performance statistics and gRPC response trailers instead of query results | | | `--time-format` | Time format for table output (`rfc3339nano` _(default)_ or `unixnano`) | | | `--token` | Database token with read permissions on the queried database | | `-h` | `--help` | Output command help | @@ -90,6 +91,7 @@ _Also see [`influxctl` global flags](/influxdb3/clustered/reference/cli/influxct - [Query InfluxDB 3 and return results in JSON format](#query-influxdb-3-and-return-results-in-json-format) - [Query InfluxDB 3 and return results with Unix nanosecond timestamps](#query-influxdb-3-and-return-results-with-unix-nanosecond-timestamps) - [Query InfluxDB 3 using credentials from the connection profile](#query-influxdb-3-using-credentials-from-the-connection-profile) +- [Output query performance statistics](#output-query-performance-statistics) - [Query data from InfluxDB 3 system tables](#query-data-from-influxdb-3-system-tables) In the examples below, replace the following: @@ -405,6 +407,93 @@ influxctl query "SELECT * FROM home WHERE time >= '2022-01-01T08:00:00Z'" ``` {{% /influxdb/custom-timestamps %}} +### Output query performance statistics + +Use the `--perf-debug` flag to output performance statistics and gRPC response +trailers instead of query results. +This is useful for debugging query performance and understanding query execution. + +{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[Table format](#) +[JSON format](#) +{{% /code-tabs %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --perf-debug \ + --format table \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)" +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} +```sh +influxctl query \ + --perf-debug \ + --format json \ + --token DATABASE_TOKEN \ + --database DATABASE_NAME \ + --language influxql \ + "SELECT SUM(temp) FROM home WHERE time > now() - 1h GROUP BY time(5m)" +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +{{% /code-placeholders %}} + +{{< expand-wrapper >}} +{{% expand "View example table-formatted performance statistics" %}} +``` ++--------------------------+----------+ +| Metric | Value | ++--------------------------+----------+ +| Client Duration | 1.222 s | +| Output Rows | 20 | +| Output Size | 647 B | ++--------------------------+----------+ +| Compute Duration | 37.2 ms | +| Execution Duration | 243.8 ms | +| Ingester Latency Data | 0 | +| Ingester Latency Plan | 0 | +| Ingester Partition Count | 0 | +| Ingester Response | 0 B | +| Ingester Response Rows | 0 | +| Max Memory | 70 KiB | +| Parquet Files | 1 | +| Partitions | 1 | +| Planning Duration | 9.6 ms | +| Queue Duration | 286.6 µs | ++--------------------------+----------+ +``` +{{% /expand %}} +{{% expand "View example JSON-formatted performance statistics" %}} +```json +{ + "client_duration_secs": 1.101, + "compute_duration_secs": 0.037, + "execution_duration_secs": 0.247, + "ingester_latency_data": 0, + "ingester_latency_plan": 0, + "ingester_partition_count": 0, + "ingester_response_bytes": 0, + "ingester_response_rows": 0, + "max_memory_bytes": 71744, + "output_bytes": 647, + "output_rows": 20, + "parquet_files": 1, + "partitions": 1, + "planning_duration_secs": 0.009, + "queue_duration_secs": 0 +} +``` +{{% /expand %}} +{{< /expand-wrapper >}} + ### Query data from InfluxDB 3 system tables > [!Note] @@ -458,6 +547,11 @@ cat ./query.sql | influxctl query \ {{% expand "View command updates" %}} +#### v2.12.0 {date="2025-12-09"} + +- Add `--perf-debug` flag to output performance statistics and gRPC response + trailers instead of query results. + #### v2.9.0 {date="2024-05-06"} - Add `--time-format` flag to specify which timestamp format to use in the diff --git a/content/shared/influxctl/release-notes.md b/content/shared/influxctl/release-notes.md index be098edf6a..aa808fbd49 100644 --- a/content/shared/influxctl/release-notes.md +++ b/content/shared/influxctl/release-notes.md @@ -5,52 +5,6 @@ - Add 'influxdata-archive-keyring' as a suggested package to simplify future repository key rotations for the end user - Add a new `--perf-debug` flag to the `query` command that outputs performance statistics and gRPC response trailers instead of query results -Example Output for `--perf-debug`: - -``` -$ ./influxctl query --perf-debug --format table --token REDACTED --database testdb --language influxql "SELECT SUM(i), non_negative_difference(SUM(i)) as diff_i FROM data WHERE time > '2025-11-07T01:20:00Z' AND time < '2025-11-07T03:00:00Z' AND runid = '540cd752bb6411f0a23e30894adea878' GROUP BY time(5m)" -+--------------------------+----------+ -| Metric | Value | -+--------------------------+----------+ -| Client Duration | 1.222 s | -| Output Rows | 20 | -| Output Size | 647 B | -+--------------------------+----------+ -| Compute Duration | 37.2 ms | -| Execution Duration | 243.8 ms | -| Ingester Latency Data | 0 | -| Ingester Latency Plan | 0 | -| Ingester Partition Count | 0 | -| Ingester Response | 0 B | -| Ingester Response Rows | 0 | -| Max Memory | 70 KiB | -| Parquet Files | 1 | -| Partitions | 1 | -| Planning Duration | 9.6 ms | -| Queue Duration | 286.6 µs | -+--------------------------+----------+ - -$ ./influxctl query --perf-debug --format json --token REDACTED --database testdb --language influxql "SELECT SUM(i), non_negative_difference(SUM(i)) as diff_i FROM data WHERE time > '2025-11-07T01:20:00Z' AND time < '2025-11-07T03:00:00Z' AND runid = '540cd752bb6411f0a23e30894adea878' GROUP BY time(5m)" -{ - "client_duration_secs": 1.101, - "compute_duration_secs": 0.037, - "execution_duration_secs": 0.247, - "ingester_latency_data": 0, - "ingester_latency_plan": 0, - "ingester_partition_count": 0, - "ingester_response_bytes": 0, - "ingester_response_rows": 0, - "max_memory_bytes": 71744, - "output_bytes": 647, - "output_rows": 20, - "parquet_files": 1, - "partitions": 1, - "planning_duration_secs": 0.009, - "queue_duration_secs": 0 -} -``` -``` - ### Dependency updates - Upgrade Go to 1.25.5. From cc8cd649b359bb66f5346141993e35220c687dbb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Dec 2025 18:19:08 +0000 Subject: [PATCH 3/3] docs: update placeholder syntax and add link to query command Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com> --- .../cloud-dedicated/reference/cli/influxctl/query.md | 8 ++------ .../influxdb3/clustered/reference/cli/influxctl/query.md | 8 ++------ content/shared/influxctl/release-notes.md | 2 +- 3 files changed, 5 insertions(+), 13 deletions(-) diff --git a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md index d65e5fcba0..4ad28043fa 100644 --- a/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md +++ b/content/influxdb3/cloud-dedicated/reference/cli/influxctl/query.md @@ -415,15 +415,13 @@ Use the `--perf-debug` flag to output performance statistics and gRPC response trailers instead of query results. This is useful for debugging query performance and understanding query execution. -{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} - {{< code-tabs-wrapper >}} {{% code-tabs %}} [Table format](#) [JSON format](#) {{% /code-tabs %}} {{% code-tab-content %}} -```sh +```sh { placeholders="DATABASE_TOKEN|DATABASE_NAME" } influxctl query \ --perf-debug \ --format table \ @@ -434,7 +432,7 @@ influxctl query \ ``` {{% /code-tab-content %}} {{% code-tab-content %}} -```sh +```sh { placeholders="DATABASE_TOKEN|DATABASE_NAME" } influxctl query \ --perf-debug \ --format json \ @@ -446,8 +444,6 @@ influxctl query \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -{{% /code-placeholders %}} - {{< expand-wrapper >}} {{% expand "View example table-formatted performance statistics" %}} ``` diff --git a/content/influxdb3/clustered/reference/cli/influxctl/query.md b/content/influxdb3/clustered/reference/cli/influxctl/query.md index e3ad09c50d..104d862c29 100644 --- a/content/influxdb3/clustered/reference/cli/influxctl/query.md +++ b/content/influxdb3/clustered/reference/cli/influxctl/query.md @@ -413,15 +413,13 @@ Use the `--perf-debug` flag to output performance statistics and gRPC response trailers instead of query results. This is useful for debugging query performance and understanding query execution. -{{% code-placeholders "DATABASE_(TOKEN|NAME)" %}} - {{< code-tabs-wrapper >}} {{% code-tabs %}} [Table format](#) [JSON format](#) {{% /code-tabs %}} {{% code-tab-content %}} -```sh +```sh { placeholders="DATABASE_TOKEN|DATABASE_NAME" } influxctl query \ --perf-debug \ --format table \ @@ -432,7 +430,7 @@ influxctl query \ ``` {{% /code-tab-content %}} {{% code-tab-content %}} -```sh +```sh { placeholders="DATABASE_TOKEN|DATABASE_NAME" } influxctl query \ --perf-debug \ --format json \ @@ -444,8 +442,6 @@ influxctl query \ {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} -{{% /code-placeholders %}} - {{< expand-wrapper >}} {{% expand "View example table-formatted performance statistics" %}} ``` diff --git a/content/shared/influxctl/release-notes.md b/content/shared/influxctl/release-notes.md index aa808fbd49..04ef7b2dfc 100644 --- a/content/shared/influxctl/release-notes.md +++ b/content/shared/influxctl/release-notes.md @@ -3,7 +3,7 @@ ### Features - Add 'influxdata-archive-keyring' as a suggested package to simplify future repository key rotations for the end user -- Add a new `--perf-debug` flag to the `query` command that outputs performance statistics and gRPC response trailers instead of query results +- Add a new `--perf-debug` flag to the [`query` command](/influxdb3/version/reference/cli/influxctl/query/) that outputs performance statistics and gRPC response trailers instead of query results ### Dependency updates