promtool: add dump-series by smallfish · Pull Request #13409 · prometheus/prometheus

smallfish · 2024-01-16T12:47:02Z

Modify promtool tsdb dump samples code for print series data (ignore samples)

example:

promtool tsdb dump --format seriesjson | jq -r '.xxx'
...

Does this PR introduce a user-facing change?

[FEATURE] Promtool tsdb dump: add `--format seriesjson` option to output just series labels in JSON format.

bboreham · 2024-08-13T11:18:36Z

Hello from the bug-scrub! Sorry your PR got no attention till now.

However I think the task got simpler -the dumpSamples function now takes a formatting function.
I think you can make a formatter which just prints the labels, i.e. based on these lines:

prometheus/cmd/promtool/tsdb.go

Lines 756 to 759 in 6f1fd4b

    
           func formatSeriesSet(ss storage.SeriesSet) error { 
        
           	for ss.Next() { 
        
           		series := ss.At() 
        
           		lbs := series.Labels()

smallfish · 2024-08-13T11:54:30Z

Thanks for reply :) the dump-series print series string and dedup the result (add a cache map)

bboreham · 2024-08-13T12:26:00Z

Yes I’m proposing you write a function which prints the string, right after the lines I quoted.
How can you get duplicate series?

smallfish · 2024-08-15T09:13:28Z

Hi @bboreham the PR has new commits, and doc and testcase updated too :)

cmd/promtool/tsdb.go

cmd/promtool/tsdb_test.go

docs/command-line/promtool.md

cmd/promtool/main.go

bboreham

Thanks for continuing to work on the PR.
I think it can be simplified.

Note also that several commits are missing 'DCO signoff', which we need to accept your contribution.

cmd/promtool/tsdb.go

cmd/promtool/main.go

machine424 · 2025-02-19T15:57:14Z

Just my 2 cents.

Note that if the json formatting isn't required, the series can also be fetched with sth like promtool tsdb dump | sed 's/} .*/}/' | sort -u

Maybe we can go further and add tsdb dump-json to dump samples in json (folks were asking for this in the past) and some scripting ~~like above~~ could be used to only get the series

smallfish · 2025-02-21T06:39:34Z

Just my 2 cents.

Note that if the json formatting isn't required, the series can also be fetched with sth like promtool tsdb dump | sed 's/} .*/}/' | sort -u

Maybe we can go further and add tsdb dump-json to dump samples in json (folks were asking for this in the past) and some scripting ~~like above~~ could be used to only get the series

Yes, JSON formatting is required (to facilitate subsequent filtering and selection using the jq tool, as well as for importing into DuckDB for SQL-based statistical sorting and analysis).

smallfish · 2025-02-21T06:44:38Z

Thanks for continuing to work on the PR. I think it can be simplified.

Note also that several commits are missing 'DCO signoff', which we need to accept your contribution.

Thank you for your response. I have resubmitted the content of this PR and included a signature.

dgl · 2025-02-24T01:21:40Z

Maybe we can go further and add tsdb dump-json

I don't really like the potential for the proliferation of dump-* options. I think we should do promtool tsdb dump --format=ndjson-labels (this should simplify the code too, as the options won't need to duplicated then).

It also leaves the door open to later have a ndjson or other option, which as @machine424 points out is a desire. (I think it makes sense to call this explicitly ndjson just incase one day it makes sense to output a whole JSON document, maybe based on an opentelemetry proto or similar.)

cmd/promtool/main.go

cmd/promtool/tsdb.go

krajorama · 2025-08-05T11:41:24Z

Hello from the bug scrub!

Seems like this comment by @dgl #13409 (comment) isn't addressed yet. Is this something you're coming back to @smallfish ? And there are some more comments as well.

Signed-off-by: smallfish <smallfish.xy@gmail.com>

Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

Add data files for series tests. Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

bboreham · 2025-11-10T18:29:56Z

I squashed the existing commits into one, then added more commits implementing the review suggestions.
@dgl I went with --format=seriesjson because I found ndjson too cryptic. I guess it meant "no data" ?

bwplotka

LGTM for a start, only one (non-blocking) question around dups.

cmd/promtool/tsdb.go

##### [\`v3.9.0\`](https://github.com/prometheus/prometheus/releases/tag/v3.9.0) #### Note for users of Native Histograms In version 3.9, Native Histograms is no longer experimental, and the feature flag `native-histogram` has no effect. You must now turn on the config setting `scrape_native_histograms` to collect Native Histogram samples from exporters. #### Changelog - \[CHANGE] Native Histograms are no longer experimental! Make the `native-histogram` feature flag a no-op. Use `scrape_native_histograms` config option instead. [#17528](prometheus/prometheus#17528) - \[CHANGE] API: Add maximum limit of 10,000 sets of statistics to TSDB status endpoint. [#17647](prometheus/prometheus#17647) - \[FEATURE] API: Add /api/v1/features for clients to understand which features are supported. [#17427](prometheus/prometheus#17427) - \[FEATURE] Promtool: Add `start_timestamp` field for unit tests. [#17636](prometheus/prometheus#17636) - \[FEATURE] Promtool: Add `--format seriesjson` option to `tsdb dump` to output just series labels in JSON format. [#13409](prometheus/prometheus#13409) - \[FEATURE] Add `--storage.tsdb.delay-compact-file.path` flag for better interoperability with Thanos. [#17435](prometheus/prometheus#17435) - \[FEATURE] UI: Add an option on the query drop-down menu to duplicate that query panel. [#17714](prometheus/prometheus#17714) - \[ENHANCEMENT]: TSDB: add flag `--storage.tsdb.block-reload-interval` to configure TSDB Block Reload Interval. [#16728](prometheus/prometheus#16728) - \[ENHANCEMENT] UI: Add graph option to start the chart's Y axis at zero. [#17565](prometheus/prometheus#17565) - \[ENHANCEMENT] Scraping: Classic protobuf format no longer requires the unit in the metric name. [#16834](prometheus/prometheus#16834) - \[ENHANCEMENT] PromQL, Rules, SD, Scraping: Add native histograms to complement existing summaries. [#17374](prometheus/prometheus#17374) - \[ENHANCEMENT] Notifications: Add a histogram `prometheus_notifications_latency_histogram_seconds` to complement the existing summary. [#16637](prometheus/prometheus#16637) - \[ENHANCEMENT] Remote-write: Add custom scope support for AzureAD authentication. [#17483](prometheus/prometheus#17483) - \[ENHANCEMENT] SD: add a `config` label with job name for most `prometheus_sd_refresh` metrics. [#17138](prometheus/prometheus#17138) - \[ENHANCEMENT] TSDB: New histogram `prometheus_tsdb_sample_ooo_delta`, the distribution of out-of-order samples in seconds. Collected for all samples, accepted or not. [#17477](prometheus/prometheus#17477) - \[ENHANCEMENT] Remote-read: Validate histograms received via remote-read. [#17561](prometheus/prometheus#17561) - \[PERF] TSDB: Small optimizations to postings index. [#17439](prometheus/prometheus#17439) - \[PERF] Scraping: Speed up relabelling of series. [#17530](prometheus/prometheus#17530) - \[PERF] PromQL: Small optimisations in binary operators. [#17524](prometheus/prometheus#17524), [#17519](prometheus/prometheus#17519). - \[BUGFIX] UI: PromQL autocomplete now shows the correct type and HELP text for OpenMetrics counters whose samples end in `_total`. [#17682](prometheus/prometheus#17682) - \[BUGFIX] UI: Fixed codemirror-promql incorrectly showing label completion suggestions after the closing curly brace of a vector selector. [#17602](prometheus/prometheus#17602) - \[BUGFIX] UI: Query editor no longer suggests a duration unit if one is already present after a number. [#17605](prometheus/prometheus#17605) - \[BUGFIX] PromQL: Fix some "vector cannot contain metrics with the same labelset" errors when experimental delayed name removal is enabled. [#17678](prometheus/prometheus#17678) - \[BUGFIX] PromQL: Fix possible corruption of PromQL text if the query had an empty `ignoring()` and non-empty grouping. [#17643](prometheus/prometheus#17643) - \[BUGFIX] PromQL: Fix resets/changes to return empty results for anchored selectors when all samples are outside the range. [#17479](prometheus/prometheus#17479) - \[BUGFIX] PromQL: Check more consistently for many-to-one matching in filter binary operators. [#17668](prometheus/prometheus#17668) - \[BUGFIX] PromQL: Fix collision in unary negation with non-overlapping series. [#17708](prometheus/prometheus#17708) - \[BUGFIX] PromQL: Fix collision in label\_join and label\_replace with non-overlapping series. [#17703](prometheus/prometheus#17703) - \[BUGFIX] PromQL: Fix bug with inconsistent results for queries with OR expression when experimental delayed name removal is enabled. [#17161](prometheus/prometheus#17161) - \[BUGFIX] PromQL: Ensure that `rate`/`increase`/`delta` of histograms results in a gauge histogram. [#17608](prometheus/prometheus#17608) - \[BUGFIX] PromQL: Do not panic while iterating over invalid histograms. [#17559](prometheus/prometheus#17559) - \[BUGFIX] TSDB: Reject chunk files whose encoded chunk length overflows int. [#17533](prometheus/prometheus#17533) - \[BUGFIX] TSDB: Do not panic during resolution reduction of invalid histograms. [#17561](prometheus/prometheus#17561) - \[BUGFIX] Remote-write Receive: Avoid duplicate labels when experimental type-and-unit-label feature is enabled. [#17546](prometheus/prometheus#17546) - \[BUGFIX] OTLP Receiver: Only write metadata to disk when experimental metadata-wal-records feature is enabled. [#17472](prometheus/prometheus#17472)

##### [\`v3.9.1\`](https://github.com/prometheus/prometheus/releases/tag/v3.9.1) - \[BUGFIX] Agent: fix crash shortly after startup from invalid type of object. [#17802](prometheus/prometheus#17802) - \[BUGFIX] Scraping: fix relabel keep/drop not working. [#17807](prometheus/prometheus#17807) --- ##### [\`v3.9.0\`](https://github.com/prometheus/prometheus/releases/tag/v3.9.0) #### Note for users of Native Histograms In version 3.9, Native Histograms is no longer experimental, and the feature flag `native-histogram` has no effect. You must now turn on the config setting `scrape_native_histograms` to collect Native Histogram samples from exporters. #### Changelog - \[CHANGE] Native Histograms are no longer experimental! Make the `native-histogram` feature flag a no-op. Use `scrape_native_histograms` config option instead. [#17528](prometheus/prometheus#17528) - \[CHANGE] API: Add maximum limit of 10,000 sets of statistics to TSDB status endpoint. [#17647](prometheus/prometheus#17647) - \[FEATURE] API: Add /api/v1/features for clients to understand which features are supported. [#17427](prometheus/prometheus#17427) - \[FEATURE] Promtool: Add `start_timestamp` field for unit tests. [#17636](prometheus/prometheus#17636) - \[FEATURE] Promtool: Add `--format seriesjson` option to `tsdb dump` to output just series labels in JSON format. [#13409](prometheus/prometheus#13409) - \[FEATURE] Add `--storage.tsdb.delay-compact-file.path` flag for better interoperability with Thanos. [#17435](prometheus/prometheus#17435) - \[FEATURE] UI: Add an option on the query drop-down menu to duplicate that query panel. [#17714](prometheus/prometheus#17714) - \[ENHANCEMENT]: TSDB: add flag `--storage.tsdb.block-reload-interval` to configure TSDB Block Reload Interval. [#16728](prometheus/prometheus#16728) - \[ENHANCEMENT] UI: Add graph option to start the chart's Y axis at zero. [#17565](prometheus/prometheus#17565) - \[ENHANCEMENT] Scraping: Classic protobuf format no longer requires the unit in the metric name. [#16834](prometheus/prometheus#16834) - \[ENHANCEMENT] PromQL, Rules, SD, Scraping: Add native histograms to complement existing summaries. [#17374](prometheus/prometheus#17374) - \[ENHANCEMENT] Notifications: Add a histogram `prometheus_notifications_latency_histogram_seconds` to complement the existing summary. [#16637](prometheus/prometheus#16637) - \[ENHANCEMENT] Remote-write: Add custom scope support for AzureAD authentication. [#17483](prometheus/prometheus#17483) - \[ENHANCEMENT] SD: add a `config` label with job name for most `prometheus_sd_refresh` metrics. [#17138](prometheus/prometheus#17138) - \[ENHANCEMENT] TSDB: New histogram `prometheus_tsdb_sample_ooo_delta`, the distribution of out-of-order samples in seconds. Collected for all samples, accepted or not. [#17477](prometheus/prometheus#17477) - \[ENHANCEMENT] Remote-read: Validate histograms received via remote-read. [#17561](prometheus/prometheus#17561) - \[PERF] TSDB: Small optimizations to postings index. [#17439](prometheus/prometheus#17439) - \[PERF] Scraping: Speed up relabelling of series. [#17530](prometheus/prometheus#17530) - \[PERF] PromQL: Small optimisations in binary operators. [#17524](prometheus/prometheus#17524), [#17519](prometheus/prometheus#17519). - \[BUGFIX] UI: PromQL autocomplete now shows the correct type and HELP text for OpenMetrics counters whose samples end in `_total`. [#17682](prometheus/prometheus#17682) - \[BUGFIX] UI: Fixed codemirror-promql incorrectly showing label completion suggestions after the closing curly brace of a vector selector. [#17602](prometheus/prometheus#17602) - \[BUGFIX] UI: Query editor no longer suggests a duration unit if one is already present after a number. [#17605](prometheus/prometheus#17605) - \[BUGFIX] PromQL: Fix some "vector cannot contain metrics with the same labelset" errors when experimental delayed name removal is enabled. [#17678](prometheus/prometheus#17678) - \[BUGFIX] PromQL: Fix possible corruption of PromQL text if the query had an empty `ignoring()` and non-empty grouping. [#17643](prometheus/prometheus#17643) - \[BUGFIX] PromQL: Fix resets/changes to return empty results for anchored selectors when all samples are outside the range. [#17479](prometheus/prometheus#17479) - \[BUGFIX] PromQL: Check more consistently for many-to-one matching in filter binary operators. [#17668](prometheus/prometheus#17668) - \[BUGFIX] PromQL: Fix collision in unary negation with non-overlapping series. [#17708](prometheus/prometheus#17708) - \[BUGFIX] PromQL: Fix collision in label\_join and label\_replace with non-overlapping series. [#17703](prometheus/prometheus#17703) - \[BUGFIX] PromQL: Fix bug with inconsistent results for queries with OR expression when experimental delayed name removal is enabled. [#17161](prometheus/prometheus#17161) - \[BUGFIX] PromQL: Ensure that `rate`/`increase`/`delta` of histograms results in a gauge histogram. [#17608](prometheus/prometheus#17608) - \[BUGFIX] PromQL: Do not panic while iterating over invalid histograms. [#17559](prometheus/prometheus#17559) - \[BUGFIX] TSDB: Reject chunk files whose encoded chunk length overflows int. [#17533](prometheus/prometheus#17533) - \[BUGFIX] TSDB: Do not panic during resolution reduction of invalid histograms. [#17561](prometheus/prometheus#17561) - \[BUGFIX] Remote-write Receive: Avoid duplicate labels when experimental type-and-unit-label feature is enabled. [#17546](prometheus/prometheus#17546) - \[BUGFIX] OTLP Receiver: Only write metadata to disk when experimental metadata-wal-records feature is enabled. [#17472](prometheus/prometheus#17472)

smallfish requested a review from dgl as a code owner January 16, 2024 12:47

smallfish force-pushed the feature/promtool-dump-series branch from 48346bc to e48f29d Compare August 15, 2024 08:48

smallfish force-pushed the feature/promtool-dump-series branch 8 times, most recently from de69a6a to 8b9f0d1 Compare August 15, 2024 15:18

bboreham reviewed Aug 19, 2024

View reviewed changes

smallfish force-pushed the feature/promtool-dump-series branch from 2868e59 to f67d482 Compare August 20, 2024 12:17

bboreham self-assigned this Feb 18, 2025

bboreham reviewed Feb 19, 2025

View reviewed changes

cmd/promtool/tsdb.go Outdated Show resolved Hide resolved

cmd/promtool/main.go Outdated Show resolved Hide resolved

smallfish force-pushed the feature/promtool-dump-series branch 4 times, most recently from e17cef2 to b71e092 Compare February 21, 2025 06:21

dgl reviewed Feb 24, 2025

View reviewed changes

cmd/promtool/main.go Outdated Show resolved Hide resolved

cmd/promtool/main.go Outdated Show resolved Hide resolved

cmd/promtool/tsdb.go Outdated Show resolved Hide resolved

smallfish force-pushed the feature/promtool-dump-series branch from b71e092 to d59c86d Compare February 24, 2025 02:03

promtool: add dump-series

5560397

Signed-off-by: smallfish <smallfish.xy@gmail.com>

Make dump-series a --format flag on the dump command

beea578

Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

bboreham force-pushed the feature/promtool-dump-series branch from d59c86d to e7765c5 Compare November 10, 2025 18:14

bboreham added 2 commits November 10, 2025 18:18

[TEST] Promtool: test dump series together with dump samples

89b92f7

Add data files for series tests. Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

Small refactor: use clearer name formatSeriesSetLabelsToJSON

11cf858

Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

bboreham force-pushed the feature/promtool-dump-series branch from e7765c5 to 11cf858 Compare November 10, 2025 18:18

lint

e177429

Signed-off-by: Bryan Boreham <bjboreham@gmail.com>

bboreham removed their assignment Nov 10, 2025

bwplotka approved these changes Dec 9, 2025

View reviewed changes

cmd/promtool/tsdb.go Show resolved Hide resolved

bboreham merged commit 6f18cc3 into prometheus:main Dec 16, 2025
28 checks passed

Conversation

smallfish commented Jan 16, 2024 • edited by bboreham Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Does this PR introduce a user-facing change?

Uh oh!

bboreham commented Aug 13, 2024

Uh oh!

smallfish commented Aug 13, 2024

Uh oh!

bboreham commented Aug 13, 2024

Uh oh!

smallfish commented Aug 15, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bboreham left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

machine424 commented Feb 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smallfish commented Feb 21, 2025

Uh oh!

smallfish commented Feb 21, 2025

Uh oh!

dgl commented Feb 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

krajorama commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bboreham commented Nov 10, 2025

Uh oh!

bwplotka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

smallfish commented Jan 16, 2024 •

edited by bboreham

Loading

machine424 commented Feb 19, 2025 •

edited

Loading

krajorama commented Aug 5, 2025 •

edited

Loading