配置 GreptimeDB

GreptimeDB 提供了层次化的配置能力,按照下列优先顺序来生效配置:

  • 命令行参数
  • 配置文件
  • 环境变量
  • 默认值

本文介绍了配置 GreptimeDB server 的方法,用户可以在 TOML 文件中进行设置。

在配置文件中,对于缺失的参数,系统会赋予其一个默认值。

所有样本配置文件都放在项目的 config 文件夹中。

命令行选项

请阅读命令行工具学习如何使用 greptime 命令行工具。

全局选项

  • -h/--help: 打印命令行帮助信息
  • -V/--version: 打印 GreptimeDB 版本信息
  • --log-dir <LOG_DIR>: 指定日志路径
  • --log-level <LOG_LEVEL>: 指定日志级别,如 infodebug 等。

datanode 子命令选项

通过执行下列命令来获取 datanode 子命令的帮助菜单:

  1. greptime datanode start --help
  • -c/--config-file: 指定 datanode 启动的配置文件
  • --data-home: 数据库存储 home 目录
  • --env-prefix <ENV_PREFIX>: 配置的环境变量前缀,默认为 GREPTIMEDB_DATANODE;
  • --http-addr <HTTP_ADDR>: HTTP 服务地址
  • --http-timeout <HTTP_TIMEOUT>: HTTP 超时设置,单位秒
  • --metasrv-addr <METASRV_ADDR>: Metasrv 服务器列表,用逗号隔开
  • --node-id <NODE_ID>: 节点 ID
  • --rpc-addr <RPC_ADDR>: gRPC 服务地址
  • --rpc-hostname <RPC_HOSTNAME>: 节点 hostname
  • --wal-dir <WAL_DIR>: WAL 日志目录;

所有的地址类选项都是 ip:port 形式的字符串。

metasrv 子命令选项

通过执行下列命令来获取 metasrv 子命令的帮助菜单:

  1. greptime metasrv start --help
  • -c/--config-file: 指定 metasrv 启动配置文件
  • --enable-region-failover: 是否启动 region 自动容灾,默认为 false 不启用。
  • --env-prefix <ENV_PREFIX>: 配置的环境变量前缀,默认为GREPTIMEDB_METASRV;
  • --bind-addr <BIND_ADDR>:服务监听地址,默认为 127.0.0.1:3002.
  • --http-addr <HTTP_ADDR>: HTTP 服务器地址
  • --http-timeout <HTTP_TIMEOUT>: HTTP 超时设置,单位秒
  • --selector <SELECTOR>: 参考 selector 类型;
  • --server-addr <SERVER_ADDR>: 提供给 frontend 和 datanode 的外部通讯服务器地址
  • --store-addr <STORE_ADDR>: 存储元数据的 etcd 地址列表,用逗号隔开
  • --use-memory-store: 是否使用内存存储替代 etcd,仅用于测试

frontend 子命令选项

通过执行下列命令来获取 frontend 子命令的帮助菜单:

  1. greptime frontend start --help
  • -c/--config-file: 指定 frontend 启动配置文件
  • --disable-dashboard: 是否禁用 dashboard,默认为 false
  • --env-prefix <ENV_PREFIX>: 配置的环境变量前缀,默认为GREPTIMEDB_FRONTEND;
  • --rpc-addr <RPC_ADDR>: gRPC 服务地址
  • --http-addr <HTTP_ADDR>: HTTP 服务器地址
  • --http-timeout <HTTP_TIMEOUT>: HTTP 超时设置,单位秒
  • --influxdb-enable: 是否启用 influxdb HTTP 接口,默认为 true。
  • --metasrv-addr <METASRV_ADDR>: Metasrv 地址列表,用逗号隔开
  • --mysql-addr <MYSQL_ADDR>: MySQL 服务地址
  • --opentsdb-addr <OPENTSDB_ADDR>: OpenTSDB 服务地址
  • --postgres-addr <POSTGRES_ADDR>: Postgres 服务地址
  • --tls-cert-path <TLS_CERT_PATH>: TLS 公钥文件地址
  • --tls-key-path <TLS_KEY_PATH>: TLS 私钥文件地址
  • --tls-mode <TLS_MODE>: TLS 模式
  • --user-provider <USER_PROVIDER>: 参考 鉴权;

standalone 子命令选项

通过执行下列命令来获取 standalone 子命令的帮助菜单:

  1. greptime standalone start --help
  • -c/--config-file: 指定 standalone 启动配置文件
  • --env-prefix <ENV_PREFIX>: 配置的环境变量前缀,默认为GREPTIMEDB_STANDALONE;
  • --http-addr <HTTP_ADDR>: HTTP 服务器地址
  • --influxdb-enable: 是否启用 influxdb HTTP 接口,默认为 true。
  • --mysql-addr <MYSQL_ADDR>: MySQL 服务地址
  • --opentsdb-addr <OPENTSDB_ADDR>: OpenTSDB 服务地址
  • --postgres-addr <POSTGRES_ADDR>: Postgres 服务地址
  • --rpc-addr <RPC_ADDR>: gRPC 服务地址

配置文件

示例

各项配置根据其功能适用于一个或多个组件。本文档只包含部分常用配置的示例。完整的配置说明可以在这个自动生成的文档中找到。

你可以在 GitHub 上找到每个组件的所有可用配置示例:

指定配置文件

用户可以通过使用命令行参数 -c [file_path] 指定配置文件。

  1. greptime [standalone | frontend | datanode | metasrv] start -c config/standalone.example.toml

例如,启动 standalone 模式:

  1. greptime standalone start -c standalone.example.toml

协议选项

协议选项适用于 frontendstandalone 子命令,它指定了协议服务器地址和其他协议相关的选项。

下面的示例配置包含了所有协议选项的默认值。 为了使数据库正常工作,配置中必须启用 HTTP 和 gRPC 协议,其他协议可选。 如果要禁用某些选项,比如禁用 OpenTSDB 协议,可以将 enable 参数设置为 false

  1. [http]
  2. addr = "127.0.0.1:4000"
  3. timeout = "30s"
  4. body_limit = "64MB"
  5. [grpc]
  6. addr = "127.0.0.1:4001"
  7. runtime_size = 8
  8. [mysql]
  9. enable = true
  10. addr = "127.0.0.1:4002"
  11. runtime_size = 2
  12. [mysql.tls]
  13. mode = "disable"
  14. cert_path = ""
  15. key_path = ""
  16. [postgres]
  17. enable = true
  18. addr = "127.0.0.1:4003"
  19. runtime_size = 2
  20. [postgres.tls]
  21. mode = "disable"
  22. cert_path = ""
  23. key_path = ""
  24. [opentsdb]
  25. enable = true
  26. addr = "127.0.0.1:4242"
  27. runtime_size = 2
  28. [influxdb]
  29. enable = true
  30. [prom_store]
  31. enable = true

下表描述了每个选项的详细信息:

选项类型描述
httpHTTP 服务器选项
addr字符串服务器地址,默认为 “127.0.0.1:4000”
timeout字符串HTTP 请求超时时间,默认为 “30s”
body_limit字符串HTTP 最大体积大小,默认为 “64MB”
grpcgRPC 服务器选项
addr字符串服务器地址,默认为 “127.0.0.1:4001”
runtime_size整数服务器工作线程数量,默认为 8
mysqlMySQL 服务器选项
enable布尔值是否启用 MySQL 协议,默认为 true
add字符串服务器地址,默认为 “127.0.0.1:4002”
runtime_size整数服务器工作线程数量,默认为 2
influxdbInfluxDB 协议选项
enable布尔值是否在 HTTP API 中启用 InfluxDB 协议,默认为 true
opentsdbOpenTSDB 协议选项
enable布尔值是否启用 OpenTSDB 协议,默认为 true
addr字符串OpenTSDB telnet API 服务器地址,默认为 “127.0.0.1:4242”
runtime_size整数服务器工作线程数量,默认为 2
prom_storePrometheus 远程存储选项
enable布尔值是否在 HTTP API 中启用 Prometheus 远程读写,默认为 true
with_metric_engine布尔值是否在 Prometheus 远程写入中使用 Metric Engine,默认为 true
postgresPostgresSQL 服务器选项
enable布尔值是否启用 PostgresSQL 协议,默认为 true
addr字符串服务器地址,默认为 “127.0.0.1:4003”
runtime_size整数服务器工作线程数量,默认为 2

存储选项

存储选项在 datanodestandalone 模式下有效,它指定了数据库数据目录和其他存储相关的选项。

GreptimeDB 支持将数据保存在本地文件系统, AWS S3 以及其兼容服务(比如 MinIO、digitalocean space、腾讯 COS、百度对象存储(BOS)等),Azure Blob Storage 和阿里云 OSS。

选项类型描述
storage存储选项
type字符串存储类型,支持 “File”,”S3” 和 “Oss” 等.
File本地文件存储选项,当 type=”File” 时有效
data_home字符串数据库存储根目录,默认为 “/tmp/greptimedb”
S3AWS S3 存储选项,当 type=”S3” 时有效
bucket字符串S3 桶名称
root字符串S3 桶中的根路径
endpoint字符串S3 的 API 端点
region字符串S3 区域
access_key_id字符串S3 访问密钥 id
secret_access_key字符串S3 秘密访问密钥
Oss阿里云 OSS 存储选项,当 type=”Oss” 时有效
bucket字符串OSS 桶名称
root字符串OSS 桶中的根路径
endpoint字符串OSS 的 API 端点
access_key_id字符串OSS 访问密钥 id
secret_access_key字符串OSS 秘密访问密钥
AzblobAzure Blob 存储选项,当 type=”Azblob” 时有效
container字符串容器名称
root字符串容器中的根路径
endpoint字符串Azure Blob 存储的 API 端点
account_name字符串Azure Blob 存储的账户名
account_key字符串访问密钥
sas_token字符串共享访问签名
GscGoogle Cloud Storage 存储选项,当 type=”Gsc” 时有效
root字符串Gsc 桶中的根路径
bucket字符串Gsc 桶名称
scope字符串Gsc 权限
credential_path字符串Gsc 访问证书
endpoint字符串GSC 的 API 端点

文件存储配置范例:

  1. [storage]
  2. type = "File"
  3. data_home = "/tmp/greptimedb/"

s3 配置范例:

  1. [storage]
  2. type = "S3"
  3. bucket = "test_greptimedb"
  4. root = "/greptimedb"
  5. access_key_id = "<access key id>"
  6. secret_access_key = "<secret access key>"

存储引擎提供商

[[storage.providers]] 用来设置存储引擎的提供商列表。基于这个配置,你可以为每张表指定不同的存储引擎,具体请参考 create table:

  1. # Allows using multiple storages
  2. [[storage.providers]]
  3. type = "S3"
  4. bucket = "test_greptimedb"
  5. root = "/greptimedb"
  6. access_key_id = "<access key id>"
  7. secret_access_key = "<secret access key>"
  8. [[storage.providers]]
  9. type = "Gcs"
  10. bucket = "test_greptimedb"
  11. root = "/greptimedb"
  12. credential_path = "<gcs credential path>"

所有配置的这些存储引擎提供商都可以在创建表时用作 storage 选项。

对象存储缓存

当使用 S3、阿里云 OSS 等对象存储的时候,最好开启缓存来加速查询:

  1. [storage]
  2. type = "S3"
  3. bucket = "test_greptimedb"
  4. root = "/greptimedb"
  5. access_key_id = "<access key id>"
  6. secret_access_key = "<secret access key>"
  7. ## 开启对象存储缓存
  8. cache_path = "/var/data/s3_local_cache"
  9. cache_capacity = "256MiB"

cache_path 指定本地的缓存目录, cache_capacity 指定缓存的最大大小(字节)。

WAL 选项

datanode 和 standalone 在 [wal] 部分可以配置 Write-Ahead-Log 的对应参数:

  1. [wal]
  2. file_size = "256MB"
  3. purge_threshold = "4GB"
  4. purge_interval = "10m"
  5. read_batch_size = 128
  6. sync_write = false
  • dir: WAL 的日志目录, 当使用文件 File 存储的时候, 默认值为{data_home}/wal 。当使用对象存储的时候,必须明确指定。
  • file_size: 单个日志文件的最大大小,默认为 256MB
  • purge_thresholdpurge_interval: 控制清除任务的触发阈值和间隔
  • sync_write: 是否在写入每条日志的时候调用 l fsync 刷盘。

Logging 选项

frontendmetasrvdatanodestandalone 都可以在 [logging] 部分配置 log、tracing 相关参数:

  1. [logging]
  2. dir = "/tmp/greptimedb/logs"
  3. level = "info"
  4. enable_otlp_tracing = false
  5. otlp_endpoint = "localhost:4317"
  6. append_stdout = true
  7. [logging.tracing_sample_ratio]
  8. default_ratio = 1.0
  • dir: log 输出目录。
  • level: log 输出的日志等级,日志等级有 info, debug, error, warn,默认等级为 info
  • enable_otlp_tracing:是否打开分布式追踪,默认不开启。
  • otlp_endpoint:使用基于 gRPC 的 OTLP 协议导出 tracing 的目标端点,默认值为 localhost:4317
  • append_stdout:是否将日志打印到stdout。默认是true
  • tracing_sample_ratio:该字段可以配置 tracing 的采样率,如何使用 tracing_sample_ratio,请参考 如何配置 tracing 采样率

如何使用分布式追踪,请参考 Tracing

Region 引擎选项

datanode 和 standalone 在 [region_engine] 部分可以配置不同存储引擎的对应参数。目前只可以配置存储引擎 mito 的选项。

部分常用的选项如下

  1. [[region_engine]]
  2. [region_engine.mito]
  3. num_workers = 8
  4. manifest_checkpoint_distance = 10
  5. max_background_jobs = 4
  6. auto_flush_interval = "1h"
  7. global_write_buffer_size = "1GB"
  8. global_write_buffer_reject_size = "2GB"
  9. sst_meta_cache_size = "128MB"
  10. vector_cache_size = "512MB"
  11. page_cache_size = "512MB"
  12. sst_write_buffer_size = "8MB"
  13. scan_parallelism = 0
  14. [region_engine.mito.inverted_index]
  15. create_on_flush = "auto"
  16. create_on_compaction = "auto"
  17. apply_on_query = "auto"
  18. mem_threshold_on_create = "64M"
  19. intermediate_path = ""
  20. [region_engine.mito.memtable]
  21. type = "time_series"

此外,mito 也提供了一个实验性质的 memtable。该 memtable 主要优化大量时间序列下的写入性能和内存占用。其查询性能可能会不如默认的 time_series memtable。

  1. [region_engine.mito.memtable]
  2. type = "partition_tree"
  3. index_max_keys_per_shard = 8192
  4. data_freeze_threshold = 32768
  5. fork_dictionary_bytes = "1GiB"

以下是可供使用的选项

类型默认值描述
num_workers整数8写入线程数量
manifest_checkpoint_distance整数10每写入 manifest_checkpoint_distance 个 manifest 文件创建一次 checkpoint
max_background_jobs整数4后台线程数量
auto_flush_interval字符串1h自动 flush 超过 auto_flush_interval 没 flush 的 region
global_write_buffer_size字符串1GB写入缓冲区大小,默认值为内存总量的 1/8,但不会超过 1GB
global_write_buffer_reject_size字符串2GB写入缓冲区内数据的大小超过 global_write_buffer_reject_size 后拒
绝写入请求,默认为 global_write_buffer_size 的 2 倍
sst_meta_cache_size字符串128MBSST 元数据缓存大小。设为 0 可关闭该缓存
默认为内存的 1/32,不超过 128MB
vector_cache_size字符串512MB内存向量和 arrow array 的缓存大小。设为 0 可关闭该缓存
默认为内存的 1/16,不超过 512MB
page_cache_size字符串512MBSST 数据页的缓存。设为 0 可关闭该缓存
默认为内存的 1/16,不超过 512MB
sst_write_buffer_size字符串8MBSST 的写缓存大小
scan_parallelism整数0扫描并发度 (默认 1/4 CPU 核数)
- 0: 使用默认值 (1/4 CPU 核数)
- 1: 单线程扫描
- n: 按并行度 n 扫描
inverted_index.create_on_flush字符串auto是否在 flush 时构建索引
- auto: 自动
- disable: 从不
inverted_index.create_on_compaction字符串auto是否在 compaction 时构建索引
- auto: 自动
- disable: 从不
inverted_index.apply_on_query字符串auto是否在查询时使用索引
- auto: 自动
- disable: 从不
inverted_index.mem_threshold_on_create字符串64M创建索引时如果超过该内存阈值则改为使用外部排序
设置为空会关闭外排,在内存中完成所有排序
inverted_index.intermediate_path字符串“”存放外排临时文件的路径 (默认 {data_home}/index_intermediate).
memtable.type字符串time_seriesMemtable type.
- time_series: time-series memtable
- partition_tree: partition tree memtable (实验性功能)
memtable.index_max_keys_per_shard整数8192一个 shard 内的主键数
只对 partition_tree memtable 生效
memtable.data_freeze_threshold整数32768一个 shard 内写缓存可容纳的最大行数
只对 partition_tree memtable 生效
memtable.fork_dictionary_bytes字符串1GiB主键字典的大小
只对 partition_tree memtable 生效

设定 meta client

meta_client 选项适用于 datanodefrontend 模块,用于指定 Metasrv 的相关信息。

  1. [meta_client]
  2. metasrv_addrs = ["127.0.0.1:3002"]
  3. timeout = "3s"
  4. connect_timeout = "1s"
  5. ddl_timeout = "10s"
  6. tcp_nodelay = true

通过 meta_client 配置 metasrv 客户端,包括:

  • metasrv_addrs, Metasrv 地址列表,对应 Metasrv 启动配置的 server address。
  • timeout, 操作超时时长,默认为 3 秒。
  • connect_timeout,连接服务器超时时长,默认为 1 秒。
  • ddl_timeout, DDL 执行的超时时间,默认 10 秒。
  • tcp_nodelay,接受连接时的 TCP_NODELAY 选项,默认为 true。

指标监控选项

这些选项用于将系统监控指标保存到 GreptimeDB 本身。 有关如何使用此功能的说明,请参见 监控 指南。

  1. [export_metrics]
  2. # Whether to enable export_metrics
  3. enable=true
  4. # Export time interval
  5. write_interval = "30s"
  • enable: 是否启用导出指标功能,默认为 false
  • write_interval: 指标导出时间间隔。

self_import 方法

frontendstandalone 支持使用 self_import 方法导出指标。

  1. [export_metrics]
  2. # Whether to enable export_metrics
  3. enable=true
  4. # Export time interval
  5. write_interval = "30s"
  6. [export_metrics.self_import]
  7. db = "information_schema"
  • db: 默认的数据库为 information_schema,你也可以创建另一个数据库来保存系统指标。

remote_write 方法

datanodefrontendmetasrvstandalone 支持使用 remote_write 方法导出指标。 它将指标发送到与 Prometheus Remote-Write protocol 兼容的接受端。

  1. [export_metrics]
  2. # Whether to enable export_metrics
  3. enable=true
  4. # Export time interval
  5. write_interval = "30s"
  6. [export_metrics.remote_write]
  7. # URL specified by Prometheus Remote-Write protocol
  8. url = "http://127.0.0.1:4000/v1/prometheus/write?db=information_schema"
  9. # Some optional HTTP parameters, such as authentication information
  10. headers = { Authorization = "Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=" }
  • url: Prometheus Remote-Write 协议指定的 URL。
  • headers: 一些可选的 HTTP 参数,比如认证信息。

Mode 选项

mode 选项在 datanodefrontendstandalone 中可用,它指定了组件的运行模式。

在分布式 GreptimeDB 的 datanodefrontend 的配置文件中,需要将值设置为 distributed

  1. mode = "distributed"

在 standalone GreptimeDB 的配置文件中,需要将值设置为 standalone

  1. mode = "standalone"

仅限于 Metasrv 的配置

  1. # The working home directory.
  2. data_home = "/tmp/metasrv/"
  3. # The bind address of metasrv, "127.0.0.1:3002" by default.
  4. bind_addr = "127.0.0.1:3002"
  5. # The communication server address for frontend and datanode to connect to metasrv, "127.0.0.1:3002" by default for localhost.
  6. server_addr = "127.0.0.1:3002"
  7. # Etcd server addresses, "127.0.0.1:2379" by default.
  8. store_addr = "127.0.0.1:2379"
  9. # Datanode selector type.
  10. # - "lease_based" (default value).
  11. # - "load_based"
  12. # For details, please see "https://docs.greptime.com/contributor-guide/meta/selector".
  13. selector = "lease_based"
  14. # Store data in memory, false by default.
  15. use_memory_store = false
类型描述
data_home字符串Metasrv 的工作目录,默认为 “/tmp/metasrv/“
bind_addr字符串Metasrv 的绑定地址,默认为 “127.0.0.1:3002”
server_addr字符串前端和数据节点连接到 Metasrv 的通信服务器地址,默认为 “127.0.0.1:3002”(适用于本地主机)
store_addr字符串etcd 服务器地址,默认为 “127.0.0.1:2379”,服务器地址由逗号分隔,格式为 “ip1:port1,ip2:port2,…”
selector字符串创建新表时选择数据节点的负载均衡策略,参见 选择器
use_memory_store布尔值仅在测试时使用,当你没有 etcd 集群时,将数据存储在内存中,默认为 false

仅限于 Datanode 的配置

  1. node_id = 42
  2. rpc_hostname = "127.0.0.1"
  3. rpc_addr = "127.0.0.1:3001"
  4. rpc_runtime_size = 8
KeyTypeDescription
node_id整数datanode 的唯一标识符。
rpc_hostname字符串datanode 的 Hostname。
rpc_addr字符串gRPC 服务端地址,默认为“127.0.0.1:3001”
rpc_runtime_size整数gRPC 服务器工作线程数,默认为 8。

环境变量配置

配置文件中的每一项都可以映射到环境变量。例如,如果我们想通过环境变量设置 datanode 的配置项 data_home

  1. # ...
  2. [storage]
  3. data_home = "/data/greptimedb"
  4. # ...

你可以使用以下的 shell 命令来设置环境变量,格式如下:

  1. export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb

环境变量规则

  • 每个环境变量应该有组件前缀,例如:

    • GREPTIMEDB_FRONTEND
    • GREPTIMEDB_METASRV
    • GREPTIMEDB_DATANODE
    • GREPTIMEDB_STANDALONE
  • 我们使用双下划线 __ 作为分隔符。例如,上述的数据结构 storage.data_home 将被转换为 STORAGE__DATA_HOME

环境变量也接受用逗号 , 分隔的列表,例如:

  1. GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003