プロジェクト

全般

プロフィール

Wiki » Linux »

InfluxDB

概要

InfluxDBは、NoSQLの時系列データベースに分類されるデータベースです。

TSM (Time Structured Merge Tree) と呼ぶ列指向のストレージエンジンに、タイムスタンプ、タグおよびフィールド値から構成されるPointデータを高速に読み書きします。Pointデータのフィールド値は、timestamp、float、integer、boolean型であれば列指向により差分符号化、string型についてはSnappy圧縮を使い、ストレージの使用量を低減します。
データの格納は、シャードと呼ぶある一定の時間範囲のデータを特定のファイルに格納します。

この仕組みから、ある時刻範囲のデータを取り出すのが非常に得意です。

古いデータを時刻に基づき自動で削除できるRetention Policyを搭載しており、永続保存か、期限付き保存かを Measurementごとに指定できます。

データベースへの問い合わせは、Fluxと呼ぶ関数指向の問い合わせ言語が用意されています。

トランザクションのACIDは一部を満たしていません。

インストールと初期設定

インストール

macOS

初期設定

T.B.D.

操作

インタフェース

Web UI

デフォルトで、8086ポートにWebブラウザでアクセスすると、InfluxDBの管理アプリケーションのWeb画面を利用できます。
InfluxDBインストール後の初回アクセス時は、[GET STARTED]ボタンのみ表示され、初期設定を実施します。
設定終了後にアクセスすると、ログイン画面となります。

データの検索・表示は、Data Explorer を使います。
データの登録は、Load Data（左側[↑]アイコンから Sources、File Upload で、CSVファイルまたはLine Protocolファイル）

コマンドライン

influxコマンドで操作を行います。
書式： influx [command]

接続先のInfluxDBの指定、使用するOrganization、認証するためのTokenを指定します。

~ % influx bucket list \
 --host http://localhost:8086 \
 --org myorg \
 --token VxbEWU-7RILekvTsFegpInGpEozHeoGGP2KFj16E9GkXI7f0tTIue3AR6iKZm51NwWrGZAbZQbjtdtNhAzov6w==
  • --hostで接続先を指定、同じマシン上で実行しているInfluxDBに接続（省略可能、省略した場合、ローカルマシンの8086ポートが使用される）
  • アクセスのためのTokenは、権限を指定して生成しておきます。簡単に生成・削除できるので、必要に応じて作ります。
    （上述はドキュメント用に生成したtokenで、生成後、破棄済みです）

コマンドラインで毎回指定する他、環境変数に定義する方法もあります。INFLUX_HOSTは省略時ローカルマシンの8086ポートが使用。

  • INFLUX_HOST, INFLUX_ORG, INFLUX_TOKEN
    export INFLUX_ORG=myorg
export INFLUX_TOKEN=VxbEWU-7RILekvTsFegpInGpEozHeoGGP2KFj16E9GkXI7f0tTIue3AR6iKZm51NwWrGZAbZQbjtdtNhAzov6w==
authコマンド

authコマンドには、さらに create, delete, list, active, inactive コマンドがあります。

tokenを確認するには、influx auth ls を実行します。

backupコマンド
$ influx backup ./backup_influxdb_20241014 -t <APIキー>
  • -t オプションで管理用Tokenを指定する
    特定のORGのTokenではバックアップできなかった
bucketコマンド

bucketコマンドには、さらに create, delete, list, update コマンドがあります。

deleteコマンド

Pointデータ群を削除します。バケットと削除対象の開始・終了日時を指定します。また、タグで絞り込みも可能です。

$ influx delete --bucket weather \
  --start '2024-03-03T07:05:03.000Z' --stop '2024-05-05T-07:05:03.000Z' \
  --predicate '_measurement="stevenson_screen"'

exportコマンド
orgコマンド

orgコマンドには、さらに create, delete, list, members, update コマンドがあります。

queryコマンド

fluxクエリを実行します。

restoreコマンド

既存のbucketがあると、backupデータのrestoreができないので、restore先を新しいbucketとするか、既存のbucketを削除して実行します。

$ influx restore ./backup_influxdb_20241014 --bucket weather -t <token>
writeコマンド

PointデータをLine protocol形式で指定してデータベースに書き込みます。
直接テキストで指定した Pointデータを書き込むほか、ファイルに記載された Pointデータを書き込むことができます。

$ influx write --bucket weather --precision s " 
stevenson_screen,rank=second temperature=31.83 172410000
"
  • tagキーとfieldキーの間は、カンマではなく空白
  • --precision sオプションは、タイムスタンプを秒単位で指定となる（UNIX time）

influxd inspect コマンド

InfluxDBのディスク上に格納された時系列データに対する検査を実施するコマンドです。
書式： influxd inspect [sub command]

export-lp

ディスク上に格納された時系列データを、ラインプロトコル形式のファイルへ出力します。

$ influxd inspect export-lp \
    --bucket-id $BUCKET_ID \
    --engine-path /var/lib/influxdb/engine \
    --start '2024-10-20T00:00:00Z' \
    --end '2024-10-20T03:00:00Z' \
    --measurement wheather \
    --output-path ./wheather_export.lp

REST API

InfluxDBへの問い合わせには、REST APIが使えます。

権限一覧を表示

http://localhost:8086/api/v2/authorizations

データ

データの階層

Bucket
  +-- Measurement
        +-- Point data

RDBMSのdatabaseに相当するものがBucketです。
RDBMSのtableに相当するものがMeasurementです。
RDBMSのrowに相当するものが Point です。
RDBMSのcolumnに相当するものが、Time, Tag, Field です。
Timeは、1つだけ必須で存在するPointのタイムスタンプ情報です。（主キーのようなもの）
Tagは、文字列のKey-valueペアから成り、複数定義可能で、インデックスで検索時に条件指定に使うことができます。時刻とともに変化する時系列データ自体ではなく、データの属性として、例えばセンサーID、位置、種別などをデータに与えます。
Fieldは、文字列のKeyと、ある型のvalueペアから成り、時系列で変化する実際の値を持ち、複数定義可能です。

データの構成

InfluxDBでは、Pointデータが1件の基本的なデータ構成となります。
Pointデータは、Measurement、tagセット、fieldセットとタイムスタンプから構成されます。
Pointデータの正規化された表現形式をLine Protocolと呼びます。

my measurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
-------------- ------------------- --------------------- -------------------
Measurement     tag set             field set              timestamp

Pointデータは、指定したmeasurementに timestampとともに格納されます。時系列データベースなので、timestampが特別扱いされます。
field setは、1つ以上のfieldの名前と値の組み合わせで構成されます。
tag setは、0個以上のkey-valueのデータの組み合わせで、主に条件付きでデータを検索する際に使用されます。
timestampは、UNIX timeのナノ秒表現です。登録データのLine protocolでは、timestampを省略した場合、登録時のサーバー時刻が適用されます。

CSVデータ

データを登録する際に、注釈付きのcsvデータを使用できます。
https://docs.influxdata.com/influxdb/v2/reference/syntax/annotated-csv/
→ 書式が少し複雑そう

1行目に #で開始する注釈（Annotation）でLine protocolの構成・型情報を定義します。
2行目に、名前（key）を定義します。
3行目以降に、Line protoclに基づくデータを記述します。

例）datatypeアノテーションを指定

#datatype measurement,tag,double,double,dateTime:RFC3339
name, sensor, temperature, humidity, time
weather,H103,31.8,78.1,2024-08-30T00:00:00Z
weather,H103,34.2,75.4,2024-08-30T03:00:00Z
weather,H103,35.9,73.2,2024-08-30T06:00:00Z

datatypeアノテーションで、最初のカラムがmeasurement、2列目がタグ、3列目と4列目がフィールドで型がdouble、5列目が時刻でRFC3339形式を指定しています。

タグとフィールドについては、2行目の見出し行にある名前がkeyとして使用されます。

ストレージの構造

Pointデータの書き込みバッチは、まずWAL（先行書き込みログ）にfsyncされruとともに、メモリ上のcacheに書き込まれます。
WALは、クラッシュリカバリに使うための追記型ファイルです。
cacheは、クエリーに備えてPointデータをメモリに保管しています。WALはクエリには適さないためです。
Pointデータは、cacheから定期的にTSMに書き込まれて永続化されます。TSMは一定期間の時間（shard group duration）で分割されるチャンクに構成されます。

クエリ

InfluxDBでは、Ver.1で用意されたInfluxQLと、Ver.2で追加されたFluxとの2つのクエリ言語が利用できます。

初期設定

インストール後の設定

Web UIからの設定

InfluxDBをインストールした後、データベース実行して Web UIからアクセスすると、[GET STARTED]ボタンが表示され、クリックすると初期設定画面が表示されます。

設定事項は次です。

  • Username
    WebUIアクセスで認証するユーザー名
  • Password
    WebUIアクセスで認証するパスワード（8文字以上）
  • Initial Organization Name
    任意の名前を設定、複数ユーザーを束ねるグループの概念（workspace）
  • Initial Bucket Name
    最初に作成するbucketの名前

入力後、アクセスに必要なTOKENが表示されるのでコピーをとっておきます。（全権限を持つTOKEN）

練習

練習データベースの作成と利用

トラブルシュート

ユーザー・パスワード指定で接続がエラー

$ curl -G http://www.torutk.com:8086/query -u <ユーザー名>:<パスワード> --data-urlencode "q=SHOW DATABASES" 
{"code":"unauthorized","message":"Unauthorized"}

InfluxDB 2.xでは、ユーザー・パスワード指定でREST APIがエラーを返しています。
そこで、Tokenを使用して接続します。

$ curl -G http://www.torutk.com:8086/query  --data-urlencode "q=SHOW DATABASES" \
--header "Authorization: Token <トークン文字列>" 
{"results":[{"statement_id":0,"series":[{"name":"databases","columns":["name"],"values":[["_monitoring"],["_tasks"],["mybucket"]]}]}]}

データベースの整合性

スキーマの検査・競合の検出

field keyの名前、型の一覧を取得します。

$ sudo sh -c "cd /var/lib/influxdb/engine/data; influx inspect check-schema" 
  :
Schema file written successfully to: "schema.json" 
Conflicts file written successfully to: "conflicts.json"

inspectを実行したカレントディレクトリ（上述の実行文では、/var/lib/influxdb/engine/data）に、schema.jsonファイルとconflicts.jsonファイルが生成されます。

  • schema.json
    バケットID、Retention名、Measurement名、field名、fieldの型が一覧生成
  • conflicts.json
    schema一覧から、fieldの型が競合しているものが生成
競合の発生するシナリオ例

field keyの値が最初にシェードファイルに格納される時に、最初の値によってfield keyの型が決定されます。
もし、最初の値の型が誤っている場合、続くデータは型が不一致のため格納できずにエラーとなります。

例）最初のシャードに、temperature フィールドの値として誤ったstring値"0.0"を書き込み、同じシャードの別時刻にfloat値 24.1を書き込もうとすると、string型のfieldにfloat型の値を書き込むことができずエラーとなります。

シャード：InfluxDBのバケットは、データの保持期間をRetentionポリシーで定義しています。InfluxDBは、この保持期間に基づきシャードの期間を決めており、実際のデータを物理ファイルに格納する際の格納先をシャード期間毎に分けています。デフォルトのRetentionは、保持期間が無制限でシャードの期間は168h（1週間）となります。タイムスタンプがこの1週間の範囲にあるPointデータは同じシャードに格納されます。

6ヶ月前に更新