Add basic initial developer docs for TSDB (#9451)
* Add basic initial developer docs for TSDB There's a decent amount of content already out there (blog posts, conference talks, etc), but: * when they get stale, they don't tend to get updated * they still leave me with questions that I'ld like to answer for developers (like me) who want to use, or work with, TSDB What I propose is developer docs inside the prometheus repository. Easy to find and harness the power of the community to expand it and keep it up to date. * perfect is the enemy of good. Let's have a base and incrementally improve * Markdown docs should be broad but not too deep. Source code comments can complement them, and are the ideal place for implementation details. Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * use example code that works out of the box Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * Apply suggestions from code review Co-authored-by: Ganesh Vernekar <15064823+codesome@users.noreply.github.com> Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * PR feedback Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * more docs Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * PR feedback Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * Apply suggestions from code review Signed-off-by: Dieter Plaetinck <dieter@grafana.com> Co-authored-by: Bartlomiej Plotka <bwplotka@gmail.com> * Apply suggestions from code review Signed-off-by: Dieter Plaetinck <dieter@grafana.com> Co-authored-by: Ganesh Vernekar <15064823+codesome@users.noreply.github.com> * feedback Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * Update tsdb/docs/usage.md Signed-off-by: Dieter Plaetinck <dieter@grafana.com> Co-authored-by: Ganesh Vernekar <15064823+codesome@users.noreply.github.com> * final tweaks Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * workaround docs versioning issue Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * Move example code to real executable, testable example. Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * cleanup example test and make sure it always reproduces Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * obtain temp dir in a way that works with older Go versions Signed-off-by: Dieter Plaetinck <dieter@grafana.com> * Fix Ganesh's comments Signed-off-by: Ganesh Vernekar <ganeshvern@gmail.com> Co-authored-by: Ganesh Vernekar <15064823+codesome@users.noreply.github.com> Co-authored-by: Bartlomiej Plotka <bwplotka@gmail.com> Co-authored-by: Ganesh Vernekar <ganeshvern@gmail.com>pull/9781/head
Dieter Plaetinck
4 years ago
committed by
GitHub
parent
49d8f02c1f
commit
0fac9bb859
@ -0,0 +1,71 @@ |
|||||||
|
# Usage |
||||||
|
|
||||||
|
TSDB can be - and is - used by other applications such as [Cortex](https://cortexmetrics.io/) and [Thanos](https://thanos.io/). |
||||||
|
This directory contains documentation for any developers who wish to work on or with TSDB. |
||||||
|
|
||||||
|
For a full example of instantiating a database, adding and querying data, see the [tsdb example in the docs](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb). |
||||||
|
`tsdb/db_test.go` also demonstrates various specific usages of the TSDB library. |
||||||
|
|
||||||
|
## Instantiating a database |
||||||
|
|
||||||
|
Callers should use [`tsdb.Open`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#Open) to open a TSDB |
||||||
|
(the directory may be new or pre-existing). |
||||||
|
This returns a [`*tsdb.DB`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#DB) which is the actual database. |
||||||
|
|
||||||
|
A `DB` has the following main components: |
||||||
|
|
||||||
|
* Compactor: a [leveled compactor](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#LeveledCompactor). Note: it is currently the only compactor implementation. It runs automatically. |
||||||
|
* [`Head`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#DB.Head) |
||||||
|
* [Blocks (persistent blocks)](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#DB.Blocks) |
||||||
|
|
||||||
|
The `Head` is responsible for a lot. Here are its main components: |
||||||
|
|
||||||
|
* [WAL](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb/wal#WAL) (Write Ahead Log). |
||||||
|
* [`stripeSeries`](https://github.com/prometheus/prometheus/blob/411021ada9ab41095923b8d2df9365b632fd40c3/tsdb/head.go#L1292): |
||||||
|
this holds all the active series by linking to [`memSeries`](https://github.com/prometheus/prometheus/blob/411021ada9ab41095923b8d2df9365b632fd40c3/tsdb/head.go#L1462) |
||||||
|
by an ID (aka "ref") and by labels hash. |
||||||
|
* Postings list (reverse index): For any label-value pair, holds all the corresponding series refs. Used for queries. |
||||||
|
* Tombstones. |
||||||
|
|
||||||
|
## Adding data |
||||||
|
|
||||||
|
Use [`db.Appender()`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#DB.Appender) to obtain an "appender". |
||||||
|
The [golang docs](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/storage#Appender) speak mostly for themselves. |
||||||
|
|
||||||
|
Remember: |
||||||
|
|
||||||
|
* Use `Commit()` to add the samples to the DB and update the WAL. |
||||||
|
* Create a new appender each time you commit. |
||||||
|
* Appenders are not concurrency safe, but scrapes run concurrently and as such, leverage multiple appenders concurrently. |
||||||
|
This reduces contention, although Commit() contend the same critical section (writing to the WAL is serialized), and may |
||||||
|
inflate append tail latency if multiple appenders try to commit at the same time. |
||||||
|
|
||||||
|
Append may reject data due to these conditions: |
||||||
|
|
||||||
|
1) `timestamp < minValidTime` where `minValidTime` is the highest of: |
||||||
|
* the maxTime of the last block (i.e. the last truncation time of Head) - updated via [`Head.Truncate()`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#Head.Truncate) and [`DB.compactHead()`](https://github.com/prometheus/prometheus/blob/411021ada9ab41095923b8d2df9365b632fd40c3/tsdb/db.go#L968) |
||||||
|
* `tsdb.min-block-duration/2` older than the max time in the Head block. Note that while technically `storage.tsdb.min-block-duration` is configurable, it's a hidden option and changing it is discouraged. So We can assume this value to be 2h. |
||||||
|
|
||||||
|
Breaching this condition results in "out of bounds" errors. |
||||||
|
The first condition assures the block that will be generated doesn't overlap with the previous one (which simplifies querying) |
||||||
|
The second condition assures the sample won't go into the so called "compaction window", that is the section of the data that might be in process of being saved into a persistent block on disk. (because that logic runs concurrently with ingestion without a lock) |
||||||
|
2) The labels don't validate. (if the set is empty or contains duplicate label names) |
||||||
|
3) If the sample, for the respective series (based on all the labels) is out of order or has a different value for the last (highest) timestamp seen. (results in `storage.ErrOutOfOrderSample` and `storage.ErrDuplicateSampleForTimestamp` respectively) |
||||||
|
|
||||||
|
`Commit()` may also refuse data that is out of order with respect to samples that were added via a different appender. |
||||||
|
|
||||||
|
## Querying data |
||||||
|
|
||||||
|
Use [`db.Querier()`](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/tsdb#DB.Querier) to obtain a "querier". |
||||||
|
The [golang docs](https://pkg.go.dev/github.com/prometheus/prometheus@v1.8.2-0.20211105201321-411021ada9ab/storage#Querier) speak mostly for themselves. |
||||||
|
|
||||||
|
Remember: |
||||||
|
|
||||||
|
* A querier can only see data that was committed when it was created. This limits the lifetime of a querier. |
||||||
|
* A querier should be closed when you're done with it. |
||||||
|
* Use mint/maxt to avoid loading unneeded data. |
||||||
|
|
||||||
|
|
||||||
|
## Example code |
||||||
|
|
||||||
|
Find the example code for ingesting samples and querying them in [`tsdb/example_test.go`](../example_test.go) |
||||||
@ -0,0 +1,112 @@ |
|||||||
|
// Copyright 2021 The Prometheus Authors
|
||||||
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
// you may not use this file except in compliance with the License.
|
||||||
|
// You may obtain a copy of the License at
|
||||||
|
//
|
||||||
|
// http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
//
|
||||||
|
// Unless required by applicable law or agreed to in writing, software
|
||||||
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
// See the License for the specific language governing permissions and
|
||||||
|
// limitations under the License.
|
||||||
|
|
||||||
|
package tsdb |
||||||
|
|
||||||
|
import ( |
||||||
|
"context" |
||||||
|
"fmt" |
||||||
|
"math" |
||||||
|
"testing" |
||||||
|
"time" |
||||||
|
|
||||||
|
"github.com/stretchr/testify/require" |
||||||
|
|
||||||
|
"github.com/prometheus/prometheus/model/labels" |
||||||
|
) |
||||||
|
|
||||||
|
func TestExample(t *testing.T) { |
||||||
|
// Create a random dir to work in. Open() doesn't require a pre-existing dir, but
|
||||||
|
// we want to make sure not to make a mess where we shouldn't.
|
||||||
|
dir := t.TempDir() |
||||||
|
|
||||||
|
// Open a TSDB for reading and/or writing.
|
||||||
|
db, err := Open(dir, nil, nil, DefaultOptions(), nil) |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
// Open an appender for writing.
|
||||||
|
app := db.Appender(context.Background()) |
||||||
|
|
||||||
|
lbls := labels.FromStrings("foo", "bar") |
||||||
|
var appendedSamples []sample |
||||||
|
|
||||||
|
// Ref is 0 for the first append since we don't know the reference for the series.
|
||||||
|
ts, v := time.Now().Unix(), 123.0 |
||||||
|
ref, err := app.Append(0, lbls, ts, v) |
||||||
|
require.NoError(t, err) |
||||||
|
appendedSamples = append(appendedSamples, sample{ts, v}) |
||||||
|
|
||||||
|
// Another append for a second later.
|
||||||
|
// Re-using the ref from above since it's the same series, makes append faster.
|
||||||
|
time.Sleep(time.Second) |
||||||
|
ts, v = time.Now().Unix(), 124 |
||||||
|
_, err = app.Append(ref, lbls, ts, v) |
||||||
|
require.NoError(t, err) |
||||||
|
appendedSamples = append(appendedSamples, sample{ts, v}) |
||||||
|
|
||||||
|
// Commit to storage.
|
||||||
|
err = app.Commit() |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
// In case you want to do more appends after app.Commit(),
|
||||||
|
// you need a new appender.
|
||||||
|
// app = db.Appender(context.Background())
|
||||||
|
//
|
||||||
|
// ... adding more samples.
|
||||||
|
//
|
||||||
|
// Commit to storage.
|
||||||
|
// err = app.Commit()
|
||||||
|
// require.NoError(t, err)
|
||||||
|
|
||||||
|
// Open a querier for reading.
|
||||||
|
querier, err := db.Querier(context.Background(), math.MinInt64, math.MaxInt64) |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
ss := querier.Select(false, nil, labels.MustNewMatcher(labels.MatchEqual, "foo", "bar")) |
||||||
|
var queriedSamples []sample |
||||||
|
for ss.Next() { |
||||||
|
series := ss.At() |
||||||
|
fmt.Println("series:", series.Labels().String()) |
||||||
|
|
||||||
|
it := series.Iterator() |
||||||
|
for it.Next() { |
||||||
|
ts, v := it.At() |
||||||
|
fmt.Println("sample", ts, v) |
||||||
|
queriedSamples = append(queriedSamples, sample{ts, v}) |
||||||
|
} |
||||||
|
|
||||||
|
require.NoError(t, it.Err()) |
||||||
|
fmt.Println("it.Err():", it.Err()) |
||||||
|
} |
||||||
|
require.NoError(t, ss.Err()) |
||||||
|
fmt.Println("ss.Err():", ss.Err()) |
||||||
|
ws := ss.Warnings() |
||||||
|
if len(ws) > 0 { |
||||||
|
fmt.Println("warnings:", ws) |
||||||
|
} |
||||||
|
err = querier.Close() |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
// Clean up any last resources when done.
|
||||||
|
err = db.Close() |
||||||
|
require.NoError(t, err) |
||||||
|
|
||||||
|
require.Equal(t, appendedSamples, queriedSamples) |
||||||
|
|
||||||
|
// Output:
|
||||||
|
// series: {foo="bar"}
|
||||||
|
// sample <ts1> 123
|
||||||
|
// sample <ts2> 124
|
||||||
|
// it.Err(): <nil>
|
||||||
|
// ss.Err(): <nil>
|
||||||
|
} |
||||||
Loading…
Reference in new issue