配置 GreptimeDB
GreptimeDB 提供了层次化的配置能力,按照下列优先顺序来生效配置(每个项目都会覆盖下面的项目):
- Greptime 命令行选项
- 配置文件选项
- 环境变量
- 默认值
你只需要设置所需的配置项。 GreptimeDB 将为未配置的任何设置分配默认值。
如何设置配置项
Greptime 命令行选项
你可以使用命令行参数指定多个配置项。 例如,以配置的 HTTP 地址启动 GreptimeDB 的独立模式:
greptime standalone start --http-addr 127.0.0.1:4000
有关 Greptime 命令行支持的所有选项,请参阅 GreptimeDB 命令行界面。
配置文件选项
你可以在 TOML 文件中指定配置项。
例如,创建一个名为 standalone.example.toml
的配置文件,如下所示:
[storage]
type = "File"
data_home = "./greptimedb_data/"
然后使用命令行参数 -c [file_path]
指定配置文件。
greptime [standalone | frontend | datanode | metasrv] start -c config/standalone.example.toml
例如以 standalone 模式启动 GreptimeDB:
greptime standalone start -c standalone.example.toml
示例文件
以下是每个 GreptimeDB 组件的示例配置文件,包括所有可用配置项。 在实际场景中,你只需要配置所需的选项,不需要像示例文件中那样配置所有选项。
Helm 配置
当使用 Helm 在 Kubernetes 上部署 GreptimeDB 时,你可以直接在 Helm values.yaml
文件中做相应的设置。
请参阅 Helm 配置项文档了解所有 Helm 支持的配置项。
对于仅在本篇文档中可用的配置项,你可以通过注入 TOML 配置文件来设置配置。
环境变量
配置文件中的每个项目都可以映射到环境变量。
例如,使用环境变量设置数据节点的 data_home
配置项:
# ...
[storage]
data_home = "/data/greptimedb"
# ...
使用以下 shell 命令以以下格式设置环境变量:
export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb
环境变量规则
-
每个环境变量应具有组件前缀,例如:
GREPTIMEDB_FRONTEND
GREPTIMEDB_METASRV
GREPTIMEDB_DATANODE
GREPTIMEDB_STANDALONE
-
使用**双下划线
__
**作为分隔符。例如,数据结构storage.data_home
转换为STORAGE__DATA_HOME
。
环境变量还接受以逗号 ,
分隔的列表,例如:
GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003
配置项
本节将介绍主要的配置项,请前往 GitHub 查看所有配置项。
协议选项
协议选项适用于 frontend
和 standalone
子命令,它指定了协议服务器地址和其他协议相关的选项。
HTTP 协议配置适用于所有 GreptimeDB 组件:frontend
、datanode
、flownode
和 metasrv
。
下面的示例配置包含了所有协议选项的默认值。
你可以在配置文件中更改这些值或禁用某些协议。
例如禁用 OpenTSDB 协议支持,可以将 enable
参数设置为 false
。
请注意,为了保障数据库的正常工作,无法禁用 HTTP 和 gRPC 协议。
[http]
addr = "127.0.0.1:4000"
timeout = "30s"
body_limit = "64MB"
[grpc]
bind_addr = "127.0.0.1:4001"
runtime_size = 8
[mysql]
enable = true
addr = "127.0.0.1:4002"
runtime_size = 2
[mysql.tls]
mode = "disable"
cert_path = ""
key_path = ""
[postgres]
enable = true
addr = "127.0.0.1:4003"
runtime_size = 2
[postgres.tls]
mode = "disable"
cert_path = ""
key_path = ""
[opentsdb]
enable = true
[influxdb]
enable = true
[prom_store]
enable = true
下表描述了每个选项的详细信息:
选项 | 键 | 类型 | 描述 |
---|---|---|---|
http | HTTP 服务器选项 | ||
addr | 字符串 | 服务器地址,默认为 "127.0.0.1:4000" | |
timeout | 字符串 | HTTP 请求超时时间,默认为 "30s" | |
body_limit | 字符串 | HTTP 最大体积大小,默认为 "64MB" | |
prom_validation_mode | 字符串 | 在 Prometheus Remote Write 协议中中是否检查字符串是否为有效的 UTF-8 字符串。可用选项:strict (拒绝任何包含无效 UTF-8 字符串的请求),lossy (用 UTF-8 REPLACEMENT CHARACTER(即 � ) 替换无效字符),unchecked (不验证字符串有效性)。 | |
grpc | gRPC 服务器选项 | ||
bind_addr | 字符串 | gRPC 服务绑定地址,默认为 "127.0.0.1:4001" | |
runtime_size | 整数 | 服务器工作线程数量,默认为 8 | |
flight_compression | 字符串 | Frontend 的 Arrow IPC 服务的压缩模式。可用选项:none :禁用所有压缩,transport :仅启用 gRPC 传输压缩(zstd),arrow_ipc :仅启用 Arrow IPC 压缩(lz4),all :启用所有压缩。默认值为 none 。 | |
mysql | MySQL 服务器选项 | ||
enable | 布尔值 | 是否启用 MySQL 协议,默认为 true | |
addr | 字符串 | 服务器地址,默认为 "127.0.0.1:4002" | |
runtime_size | 整数 | 服务器工作线程数量,默认为 2 | |
influxdb | InfluxDB 协议选项 | ||
enable | 布尔值 | 是否在 HTTP API 中启用 InfluxDB 协议,默认为 true | |
opentsdb | OpenTSDB 协议选项 | ||
enable | 布尔值 | 是否启用 OpenTSDB 协议,默认为 true | |
prom_store | Prometheus 远程存储选项 | ||
enable | 布尔值 | 是否在 HTTP API 中启用 Prometheus 远程读写,默认为 true | |
with_metric_engine | 布尔值 | 是否在 Prometheus 远程写入中使用 Metric Engine,默认为 true | |
postgres | PostgresSQL 服务器选项 | ||
enable | 布尔值 | 是否启用 PostgresSQL 协议,默认为 true | |
addr | 字符串 | 服务器地址,默认为 "127.0.0.1:4003" | |
runtime_size | 整数 | 服务器工作线程数量,默认为 2 |
对 MySQL,Postgres 和 gRPC 接口,我们支持 TLS 配置
Option | Key | Type | Description |
---|---|---|---|
mysql.tls ,postgres.tls 或 grpc.tls | MySQL 或 Postgres 的 TLS 配置 | ||
mode | String | TLS 模式,支持 disable , prefer and require | |
cert_path | String | TLS 证书文件路径 | |
key_path | String | TLS 私钥文件路径 | |
watch | Boolean | 监控文件变化,自动重新加载证书或私钥 |
查询选项
查询
选项在 standalone、datanode 和 frontend 模式下有效,用于控制查询引擎的行为。
下表详细描述了这些选项:
选项 | 键 | 类型 | 描述 |
---|---|---|---|
parallelism | 整数 | 0 | 查询引擎的并行度。默认为 0,表示 CPU 核心数。 |
示例配置:
[query]
parallelism = 0
存储选项
存储
选项在 datanode
和 standalone
模式下有效,它指定了数据库数据目录和其他存储相关的选项。
GreptimeDB 支持将数据保存在本地文件系统,AWS S3 以及其兼容服务(比如 MinIO、digitalocean space、腾讯 COS、百度对象存储(BOS)等),Azure Blob Storage 和阿里云 OSS。
选项 | 键 | 类型 | 描述 |
---|---|---|---|
storage | 存储选项 | ||
type | 字符串 | 存储类型,支持 "File","S3" 和 "Oss" 等。 | |
File | 本 地文件存储选项,当 type="File" 时有效 | ||
data_home | 字符串 | 数据库存储根目录,默认为 "./greptimedb_data" | |
S3 | AWS S3 存储选项,当 type="S3" 时有效 | ||
name | 字符串 | 存储提供商名字,默认为 S3 | |
bucket | 字符串 | S3 桶名称 | |
root | 字符串 | S3 桶中的根路径 | |
endpoint | 字符串 | S3 的 API 端点 | |
region | 字符串 | S3 区域 | |
access_key_id | 字符串 | S3 访问密钥 id | |
secret_access_key | 字符串 | S3 秘密访问密钥 | |
enable_virtual_host_style | 布尔值 | 使用 virtual-host-style 域名而不是 path-style 域名调用 API,默认为 false | |
Oss | 阿里云 OSS 存储选项,当 type="Oss" 时有效 | ||
name | 字符串 | 存储提供商名字,默认为 Oss | |
bucket | 字符串 | OSS 桶名称 | |
root | 字符串 | OSS 桶中的根路径 | |
endpoint | 字符串 | OSS 的 API 端点 | |
access_key_id | 字符串 | OSS 访问密钥 id | |
access_key_secret | 字符串 | OSS 秘密访问密钥 | |
Azblob | Azure Blob 存储选项,当 type="Azblob" 时有效 | ||
name | 字符串 | 存储提供商名字,默认为 Azblob | |
container | 字符串 | 容器名称 | |
root | 字符串 | 容器中的根路 径 | |
endpoint | 字符串 | Azure Blob 存储的 API 端点 | |
account_name | 字符串 | Azure Blob 存储的账户名 | |
account_key | 字符串 | 访问密钥 | |
sas_token | 字符串 | 共享访问签名 | |
Gsc | Google Cloud Storage 存储选项,当 type="Gsc" 时有效 | ||
name | 字符串 | 存储提供商名字,默认为 Gsc | |
root | 字符串 | Gsc 桶中的根路径 | |
bucket | 字符串 | Gsc 桶名称 | |
scope | 字符串 | Gsc 权限 | |
credential_path | 字符串 | Gsc 访问证书 | |
endpoint | 字符串 | GSC 的 API 端点 |
文件存储配置范例:
[storage]
type = "File"
data_home = "./greptimedb_data/"
s3 配置范例:
[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
存储服务的 http 客户端
[storage.http_client]
设置了向存储服务发送请求的 http 客户端的各种配置。
仅当存储服务类型是“S3”,“Oss”,“Azblob”或“Gcs”时生效。
Key | 类型 | 默认值 | 含义 |
---|---|---|---|
pool_max_idle_per_host | 数字 | 1024 | http 连接池中对每个 host 的最大空闲连接数。 |
connect_timeout | 字符串 | “30s”(30 秒) | http 客户端在进行连接时的超时 |
timeout | 字符串 | “30s”(30 秒) | 总的 http 请求超时,包括了从建立连接到接收完返回值为止的时间。也可视为一个请求从开始到结束的一个完整的截止时间。 |
pool_idle_timeout | 字符串 | “90s”(90 秒) | 对空闲连接进行保活( "keep-alive" )的超时。 |
存储引擎提供商
[[storage.providers]]
用来设置存储引擎的提供商列表。基于这个配置,你可以为每张表指定不同的存储引擎,具体请参考 create table:
# Allows using multiple storages
[[storage.providers]]
name = "S3"
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
[[storage.providers]]
name = "Gcs"
type = "Gcs"
bucket = "test_greptimedb"
root = "/greptimedb"
credential_path = "<gcs credential path>"
所有配置的这些存储引擎提供商的 name
都可以在创建表时用作 storage
选项。
对于同样提供商的存储,比如你希望使用不同 S3 bucket 来作为不同表的存储引擎,你就可以设置不同的 name
,并在创建表的时候指定 storage
选项。
对象存储缓存
在使用 AWS S3、阿里云 OSS 或 Azure Blob Storage 等远程存储服务时,查询过程中获取数据通常会很耗时,尤其在公有云环境。为了解决这个问题,GreptimeDB 提供了本地缓存机制来加速重复数据的访问。
从 v0.11 版本开始,GreptimeDB 默认启用远程对象存储的本地文件缓存。读取和写入缓存容量都设置为 5GiB
。
通常你无需专门配置缓存,除非你需要修改缓存的大小
[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
cache_capacity = "10GiB"
# cache_path = "/path/to/cache/home"
cache_path
指定存储缓存文件的本地目录,而 cache_capacity
则决定缓存目录中允许的最大文件总大小(以字节为单位)。你可以通过将 cache_path
设置为空字符串来禁用读取缓存。默认的缓存目录位于 {data_home}
目录下。我们建议你不用配置 cache_path
,因为数据库会自动设置该目录。
自 v0.12
之后,写入缓存不再是实验性的功能。你可以通过修改 mito 的配置调整缓存的大小
[[region_engine]]
[region_engine.mito]
write_cache_size = "10GiB"
更详细的信息请参阅性能调优技巧。
WAL 选项
GreptimeDB 支持两种 WAL 存储方式:本地 WAL 和 Remote WAL。关于它们的对比,请参见 WAL 概述。具体配置可参考 本地 WAL 和 Remote WAL 文档。
Logging 选项
frontend
、metasrv
、datanode
和 standalone
都可以在 [logging]
部分配置 log、tracing 相关参数:
[logging]
dir = "./greptimedb_data/logs"
level = "info"
enable_otlp_tracing = false
otlp_endpoint = "localhost:4317"
append_stdout = true
[logging.tracing_sample_ratio]
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
的选项。
部分常用的选项如下
[[region_engine]]
[region_engine.mito]
num_workers = 8
manifest_checkpoint_distance = 10
max_background_jobs = 4
auto_flush_interval = "1h"
global_write_buffer_size = "1GB"
global_write_buffer_reject_size = "2GB"
sst_meta_cache_size = "128MB"
vector_cache_size = "512MB"
page_cache_size = "512MB"
sst_write_buffer_size = "8MB"
scan_parallelism = 0
[region_engine.mito.index]
aux_path = ""
staging_size = "2GB"
metadata_cache_size = "64MiB"
content_cache_size = "128MiB"
content_cache_page_size = "64KiB"
[region_engine.mito.inverted_index]
create_on_flush = "auto"
create_on_compaction = "auto"
apply_on_query = "auto"
mem_threshold_on_create = "64M"
intermediate_path = ""
[region_engine.mito.memtable]
type = "time_series"
此外,mito
也提供了一个实验性质的 memtable。该 memtable 主要优化大量时间序列下的写入性能和内存占用。其查询性能可能会不如默认的 time_series
memtable。
[region_engine.mito.memtable]
type = "partition_tree"
index_max_keys_per_shard = 8192
data_freeze_threshold = 32768
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 | 字符串 | 128MB | SST 元数据缓存大小。设为 0 可关闭该缓存 默认为内存的 1/32,不超过 128MB |
vector_cache_size | 字符串 | 512MB | 内存向量和 arrow array 的缓存大小。设为 0 可关闭该缓存 默认为内存的 1/16,不超过 512MB |
page_cache_size | 字符串 | 512MB | SST 数据页的缓存。设为 0 可关闭该缓存 默认为内存的 1/8 |
selector_result_cache_size | 字符串 | 512MB | last_value() 等时间线检索结果的缓存。设为 0 可关闭该缓存默认为内存的 1/16,不超过 512MB |
sst_write_buffer_size | 字符串 | 8MB | SST 的写缓存大小 |
scan_parallelism | 整数 | 0 | 扫描并发度 (默认 1/4 CPU 核数) - 0 : 使用默认值 (1/4 CPU 核数)- 1 : 单线程扫描- n : 按并行度 n 扫描 |
index | -- | -- | Mito 引擎中索引的选项。 |
index.aux_path | 字符串 | "" | 文件系统中索引的辅助目录路径,用于存储创建索引的中间文件和搜索索引的暂存文件,默认为 {data_home}/index_intermediate 。为了向后兼容,该目录的默认名称为 index_intermediate 。此路径包含两个子目录:- __intm : 用于存储创建索引时使用的中间文件。- staging : 用于存储搜索索引时使用的暂存文件。 |
index.staging_size | 字符串 | 2GB | 暂存目录的最大容量。 |
index.metadata_cache_size | 字符串 | 64MiB | 索引元数据的缓存大小。 |
index.content_cache_size | 字符串 | 128MiB | 索引内容的缓存大小。 |
index.content_cache_page_size | 字符串 | 64KiB | 倒排索引内容缓存的页大小。 |
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_series | Memtable 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
选项适用于 datanode
和 frontend
模块,用于指定 Metasrv 的相关信息。
[meta_client]
metasrv_addrs = ["127.0.0.1:3002"]
timeout = "3s"
connect_timeout = "1s"
ddl_timeout = "10s"
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 本身。 有关如何使用此功能的说明,请参见 监控 指南。
[export_metrics]
# Whether to enable export_metrics
enable=true
# Export time interval
write_interval = "30s"
enable
: 是否启用导出指标功能,默认为false
。write_interval
: 指标导出时间间隔。