1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
======
API
======
There are a few things that you should know about API before using it.
Four ways to add a new trace point.
-----------------------------------
.. code-block:: python
from osprofiler import profiler
def some_func():
profiler.start("point_name", {"any_key": "with_any_value"})
# your code
profiler.stop({"any_info_about_point": "in_this_dict"})
@profiler.trace("point_name",
info={"any_info_about_point": "in_this_dict"},
hide_args=False)
def some_func2(*args, **kwargs):
# If you need to hide args in profile info, put hide_args=True
pass
def some_func3():
with profiler.Trace("point_name",
info={"any_key": "with_any_value"}):
# some code here
@profiler.trace_cls("point_name", info={}, hide_args=False,
trace_private=False)
class TracedClass(object):
def traced_method(self):
pass
def _traced_only_if_trace_private_true(self):
pass
How profiler works?
-------------------
* **@profiler.Trace()** and **profiler.trace()** are just syntax sugar,
that just calls **profiler.start()** & **profiler.stop()** methods.
* Every call of **profiler.start()** & **profiler.stop()** sends to
**collector** 1 message. It means that every trace point creates 2 records
in the collector. *(more about collector & records later)*
* Nested trace points are supported. The sample below produces 2 trace points:
.. code-block:: python
profiler.start("parent_point")
profiler.start("child_point")
profiler.stop()
profiler.stop()
The implementation is quite simple. Profiler has one stack that contains
ids of all trace points. E.g.:
.. code-block:: python
profiler.start("parent_point") # trace_stack.push(<new_uuid>)
# send to collector -> trace_stack[-2:]
profiler.start("parent_point") # trace_stack.push(<new_uuid>)
# send to collector -> trace_stack[-2:]
profiler.stop() # send to collector -> trace_stack[-2:]
# trace_stack.pop()
profiler.stop() # send to collector -> trace_stack[-2:]
# trace_stack.pop()
It's simple to build a tree of nested trace points, having
**(parent_id, point_id)** of all trace points.
Process of sending to collector.
--------------------------------
Trace points contain 2 messages (start and stop). Messages like below are
sent to a collector:
.. parsed-literal::
{
"name": <point_name>-(start|stop)
"base_id": <uuid>,
"parent_id": <uuid>,
"trace_id": <uuid>,
"info": <dict>
}
The fields are defined as the following:
* base_id - ``<uuid>`` that is equal for all trace points that belong
to one trace, this is done to simplify the process of retrieving
all trace points related to one trace from collector
* parent_id - ``<uuid>`` of parent trace point
* trace_id - ``<uuid>`` of current trace point
* info - the dictionary that contains user information passed when calling
profiler **start()** & **stop()** methods.
Setting up the collector.
-------------------------
The profiler doesn't include a trace point collector. The user/developer
should instead provide a method that sends messages to a collector. Let's
take a look at a trivial sample, where the collector is just a file:
.. code-block:: python
import json
from osprofiler import notifier
def send_info_to_file_collector(info, context=None):
with open("traces", "a") as f:
f.write(json.dumps(info))
notifier.set(send_info_to_file_collector)
So now on every **profiler.start()** and **profiler.stop()** call we will
write info about the trace point to the end of the **traces** file.
Initialization of profiler.
---------------------------
If profiler is not initialized, all calls to **profiler.start()** and
**profiler.stop()** will be ignored.
Initialization is a quite simple procedure.
.. code-block:: python
from osprofiler import profiler
profiler.init("SECRET_HMAC_KEY", base_id=<uuid>, parent_id=<uuid>)
``SECRET_HMAC_KEY`` - will be discussed later, because it's related to the
integration of OSprofiler & OpenStack.
**base_id** and **trace_id** will be used to initialize stack_trace in
profiler, e.g. ``stack_trace = [base_id, trace_id]``.
OSProfiler CLI.
---------------
To make it easier for end users to work with profiler from CLI, osprofiler
has entry point that allows them to retrieve information about traces and
present it in human readable from.
Available commands:
* Help message with all available commands and their arguments:
.. parsed-literal::
$ osprofiler -h/--help
* OSProfiler version:
.. parsed-literal::
$ osprofiler -v/--version
* Results of profiling can be obtained in JSON (option: ``--json``) and HTML
(option: ``--html``) formats:
.. parsed-literal::
$ osprofiler trace show <trace_id> --json/--html
hint: option ``--out`` will redirect result of ``osprofiler trace show``
in specified file:
.. parsed-literal::
$ osprofiler trace show <trace_id> --json/--html --out /path/to/file
* Using other storage drivers (e.g. MongoDB, ElasticSearch):
.. parsed-literal::
$ osprofiler trace show <trace_id> --connection-str=<URI> --json/--html
|
