qgprofiler 0.1.14

qgprofiler
==============

QGProfiler 是一个简单的、用户控制的分析器。它与
其他分析器的不同之处在于它为程序员提供了对程序
各个部分的分析粒度的控制。
通过这样做，程序员可以保持低分析开销
（QGProfiler 旨在用于生产），同时仍然可以
看到程序中最重要的组件。


安装
--------------
使用 pip:

```sh
$ pip install qgprofiler
```

使用 setuptools:

``sh
$ git clone https://github.com/quantumgraph/qgprofiler
$ cd qgprofiler
$ python setup.py install
```

用法
--------------

该模块包含两个主要类 **QGProfiler** 和 **QGProfileAggregator**。下面描述和演示了它们的用法。

### QGProfiler：

QGProfiler 接受 2 个确定参数和 1 个可选参数：
- 程序名称（这将是堆栈的根名称）
- 带有路径的输出文件名（文件名应以 .json 或 .xml 结尾；如果路径未指定而不是在当前文件夹中生成具有给定文件名的文件）
- 一个可选的自定义属性，可以附加到节点并且可以更新 ```attributes={'somename': 'max', 'anothername': 'sum'}```（值可以是 'max' 或'sum'; QGProfiler 将执行计算以将值按其已定义的类型浮动到父节点；想法是使用此功能来计算内存，其中 max 和 no.of db 调用使用 sum 功能等on..)

这个类包含一些函数，可用于评估每个函数/模块所花费的时间以及调用相同函数/模块的次数。所用时间通过使用简单的
-```push('name')```（名称可以是函数名/db查询/类模块/等）确定，

- ```pop_all()``` 如果用户忘记完成推送的次数，它可以帮助用户弹出堆栈中的所有节点。在程序结束后，用户必须调用
- ```end()``` 来结束根程序时间，然后
- ```generate_file()``` 用于生成 xml 或 json 文件。默认情况下，QGProfiler 不会在 generate_file 获得最大精度时对值的数量进行四舍五入，您可以通过传递类似 ```generate_file(rounding_no=6)``` 或只是 ``generate_file(6)` 的参数来舍入这些值`。

下面显示了一个简短的示例，其中包含开始的输出：

```python
import time
from qgprofiler import QGProfiler

# 文件扩展名可以是 json 或 xml
qg_profiler = QGProfiler('program_root_name', '/path/to/your/file/filename.json', {'mem': 'max'}) # 程序启动
qg_profiler.push('test1') # test1 启动
time.sleep (0.1) # sleep 跟随某个程序执行
qg_profiler.update('mem', 10)# update 会更新节点的属性

qg_profiler.push('test11') # test11 开始时间.sleep
(0.5)
qg_profiler.pop () # test11 结束

qg_profiler.push('test12') # test12 开始time.sleep
(0.5)
qg_profiler.update('mem', 10)
qg_profiler.push('test121') # test121 开始 time.sleep
(1.0)
qg_profiler .update('mem', 30)
qg_profiler。pop() # test121 结束
qg_profiler.pop() # test12 结束

qg_profiler.push('test12') # test12 开始time.sleep
(0.5)
qg_profiler.pop() # test121 结束

qg_profiler.pop() # test1 结束

qg_profiler.push('test2') # test2 开始time.sleep
(0.1)
qg_profiler.update('mem', 10)
qg_profiler.pop() # test2 结束

qg_profiler.push('test2') # test2 开始time.sleep
(0.1)
qg_profiler.update('mem' , 20)
qg_profiler.pop() # test2 结束

qg_profiler.end() # 程序结束

qg_profiler.generate_file() # 将生成文件
```

这会生成一个包含 json
```json
{
“count”：1，
“name”：“program_root_name”，
“value”：2.808331，
“overhead”：3.5e-05，
“attributes”：{“mem”：{“type”：“max”，“value” : 30}},
"children": [{
"count": 1,
"name": "test1",
"value": 2.606762,
"overhead": 0.000131999999999999998,
"attributes": {"mem": {"type" : "max", "value": 30}},
"children": [{
"count": 1,
"name": "test11",
"value": 0.501054,
"overhead": 0.00031099999999999997，
“属性”：{“mem”：{“type”：“max”，“value”：0}}，
“children”：[]
}，{
“count”：2，
“name”：“test12” ,
“值”：2.0043670000000002，
“开销”：0.000463，
“属性”：{“mem”：{“type”：“max”，“value”：30}}，
“children”：[{
“count”：1，
“名称”：“test121”，
“值”：1.001872，
“开销”：0.000338，
“属性”：{“内存”：{“类型”：“最大值”，“值”：30}}，
“孩子”： []
}]
}]
}，{
“计数”：2，
“名称”：“test2”，
“值”：0.20094299999999998，
“开销”：0.000297，
“属性”：{“mem”：{“type”：“max”，“value”：20}}，
“children”：[]
}]
}
```

如果 .xml 作为文件名中的扩展名
```xml
<node name="program_root_name" value="2.808331" count="1" overhead="3.5e-05" attributes="mem:max:30"则生成的文件>
<node name="test1" value="2.606762" count="1" 开销="0.000132" attributes="mem:max:30">
<node name="test11" value="0.501054" count="1"开销="0.000311" 属性="mem:max:0"></node>
<节点名称="test12" value="2.004367" count="2" 开销="0.000463" 属性="mem:max:30" >
<节点名称=“test121”值=“1.001872”计数=“1”开销=0.000338" attributes="mem:max:30"></node>
</node>
</node>
<node name="test2" value="0.200943" count="2" overhead="0.000297" attributes="mem :max:20"></node>
</node>
```

### QGProfileAggregator:

QGProfileAggregator 接受 2 个参数：
- 输入文件路径（接受 unix 级别命令，例如：~/path/*.xml；接受给定路径中指定的所有 xml 文件）
- 输出文件名和路径（文件名应以.json 或 .xml 或 .html；如果未指定路径，则它在当前文件夹中生成具有给定文件名的路径）

此类包含一个函数``generate_file()``，它将聚合所有文件数据（.xml 或 .json 指定的任何一个，或者如果指定，它将获取所有文件*并仅处理 .xml / .json）。这将生成输出文件名中指定的 .xml / .json 文件。默认情况下，QGAggregator 将设置一个参数将值的数量舍入到 6 位到 generate_file，您可以通过将其作为参数传递来覆盖它，例如 ```generate_file(rounding_no=4)``` 或只是 ``generate_file(4) ```。如果生成的文件输出为 .json 或 .xml，则格式如上图所示。但是如果 .html 作为扩展名，它将使用 d3 生成一个火焰图，这需要有效的互联网连接来下载所需的 js 文件，该图看起来像


下面举例说明如何使用它：

``python
from qgprofiler import QGProfileAggregator

qg_profile_agg = QGProfileAggregator('/​​your /file/path/*.xml', '/path/to/your/file/filename.xml')
qg_profile_agg.generate_file() # 这会将所有 json/xml 文件聚合到 1 个文件中

```