Skip to content

Home

Jump to bottom
chengshiwen edited this page Aug 15, 2024 · 19 revisions

Influx Tool 说明文档 v0.4.1

Influx Tool 是 InfluxDB 和 Influx Proxy 的工具集合，提供高性能的数据迁移（如扩缩容、重新平衡）、数据清理、数据压缩等工具命令

使用说明

$ influx-tool --help

influx tool for influxdb and influx-proxy

Usage:
  influx-tool [command]

Available Commands:
  cleanup     Cleanup measurements with regexp
  compact     Compact the all shards fully
  completion  Generate the autocompletion script for the specified shell
  deletetsm   Delete a measurement from a raw tsm file
  export      Export tsm files into InfluxDB line protocol format
  hashdist    Hash distribution calculation
  help        Help about any command
  import      Import a previous export from file
  transfer    Transfer influxdb persist data on disk from one to another

Flags:
  -h, --help      help for influx-tool
  -v, --version   version for influx-tool

Use "influx-tool [command] --help" for more information about a command

清理命令

清理 measurements，支持正则表达式

$ influx-tool cleanup --help

Cleanup measurements with regexp

Usage:
  influx-tool cleanup [flags]

Flags:
  -H, --host string       host to connect to (default "127.0.0.1")
  -P, --port int          port to connect to (default 8086)
  -d, --database string   database to connect to the server (required)
  -u, --username string   username to connect to the server
  -p, --password string   password to connect to the server
  -s, --ssl               use https for requests (default: false)
  -r, --regexp string     regular expression of measurements to clean (default "", all)
  -m, --max-limit int     max limit to show measurements (default 0, no limit)
  -S, --show-num int      measurement number to show when show measurements (default 10)
  -D, --drop-num int      measurement number to drop per worker (default 1)
  -w, --worker int        number of concurrent workers to cleanup (default 10)
  -n, --progress int      print progress after every <n> measurements cleanup (default 10)
  -C, --cleanup           confirm cleanup the measurements (be cautious before doing it, default: false)
  -h, --help              help for cleanup

选项说明

  • -H, --host: host，默认为 127.0.0.1
  • -P, --port: 端口，默认为 8086
  • -d, --database: 数据库，必须
  • -u, --username: 用户
  • -p, --password: 密码
  • -s, --ssl: ssl 设置，针对启用了 ssl 的 influxdb 或 influx proxy，默认为 false
  • -r, --regexp: 要清除的 measurement 的正则表达式，默认为空（全部）
  • -m, --max-limit: 返回 show measurements 结果的前 <m> 个 measurement，默认为 0，不限制
  • -S, --show-num: show measurements 后默认打印前 <S> 个 measurement，默认为 10
  • -D, --drop-num: 每个 worker 线程同时清除的 measurement 的个数，默认为 1
  • -w, --worker: worker 线程数，默认为 10
  • -n, --progress: 每清除 <n> 个 measurement 时打印进度，默认为 10
  • -C, --cleanup: 是否要清除 measurements，默认不清除（执行它之前请谨慎确认，默认为 false）

注意：当 host 和 port 填写为 influx proxy 的地址时，请保持 --drop-num 为 1

压缩命令

压缩指定 db 和 rp 下的所有 shard，优化重复数据和错误数据，节约磁盘空间

$ influx-tool compact --help

Compact the all shards fully

Usage:
  influx-tool compact [flags]

Flags:
  -p, --path string   path of shard to be compacted like /path/to/influxdb/data/db/rp (required)
  -f, --force         force compaction without prompting (default: false)
  -w, --worker int    number of concurrent workers to compact (default: 0, unlimited)
  -h, --help          help for compact

选项说明

  • -p, --path: 要压缩的分片路径，如 /path/to/influxdb/data/db/rp，必须
  • -f, --force: 在没有提示的情况下强制压缩，默认弹出提示
  • -w, --worker: 压缩的并发 worker 数量，默认为 0 (无限制)，非 0 时该值越大压缩越快

删除 TSM 命令

$ influx-tool deletetsm --help

Delete a measurement from a raw tsm file

Usage:
  influx-tool deletetsm [flags] path...

Flags:
  -m, --measurement string   the name of the measurement to remove
  -s, --sanitize             remove all keys with non-printable unicode characters (default: false)
  -v, --verbose              enable verbose logging (default: false)
  -h, --help                 help for deletetsm

选项说明

  • -m, --measurement: 要删除的 measurement 名称
  • -s, --sanitize: 删除所有带有不可打印的 unicode 字符的 key（key 包含 measurement 和所有 tag 的键值对）
  • -v, --verbose: 启用详细日志记录，默认为 false

导出命令

导出持久化 tsm 文件为 InfluxDB line protocol 格式

$ influx-tool export --help

Export tsm files into InfluxDB line protocol format

Usage:
  influx-tool export [flags]

Flags:
  -D, --datadir string                   data storage path (required)
  -W, --waldir string                    wal storage path (required)
  -o, --out string                       '-' for standard out or the destination file to export to (default "./export")
  -d, --database string                  database to export without _internal (default: all)
  -r, --retention-policy string          retention policy to export (require database)
  -m, --measurement stringArray          measurement to export, can be set multiple times (require database, default: all)
  -M, --regexp-measurement stringArray   regexp measurement to export, can be set multiple times (require database, default: all)
  -S, --start string                     start time to export (RFC3339 format, optional)
  -E, --end string                       end time to export (RFC3339 format, optional)
  -l, --lponly                           only export line protocol (default: false)
  -c, --compress                         compress the output (default: false)
  -h, --help                             help for export

选项说明

  • -D, --datadir: data 存储路径，必须
  • -W, --waldir: wal 存储路径，必须
  • -o, --out: 导出的目标文件，- 表示 stdout，默认为 ./export
  • -d, --database: 导出的数据库，不含 _internal，默认为全部
  • -r, --retention-policy: 导出的保留策略，须指定 database
  • -m, --measurement: 导出的 measurement，可以设置多次，须指定 database
  • -M, --regexp-measurement: 导出的 regex measurement，可以设置多次，须指定 database
  • -S, --start: 迁移数据的起始时间，RFC3339 格式(如 2017-12-08T00:00:00.00Z 和 2017-12-08T00:08:00.00+08:00)，可选
  • -E, --end: 迁移数据的结束时间，RFC3339 格式(如 2017-12-08T00:00:00.00Z 和 2017-12-08T00:08:00.00+08:00)，可选
  • -l, --lponly: 只导出 line protocol 格式，不包括 DDL 和 DML 注释，默认为 false
  • -c, --compress: 压缩输出文件，默认为 false

哈希分布命令

$ influx-tool hashdist --help

Hash distribution calculation

Usage:
  influx-tool hashdist [flags]

Flags:
  -v, --version string       influxdb version: v1, v2 (default "v1")
  -n, --node-total int       total number of node in a circle (default 1)
  -k, --hash-key string      hash key for influx proxy: idx, exi or template containing %idx (v1 default "idx", v2 default "%idx")
  -K, --shard-key string     shard key for influx proxy, which containing %org, %bk, %db or %mm (v1 default "%db,%mm", v2 default "%org,%bk,%mm")
  -o, --org string           org name under influxdb v2, note that --file cannot be specified when --org specified
  -b, --bucket string        bucket name under influxdb v2, note that --file cannot be specified when --bucket specified
  -d, --database string      database name under influxdb v1, note that --file cannot be specified when --database specified
  -m, --measurement string   measurement name, note that --file cannot be specified when --measurement specified
  -s, --separator string     separator character to separate each line in the file (default ",")
  -f, --file string          path to the file to read, format of each line is like 'db,mm' separated by a separator
  -D, --dist string          '-' for standard out or the distribution file to write to when --file specified (default "./dist")
  -h, --help                 help for hashdist

选项说明

  • -v, --version: influxdb 版本：v1, v2，默认为 v1
  • -n, --node-total: circle 中的 influxdb 节点的总数量，默认为 1
  • -k, --hash-key: influx proxy 的 hash key: idx，exi 或包含 %idx 的模板，例如 backend-%idx，v1 默认为 idx，v2 默认为 %idx
  • -K, --shard-key: influx proxy 的 shard key，是包含 %org，%bk，%db 或 %mm 的模板，例如 shard-%db-%mm，v1 默认为 %db,%mm，v2 默认为 %org,%bk,%mm
  • -o, --org: org 名称，适用 influxdb v2，注意当指定 --org 时则不能指定 --file
  • -b, --bucket: bucket 名称，适用 influxdb v2，注意当指定 --bucket 时则不能指定 --file
  • -d, --database: database 名称，适用 influxdb v1，注意当指定 --database 时则不能指定 --file
  • -m, --measurement: measurement 名称，注意当指定 --measurement 时则不能指定 --file
  • -s, --separator: 分隔符，用于分隔 --file 指定文件中的每一行字符串，默认为 ,
  • -f, --file: 读取文件的路径，文件中的每一行字符串格式形如 db,mm，即 database、分隔符、measurement
  • -D, --dist: 输出的分布文件，- 表示 stdout，默认为 ./dist

导入命令

导入一个先前的导出文件

$ influx-tool import --help

Import a previous export from file

Usage:
  influx-tool import [flags]

Flags:
  -H, --host string       host to connect to (default "127.0.0.1")
  -P, --port int          port to connect to (default 8086)
  -u, --username string   username to connect to the server
  -p, --password string   password to connect to the server
  -s, --ssl               use https for requests (default: false)
  -f, --path string       path to the file to import (required)
  -c, --compressed        set to true if the import file is compressed (default: false)
      --pps int           points per second the import will allow (default: 0, unlimited)
  -h, --help              help for import

选项说明

  • -H, --host: host，默认为 127.0.0.1
  • -P, --port: 端口，默认为 8086
  • -u, --username: 用户
  • -p, --password: 密码
  • -s, --ssl: ssl 设置，针对启用了 ssl 的 influxdb 或 influx proxy，默认为 false
  • -f, --path: 导入文件的路径，必须
  • -c, --compressed: 当导入文件被压缩时需要设置为 true，默认为 false
  • --pps: 每秒导入的点数，默认为 0 (无限制)

注意：导入文件必须是 influx-tool export 未指定 --lponly 时生成的导出文件

迁移命令

迁移 influxdb 持久化数据，高性能且无须 influxdb 启动

$ influx-tool transfer --help

Transfer influxdb persist data on disk from one to another

Usage:
  influx-tool transfer [flags]

Flags:
  -s, --source-dir string         source influxdb directory containing meta, data and wal (required)
  -t, --target-dir string         target influxdb directory containing meta, data and wal (required)
  -d, --database string           database name (required)
  -r, --retention-policy string   retention policy (default "autogen")
      --duration duration         retention policy duration (default: 0)
      --shard-duration duration   retention policy shard duration (default 168h0m0s)
  -S, --start string              start time to transfer (RFC3339 format, optional)
  -E, --end string                end time to transfer (RFC3339 format, optional)
  -w, --worker int                number of concurrent workers to transfer (default: 0, unlimited)
      --skip-tsi                  skip building TSI index on disk (default: false)
  -n, --node-total int            total number of node in target circle (default 1)
  -i, --node-index intset         index of node in target circle delimited by comma, [0, node-total) (default: all)
  -k, --hash-key string           hash key for influx proxy: idx, exi or template containing %idx (default "idx")
  -K, --shard-key string          shard key for influx proxy, which containing %db or %mm (default "%db,%mm")
  -h, --help                      help for transfer

选项说明

  • -s, --source-dir: 来源 influxdb 目录，其包含 meta, data and wal，必须
  • -t, --target-dir: 目标 influxdb 目录，其包含 meta, data and wal，必须
  • -d, --database: 数据库名称，必须
  • -r, --retention-policy: 保留策略名称，默认为 autogen
  • --duration: 保留策略的时长，默认为 0，即全部保留，一般不用设置
  • --shard-duration: 保留策略的 shard 分组时长，默认为 168h0m0s，即一周，一般不用设置
  • -S, --start: 迁移数据的起始时间，RFC3339 格式(如 2017-12-08T00:00:00.00Z 和 2017-12-08T00:08:00.00+08:00)，可选
  • -E, --end: 迁移数据的结束时间，RFC3339 格式(如 2017-12-08T00:00:00.00Z 和 2017-12-08T00:08:00.00+08:00)，可选
  • -w, --worker: 迁移的并发 worker 数量，默认为 0 (无限制)，非 0 时该值越大迁移越快
  • --skip-tsi: 跳过构建磁盘的 TSI 索引，当 index-version = inmem 时需要开启此选项，默认为 false
  • -n, --node-total: 需要迁移的目标 circle 中的 influxdb 节点的总数量，默认为 1
  • -i, --node-index: 需要迁移的目标 circle 中的 influxdb 节点的指定索引，以英文逗号分隔，要求范围 [0, node-total)，默认为所有
  • -k, --hash-key: influx proxy 的 hash key: idx，exi 或包含 %idx 的模板，例如 backend-%idx，默认为 idx
  • -K, --shard-key: influx proxy 的 shard key，是包含 %db 或 %mm 的模板，例如 shard-%db-%mm，默认为 %db,%mm

迁移要求

  • 停止所有 influxdb 实例
  • 迁移后的 influx-proxy 版本 >= 2.4.7，建议使用最新版本 2.5.x，要求 hash_key 为 idx，exi 或包含 %idx 的模板

使用示例

假如原来有 influxdb 集群有 2 个 circle，选择一个数据最全的 circle，假设它有 3 influxdb 实例，分别对应以下 3 个数据持久化目录（以下目录仅为参考，以实际目录为准）：

/data/source-1/influxdb
/data/source-2/influxdb
/data/source-3/influxdb

我们要迁移到新的 influxdb 集群，假设第一个 circle 有 4 个 influxdb，迁移的数据库名称为 db，默认的保留策略为 autogen，数据全部迁移，假设用 8 个 worker 线程同时迁移，则需要执行以下命令：

./influx-tool transfer --source-dir /data/source-1/influxdb --target-dir /data/target/influxdb --database db --node-total 4 --worker 8
./influx-tool transfer --source-dir /data/source-2/influxdb --target-dir /data/target/influxdb --database db --node-total 4 --worker 8
./influx-tool transfer --source-dir /data/source-3/influxdb --target-dir /data/target/influxdb --database db --node-total 4 --worker 8

./influx-tool compact --path /data/target/influxdb-0/data/db/autogen --force --worker 8
./influx-tool compact --path /data/target/influxdb-1/data/db/autogen --force --worker 8
./influx-tool compact --path /data/target/influxdb-2/data/db/autogen --force --worker 8
./influx-tool compact --path /data/target/influxdb-3/data/db/autogen --force --worker 8

前 3 条命令将老的 3 个 influxdb 数据迁移到 /data/target/influxdb 目录下，生成以下 4 个新的 influxdb 数据目录（目录名称为 {target-dir}-{序号}，其中 序号 的范围为 [0, {node-total})，共 {node-total} 个），其顺序和 proxy.json 中对应的 backends 顺序一致（以下目录仅为参考，以实际目录为准）：

/data/target/influxdb-0
/data/target/influxdb-1
/data/target/influxdb-2
/data/target/influxdb-3

注意：因为 /data/target/influxdb 是同一个目录，因此必须在同一台机器上执行，最好将 /data/source-1/influxdb、/data/source-2/influxdb、/data/source-3/influxdb 放到同一机器上；或者依次将 /data/target/influxdb 拷贝到 /data/source-n/influxdb 所在机器上

后 4 条命令是对迁移后的数据进行压缩优化，例如重复数据、错误数据的优化，当然不执行也不会有问题

当第 1 个 circle 迁移完成后，第 2 个 circle 如果 backend 数量和第 1 个 circle 一致，则直接复制第 1 个 circle 的所有 influxdb 持久化数据到第 2 个 circle 即可

注意事项

influx-tool 可以用于 influx-proxy 及 influxdb 集群的动态扩缩容、重新平衡、故障恢复、数据同步等，需要停止 influx-proxy 和 influxdb 集群，根据实际情况有以下两个方案：

  • 方案一：使用 influx-tool transfer 命令进行迁移，无须 influxdb 运行，具有很高的性能：2-4 GB/min（以实际环境为准）
    • 特性：influx-tool transfer 将直接读取 influxdb 实例的持久化文件进行迁移，并非基于 http 接口进行数据并行查询和写入，因此具有很高的性能
    • 存在问题：要求 influxdb 必须停止运行，且迁移的 measurement 和 tags 不能包含特殊字符 ,(逗号)、 (空格)、=(等号)，否则会被丢弃；对于丢弃的 measurement，可以考虑性能较低的方案二
  • 方案二：使用 influx-tool export 命令导出数据，再使用 influx-tool import 或 influx -import -path 导入到 influx proxy
    • 存在问题：此方案通过扫描磁盘文件导出，再通过 http 接口导入，导入性能较低、但整体性能高于 rebalance 操作，适合少部分数据的情形
    • 支持特性：influx-tool export 支持 --measurement 和 --regexp-measurement 导出特定 measurement，选项可以设置多次

发版日志

v0.4.1

v0.4.0

  • 修复 cleanup 命令中 measurement 转义问题
  • 修复 transfer 命令中指定 --hash-key=exi 时导致 hash 分配不生效问题
  • 支持 transfer 命令中自定义 --hash-key 模板，例如 backend-%idx
  • 支持 transfer 命令中自定义 --shard-key 模板，例如 shard-%db-%mm
  • 添加 hashdist 命令，用于哈希分布计算
  • 添加 deletetsm 命令，用于从原始 tsm 文件中删除 measurement

v0.3.2

v0.3.1

  • 优化所有命令
  • 支持 darwin/arm64 版本
  • 升级依赖库，解决安全问题

v0.3.0

  • 添加 export 命令，用于将 tsm 文件导出为 InfluxDB 行协议格式
  • 添加 import 命令，用于从文件导入先前导出的内容
  • export 命令: 支持 --measurement 和 --regexp-measurement 用于导出特定 measurement
  • transfer 命令: 修复 slice bounds out of range in series_cursor next

v0.2.0

  • 添加 cleanup 命令，用于清理 measurement，支持正则表达式
  • 添加 compact 命令，用于完全压缩所有分片
  • 添加 transfer 命令，用于将磁盘上的 influxdb 持久数据从一个磁盘迁移到另一个磁盘
  • transfer 命令: 修复 panic: keys must be added in sorted order
Clone this wiki locally