Over a million developers have joined DZone.

InfluxDB Internals 101 (Part 1)

DZone's Guide to

InfluxDB Internals 101 (Part 1)

The goal of this series is to present a consolidated overview of the InfluxDB architecture. Part 1 explains how InfluxDB receives and persists incoming writes.

· Database Zone ·
Free Resource

Read why times series is the fastest growing database category.

Paul Dix led a series of internal InfluxDB 101 sessions to teach newcomers InfluxDB internals. I learned a lot from the talks and want to share the content with the community. I'm also writing this to organize my own understanding of InfluxDB and to perhaps help others who want to learn how InfluxDB is architected. A lot of this information is gathered from InfluxDB documentation, as well — the goal of this series is to present a consolidated overview of the InfluxDB architecture.

There's a lot to digest so it's presented in three parts. This first post explains the data model and the write path. Post two explains the query path. Post three explains InfluxEnterprise clustering.

Data Model and Write Path: Adding Data to InfluxDB

Learn about data models and terminology, receiving points from clients, persisting points to storage, and compacting TSM data.

Data Model and Terminology

The serialization format for points is defined by the [line protocol] (which includes additional examples and explanations if you'd like to read more detail). An example point from the specification helps to explain the terminology:

" temperature,machine=unit42,type=assembly internal=32,external=100 1434055562000000035

The measurement is temperature.

The tagset is machine=unit42,type=assembly. The keys, machine and type, in the tagset are called tag keys. The values, unit42 and assembly, in the tagset are called tag values.

The fieldset is internal=32,external=100. The keys, internal and external, in the fieldset are called field keys. The values, 32 and 100, in the fieldset are called field values.

We'll explain replication factor, shard groups, and shards later when we describe how the write path works in InfluxDB.

There's one additional term that we need to get started: series. A series is simply a shortcut for saying retention policy + measurement + tagset.. All points with the same retention policy, measurement, and tagset are members of the same series.

You can refer to the documentation glossary for these terms or others that might be used in this blog post series.

Receiving Points From Clients

Clients POST points (inline protocol format) to InfluxDB's HTTP /write endpoint. Points can be sent individually; however, for efficiency, most applications send points in batches. A typical batch ranges in size from hundreds to thousands of points. The POST specifies a database and an optional retention policy via query parameters. If the retention policy is not specified, the default retention policy is used. All points in the body will be written to that database and retention policy. Points in a POST body can be from an arbitrary number of series; points in a batch do not have to be from the same measurement or tagset.

When the database receives new points, it must make those points durable so that they can be recovered in case of a database or server crash and make the points queryable. This post focuses on the first half, making points durable.

Persisting Points to Storage

To make points durable, each batch is written and fsynced to a write ahead log ( WAL). The WAL is an append-only file that is only read during a database recovery. For space and disk IO efficiency, each batch in the WAL is compressed using Snappy compression before being written to disk.

The combination of WAL and cache works well for incoming data but is insufficient for long-term storage. Since the WAL must be replayed on startup, it is important to constrain it to a reasonable size. The cache is limited to the size of RAM, which is also undesirable for many time series use cases. Consequently, data needs to be organized and written to long-term storage blocks on disk that are size-efficient (so that the database can store a lot of points) and efficient for querying.

Time series queries are frequently aggregations over time-scans of points within a bounded time range that are then reduced by a summary function like mean, max, or moving windows. Columnar database storage techniques, where data is organized on disk by column and not by row, fit this query pattern nicely. Additionally, columnar systems compress data exceptionally well, satisfying the need to store data efficiently. There is a lot of literature on column stores. Columnar-Oriented Database Systems is one such overview.

Time series applications often evict data from storage after a period of time. Many monitoring applications, for example, will store the last month or two of data online to support monitoring queries. It needs to be efficient to remove data from the database if a configured time-to-live expires. Deleting points from columnar storage is expensive, so InfluxDB additionally organizes its columnar format into time-bounded chunks. When the time-to-live expires, the time-bounded file can simply be deleted from the filesystem rather than requiring a large update to persisted data.

Finally, when InfluxDB is run as a clustered system, it replicates data across multiple servers for availability and durability in case of failures.

The optional time-to-live duration, the granularity of time blocks within the time-to-live period, and the number of replicas are configured using an InfluxDB retention policy:

CREATE RETENTION POLICY <retention_policy_name> ON <database_name> DURATION <duration> REPLICATION <n> [SHARD DURATION <duration>] [DEFAULT]

The duration is the optional time to live (if data should not expire, set duration to INF). SHARD DURATION is the granularity of data within the expiration period. For example, a one- hour shard duration with a 24 hour duration configures the database to store 24 one-hour shards. Each hour, the oldest shard is expired (removed) from the database. Set REPLICATION to configure the replication factor-how many copies of a shard should exist within a cluster.

Concretely, the database creates this physical organization of data on disk:

'' Database director  /db
    '' Retention Policy directory /db/rp
        '' Shard Group (time bounded). (Logical)
            '' Shard directory (db/rp/Id#)
                '' TSM0001.tsm (data file)
                '' TSM0002.tsm (data file)
                '' …

The in-memory cache is flushed to disk in the TSM format. When the flush completes, flushed points are removed from the cache and the corresponding WAL is truncated. (The WAL and cache are also maintained per-shard.) The TSM data files store the columnar-organized points. Once written, a TSM file is immutable. A detailed description of the TSM file layout is available in the InfluxDB documentation.

Compacting TSM Data

The cache is a relatively small amount of data. The TSM columnar format works best when it can store long runs of values for a series in a single block. A longer run produces both better compression and reduces seeks to scan a field for query. The TSM format is based heavily on log-structured merge-trees. New (level one) TSM files are generated by cache flushes. These files are later combined (compacted) into level two files. Level two files are further combined into level three files. Additional levels of compaction occur as the files become larger and eventually become cold (the time range they cover is no longer hot for writes.) The documentation reference above offers a detailed description of compaction.

There's a lot of logic and sophistication in the TSM compaction code. However, the high-level goal is quite simple: organize values for a series together into long runs to best optimize compression and scanning queries.

Concluding Part One

In summary, batches of points are POSTed to InfluxDB. Those batches are Snappy-compressed and are written to a WAL for immediate durability. The points are also written to an in-memory cache so that newly written points are immediately queryable. The cache is periodically flushed to TSM files. As TSM files accumulate, they are combined and compacted into higher-level TSM files. TSM data is organized into shards. The time range covered by a shard and the replication factor of a shard in a clustered deployment are configured by the retention policy.

Hopefully, this post helps to explain how InfluxDB receives and persists incoming writes. In the next post, we'll discuss how the system supports query, update, and delete operations.

Learn how to get 20x more performance than Elastic by moving to a Time Series database.

influxdb ,database ,database internals ,write path ,persistence ,tutorial

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}