文章目录
- 1. 前言
- 2. 工具使用细节
- 3. 如何制作一个自己的python-package
- 3.1 项目配置文件
- 3.1.1 LICENSE 文件
- 3.2 README.md 文件
- 3.3 pyproject.toml 文件
- 3.4 setup.cfg文件
- 3.5 setup.py文件
- 3.2 打包
- 3.2.1 安装打包工具
- 3.2.2 打包
- 3.3 打包好的文件上传pypi
- 3.3.1 注册自己的pypi账户
- 3.3.2 添加项目token
- 3.3.3 发布打包文件
- 3.4 测试发布的包
1. 前言
本节提供一个rocksdb的日志分析工具，能够在db机器根据rocskdb的option文件和log文件 分析当前rocksdb运行过程中是否存在稳定性和性能问题，并给出对应的参数优化或者问题解决的建议。比如：当前db中存在write-stall问题，而且实际过程中write-stall可能的问题源头有很多个，像L0文件个数过多就是因为L0->L1 compaction太慢 或者说 compaction线程数太少， 这个工具能够分析出其中存在问题根源，并提出对应的参数优化，像增大compaction线程数等等。
类似如下输出：
# 规则文件
Rule: stall-too-many-L0
# 日志异常信息
LogCondition: stall-too-many-L0 regex: Stalling writes because we have \d+ level-0 files
# 建议修改的参数
Suggestion: inc-max-subcompactions option : DBOptions.max_subcompactions action : increase
Suggestion: inc-max-bg-compactions option : DBOptions.max_background_compactions action : increase suggested_values : ['2']
Suggestion: inc-write-buffer-size option : CFOptions.write_buffer_size action : increase
Suggestion: dec-max-bytes-for-level-base option : CFOptions.max_bytes_for_level_base action : decrease
Suggestion: inc-l0-slowdown-writes-trigger option : CFOptions.level0_slowdown_writes_trigger action : increase
scope: col_fam:
{'default'}
2. 工具使用细节
工具本身是rocksdb 社区提供的，为了方便本地使用，我将其封装成了python package 形态，可以直接通过本地pip安装，也支持指定不同的国内源安装，都没有问题。
- 下载
pip3 install Adviser-Rocksdb - 规则文件保存到服务器上： rules.ini
- 执行：
python3 -m advisor.rule_parser_example \
# 指定保存的规则文件
--rules_spec=advisor/rules.ini \
# 指定db目录下的option文件
--rocksdb_options=OPTIONS-000005 \
# 指定db目录下的日志文件
--log_files_path_prefix=tests/input_files/LOG-0 \
# 指定db-log文件内容的statistics打印频率（这里随意设置并没有什么问题，但需要有这个参数）
--stats_dump_period_sec=20
- 更多命令细节
python3 -m advisor.rule_parser_example --help # 查看工具帮助信息
本质上这个工具就像是一个规则引擎，通过预先设定好的规则rules.ini文件来从rocksdb-log中进行匹配，输出最后的匹配结果，当然，我们也可以向rules.ini文件中按照格式增加适合自己业务的匹配规则即可。
比如发现如下参数不合理的问题，write_buffer_size 过小会出现频繁的flush，且level0文件因为小而数量增长快，调度的L0->L1 的compaction也会很频繁，这个代价就比较大。
[CFOptions "col_fam_A"]
max_bytes_for_level_base=268435456
level0_file_num_compaction_trigger=5
write_buffer_size=1024000
通过日志分析工具，能够给出一个合理的参数优化方案：调大write-buffer-size 并适度缩小max_bytes_for_level_base来保证小sst文件的LSM-tree形态。
Rule: small-l0-files
OptionCondition: small-l0-files options: ['CFOptions.max_bytes_for_level_base', 'CFOptions.level0_file_num_compaction_trigger', 'CFOptions.write_buffer_size'] expression: int(options[0])>(10*int(options[1])*int(options[2])) trigger: {'default': ['268435456', '4', '4194000'], 'col_fam_A': ['268435456', '5', '1024000']}
Suggestion: dec-max-bytes-for-level-base option : CFOptions.max_bytes_for_level_base action : decrease
Suggestion: inc-write-buffer-size option : CFOptions.write_buffer_size action : increase
scope: col_fam:
{'col_fam_A', 'default'}
相关的日志分析工具源代码见https://github.com/BaronStack/Rocksdb-Adviser
这里顺带提一下如何制作一个自己的python-package：
3. 如何制作一个自己的python-package
下文中提到的配置文件均可以参考：
https://github.com/BaronStack/Rocksdb-Adviser 中的内容。
如果你想做测试，可以直接按照如下步骤来尝试。
3.1 项目配置文件
创建目录packaging，并创建如下文件，可以先让其中文件内容为空，后面会补充。
> tree .
.
├── LICENSE # 本package 遵守的开源协议
├── README.md # 你的package 描述文档,告诉别人如何使用这个package
├── example_pkg # package 源代码目录
│ └── __init__.py # 该文件支持将你的源代码以package 形式导入
├── pyproject.toml # 打包当前package是需要增加的依赖库版本
├── setup.cfg # 静态打包，类似静态库，相关依赖/需要安装内容在安装之前就已经确定，并打包好，一般优先使用.cfg来打包
├── setup.py # 动态打包，通过setuptool工具，在安装的时候才去安装对应的依赖
└── tests # 源代码的测试文件目录
3.1.1 LICENSE 文件
可以在 https://choosealicense.com/ 找到协议内容，比如尊崇的是MIT开源协议:
Copyright (c) 2018 The Python Packaging Authority
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
3.2 README.md 文件
这里不多说，就是针对你个人package的使用描述文件.
# TEST
This is a packaging test directory.
3.3 pyproject.toml 文件
指定打包时 源代码所需要的依赖库，这个文件默认可以不需要添加，一般认为这个文件存在，是因为你需要依赖wheel。
如果不依赖wheel，则可以不需要这个文件
[build-system]
requires = [
"setuptools>=42",
"wheel"
]
build-backend = "setuptools.build_meta"
3.4 setup.cfg文件
这个文件在打包之前就能够明确指定当前package的信息，比较准确且容易发现配置内容的问题，也是官方推荐的打包方式。
一般内容如下，可以直接使用
[metadata]
# 指定你想要 打包的 包名称 ‘packaging-testing’
name = example-pkg-YOUR-USERNAME-HERE
# 包的版本
version = 0.0.1
# 开发者
author = Example Author
# 开发者邮件
author_email = [email protected]
# 包的简单功能描述
description = A small example package
# 指定详细描述 的文件，默认是README.md
long_description = file: README.md
# 指定详细描述的的文本编辑器 markdown，可能还有富文本编辑器
long_description_content_type = text/markdown
# 指定维护package的github地址，可选
url = https://github.com/pypa/sampleproject
# 指定package的issue地址，可选
project_urls =
Bug Tracker = https://github.com/pypa/sampleproject/issues
# 一些版本 - 协议信息
classifiers =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
# python版本
[options]
packages = find:
python_requires = >=3.6
如果setup.py文件存在，也就是后面说的这个文件存在，则当前 setup.cfg不会生效，默认以setup.py为主，为了保证安装时增加的setuptools的扩展插件能够被正确安装。
setup.py和setup.cfg 两个文件选择一个就可以，官方推荐setup.cfg来打包
3.5 setup.py文件
基本和setup.cfg配置项一样，只是启动方式不同，通过pip在各自本地安装时通过setuptool安装一些依赖。
import setuptools
with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()
setuptools.setup(
name="example-pkg-YOUR-USERNAME-HERE", # Replace with your own username
version="0.0.1",
author="Example Author",
author_email="[email protected]",
description="A small example package",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/pypa/sampleproject",
project_urls={
"Bug Tracker": "https://github.com/pypa/sampleproject/issues",
},
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
packages=setuptools.find_packages(),
python_requires=">=3.6",
)
3.2 打包
3.2.1 安装打包工具
python3 -m pip install --upgrade build
3.2.2 打包
python3 -m build
打包完成会在当前目录下生成一些打包目录，其中dist目录是打包完成的文件:
> tree .
.
├── BaronStack.egg-info
│ ├── PKG-INFO
│ ├── SOURCES.txt
│ ├── dependency_links.txt
│ └── top_level.txt
├── LICENSE
├── README.md
├── build
│ └── bdist.macosx-11-x86_64
├── dist
│ ├── BaronStack-0.0.1-py3-none-any.whl
│ └── BaronStack-0.0.1.tar.gz
├── example_pkg
│ └── __init__.py
├── setup.cfg
├── setup.py
└── tests
3.3 打包好的文件上传pypi
我们需要将打包好的文件上传到https://pypi.org/中，才能够被全世界的其他想要使用的伙伴下载下来。
3.3.1 注册自己的pypi账户
这个不多说，直接注册完了
3.3.2 添加项目token
这一步主要是为了保证本地刚才构建好的python package 能够免密上传到自己的账户下。
- 我的账户已经注册完了,选择
accont setting - 添加token
- 设置token名称， 设置token范围，第一次创建的话需要设置为适配所有项目，保证对当前自己想要上传的项目生效
- 将生成的token添加到自己的本地
~/.pypirc文件中
3.3.3 发布打包文件
- 安装发布工具 (只需安装一次，后续可以直接执行第二个命令)
python3 -m pip install --user --upgrade twine - 发布
python3 -m twine upload dist/*发布成功后会出现：
Uploading distributions to https://test.pypi.org/legacy/
Uploading example_pkg_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100%|█████████████████████| 4.65k/4.65k [00:01<00:00, 2.88kB/s]
Uploading example_pkg_YOUR_USERNAME_HERE-0.0.1.tar.gz
100%|█████████████████████| 4.25k/4.25k [00:01<00:00, 3.05kB/s]
这个时候你去https://pypi.org/manage/projects/就能够看到自己的项目了。
3.4 测试发布的包
可以本地直接通过pip install package-name ，然后就可以直接import 对应的package，或者python3 -m package xxx 来调用包内的函数。
如果你本地pip配置的是国内源，立即执行pip3 install package 会失败，这一些国内源会每隔一段时间从pypi同步包。