1 |
|
-module(mongoose_instrument). |
2 |
|
|
3 |
|
-behaviour(gen_server). |
4 |
|
|
5 |
|
%% API |
6 |
|
-export([config_spec/0, |
7 |
|
start_link/0, persist/0, |
8 |
|
set_up/1, set_up/3, |
9 |
|
tear_down/1, tear_down/2, |
10 |
|
span/4, span/5, |
11 |
|
execute/3]). |
12 |
|
|
13 |
|
%% gen_server callbacks |
14 |
|
-export([init/1, handle_call/3, handle_cast/2, code_change/3, handle_info/2, terminate/2]). |
15 |
|
|
16 |
|
-ignore_xref([start_link/0, set_up/3, tear_down/2, span/4, span/5, execute/3]). |
17 |
|
|
18 |
|
-include("mongoose.hrl"). |
19 |
|
-include("mongoose_config_spec.hrl"). |
20 |
|
|
21 |
|
-type event_name() :: atom(). |
22 |
|
-type labels() :: #{host_type => mongooseim:host_type()}. % to be extended |
23 |
|
-type metrics() :: #{atom() => spiral | histogram}. % to be extended |
24 |
|
-type measurements() :: #{atom() => integer() | atom() | binary()}. |
25 |
|
-type spec() :: {event_name(), labels(), config()}. |
26 |
|
-type config() :: #{metrics => metrics()}. % to be extended |
27 |
|
-type handler_fun() :: fun((event_name(), labels(), config(), measurements()) -> any()). |
28 |
|
-type handlers() :: {[handler_fun()], config()}. |
29 |
|
-type execution_time() :: integer(). |
30 |
|
-type measure_fun(Result) :: fun((execution_time(), Result) -> measurements()). |
31 |
|
|
32 |
|
-callback config_spec() -> mongoose_config_spec:config_section(). |
33 |
|
-callback set_up(event_name(), labels(), config()) -> boolean(). |
34 |
|
-callback handle_event(event_name(), labels(), config(), measurements()) -> any(). |
35 |
|
|
36 |
|
-optional_callbacks([config_spec/0]). |
37 |
|
|
38 |
|
-export_type([event_name/0, labels/0, config/0, measurements/0, spec/0, handlers/0]). |
39 |
|
|
40 |
|
%% API |
41 |
|
|
42 |
|
%% @doc Specifies the configuration of the instrumentation section |
43 |
|
-spec config_spec() -> mongoose_config_spec:config_section(). |
44 |
|
config_spec() -> |
45 |
53 |
Items = maps:from_list([{atom_to_binary(Key), config_spec(Key)} || Key <- all_handlers()]), |
46 |
53 |
#section{items = Items, wrap = global_config, include = always}. |
47 |
|
|
48 |
|
-spec start_link() -> gen_server:start_ret(). |
49 |
|
start_link() -> |
50 |
53 |
gen_server:start_link({local, ?MODULE}, ?MODULE, [], []). |
51 |
|
|
52 |
|
%% @doc Saves the state to a persistent term, improving performance of `execute' and `span'. |
53 |
|
%% On the other hand, future calls to `set_up' or `tear_down' will update the persistent term, |
54 |
|
%% which makes them less performant. |
55 |
|
%% You should call this function only once - after the initial setup, but before handling any load. |
56 |
|
-spec persist() -> ok. |
57 |
|
persist() -> |
58 |
53 |
gen_server:call(?MODULE, persist). |
59 |
|
|
60 |
|
%% @doc Sets up instrumentation for multiple events. |
61 |
|
%% @see set_up/3 |
62 |
|
-spec set_up([spec()]) -> ok. |
63 |
|
set_up(Specs) -> |
64 |
:-( |
lists:foreach(fun({EventName, Labels, Config}) -> set_up(EventName, Labels, Config) end, Specs). |
65 |
|
|
66 |
|
%% @doc Tears down instrumentation for multiple events. |
67 |
|
%% @see tear_down/2 |
68 |
|
-spec tear_down([spec()]) -> ok. |
69 |
|
tear_down(Specs) -> |
70 |
:-( |
lists:foreach(fun({EventName, Labels, _Config}) -> tear_down(EventName, Labels) end, Specs). |
71 |
|
|
72 |
|
%% @doc Sets up instrumentation for an event identified by `EventName' and `Labels' |
73 |
|
%% according to `Config'. Fails if the event is already registered, or if the keys of `Labels' |
74 |
|
%% are different than for already registered events with `EventName'. |
75 |
|
-spec set_up(event_name(), labels(), config()) -> ok. |
76 |
|
set_up(EventName, Labels, Config) -> |
77 |
:-( |
case gen_server:call(?MODULE, {set_up, EventName, Labels, Config}) of |
78 |
:-( |
ok -> ok; |
79 |
:-( |
{error, ErrorMap} -> error(ErrorMap) |
80 |
|
end. |
81 |
|
|
82 |
|
%% @doc Tears down instrumentation for an event identified by `EventName' and `Labels'. |
83 |
|
%% This operation is idempotent. |
84 |
|
-spec tear_down(event_name(), labels()) -> ok. |
85 |
|
tear_down(EventName, Labels) -> |
86 |
:-( |
gen_server:call(?MODULE, {tear_down, EventName, Labels}). |
87 |
|
|
88 |
|
%% @doc Calls `F', measuring its result with `MeasureF', and calls attached event handlers. |
89 |
|
%% @see span/5 |
90 |
|
-spec span(event_name(), labels(), fun(() -> Result), measure_fun(Result)) -> Result. |
91 |
|
span(EventName, Labels, F, MeasureF) -> |
92 |
:-( |
span(EventName, Labels, F, [], MeasureF). |
93 |
|
|
94 |
|
%% @doc Calls `F' with `Args', measuring its execution time. |
95 |
|
%% The time and the result are passed to `MeasureF', which returns measurements. |
96 |
|
%% The measurements are then passed to all handlers attached to |
97 |
|
%% the event identified by `EventName' and `Labels'. |
98 |
|
%% Fails without calling `F' if the event is not registered. |
99 |
|
-spec span(event_name(), labels(), fun((...) -> Result), list(), measure_fun(Result)) -> Result. |
100 |
|
span(EventName, Labels, F, Args, MeasureF) -> |
101 |
:-( |
Handlers = get_handlers(EventName, Labels), |
102 |
:-( |
{Time, Result} = timer:tc(F, Args), |
103 |
:-( |
handle_event(EventName, Labels, MeasureF(Time, Result), Handlers), |
104 |
:-( |
Result. |
105 |
|
|
106 |
|
%% @doc Executes all handlers attached to the event identified by `EventName' and `Labels', |
107 |
|
%% passing `Measurements' to them. Fails if the event is not registered. |
108 |
|
-spec execute(event_name(), labels(), measurements()) -> ok. |
109 |
|
execute(EventName, Labels, Measurements) -> |
110 |
:-( |
Handlers = get_handlers(EventName, Labels), |
111 |
:-( |
handle_event(EventName, Labels, Measurements, Handlers). |
112 |
|
|
113 |
|
%% gen_server callbacks |
114 |
|
|
115 |
|
-type state() :: #{event_name() => #{labels() => handlers()}}. |
116 |
|
|
117 |
|
-spec init([]) -> {ok, state()}. |
118 |
|
init([]) -> |
119 |
53 |
erlang:process_flag(trap_exit, true), % Make sure that terminate is called |
120 |
53 |
persistent_term:erase(?MODULE), % Prevent inconsistency when restarted after a kill |
121 |
53 |
{ok, #{}}. |
122 |
|
|
123 |
|
-spec handle_call(any(), gen_server:from(), state()) -> |
124 |
|
{reply, ok | {ok, handlers()} | {error, map()}, state()}. |
125 |
|
handle_call({set_up, EventName, Labels, Config}, _From, State) -> |
126 |
:-( |
case set_up_and_register(EventName, Labels, Config, State) of |
127 |
|
{error, _} = Error -> |
128 |
:-( |
{reply, Error, State}; |
129 |
|
NewState = #{} -> |
130 |
:-( |
update_if_persisted(State, NewState), |
131 |
:-( |
{reply, ok, NewState} |
132 |
|
end; |
133 |
|
handle_call({tear_down, EventName, Labels}, _From, State) -> |
134 |
:-( |
NewState = deregister(EventName, Labels, State), |
135 |
:-( |
update_if_persisted(State, NewState), |
136 |
:-( |
{reply, ok, NewState}; |
137 |
|
handle_call(persist, _From, State) -> |
138 |
53 |
persistent_term:put(?MODULE, State), |
139 |
53 |
{reply, ok, State}; |
140 |
|
handle_call({lookup, EventName, Labels}, _From, State) -> |
141 |
:-( |
{reply, lookup(EventName, Labels, State), State}; |
142 |
|
handle_call(Request, From, State) -> |
143 |
:-( |
?UNEXPECTED_CALL(Request, From), |
144 |
:-( |
{reply, {error, #{what => unexpected_call, request => Request}}, State}. |
145 |
|
|
146 |
|
-spec handle_cast(any(), state()) -> {noreply, state()}. |
147 |
|
handle_cast(Msg, State) -> |
148 |
:-( |
?UNEXPECTED_CAST(Msg), |
149 |
:-( |
{noreply, State}. |
150 |
|
|
151 |
|
-spec handle_info(any(), state()) -> {noreply, state()}. |
152 |
|
handle_info(Info, State) -> |
153 |
:-( |
?UNEXPECTED_INFO(Info), |
154 |
:-( |
{noreply, State}. |
155 |
|
|
156 |
|
-spec terminate(any(), state()) -> ok. |
157 |
|
terminate(_Reason, _State) -> |
158 |
54 |
persistent_term:erase(?MODULE), |
159 |
54 |
ok. |
160 |
|
|
161 |
|
-spec code_change(any(), state(), any()) -> {ok, state()}. |
162 |
|
code_change(_OldVsn, State, _Extra) -> |
163 |
:-( |
{ok, State}. |
164 |
|
|
165 |
|
%% Internal functions |
166 |
|
|
167 |
|
-spec update_if_persisted(state(), state()) -> ok. |
168 |
|
update_if_persisted(State, NewState) -> |
169 |
:-( |
try persistent_term:get(?MODULE) of |
170 |
:-( |
State -> persistent_term:put(?MODULE, NewState) |
171 |
|
catch |
172 |
:-( |
error:badarg -> ok |
173 |
|
end. |
174 |
|
|
175 |
|
-spec set_up_and_register(event_name(), labels(), config(), state()) -> state() | {error, map()}. |
176 |
|
set_up_and_register(EventName, Labels, Config, State) -> |
177 |
:-( |
LabelKeys = label_keys(Labels), |
178 |
:-( |
case State of |
179 |
|
#{EventName := #{Labels := _}} -> |
180 |
:-( |
{error, #{what => event_already_registered, |
181 |
|
event_name => EventName, labels => Labels}}; |
182 |
|
#{EventName := HandlerMap} -> |
183 |
:-( |
{ExistingLabels, _, _} = maps:next(maps:iterator(HandlerMap)), |
184 |
:-( |
case label_keys(ExistingLabels) of |
185 |
|
LabelKeys -> |
186 |
:-( |
Handlers = do_set_up(EventName, Labels, Config), |
187 |
:-( |
State#{EventName := HandlerMap#{Labels => Handlers}}; |
188 |
|
ExistingKeys -> |
189 |
:-( |
{error, #{what => inconsistent_labels, |
190 |
|
event_name => EventName, labels => Labels, |
191 |
|
existing_label_keys => ExistingKeys}} |
192 |
|
end; |
193 |
|
#{} -> |
194 |
:-( |
Handlers = do_set_up(EventName, Labels, Config), |
195 |
:-( |
State#{EventName => #{Labels => Handlers}} |
196 |
|
end. |
197 |
|
|
198 |
|
-spec do_set_up(event_name(), labels(), config()) -> handlers(). |
199 |
|
do_set_up(EventName, Labels, Config) -> |
200 |
:-( |
AllModules = handler_modules(), |
201 |
:-( |
UsedModules = lists:filter(fun(Mod) -> Mod:set_up(EventName, Labels, Config) end, AllModules), |
202 |
:-( |
{[fun Mod:handle_event/4 || Mod <- UsedModules], Config}. |
203 |
|
|
204 |
|
-spec deregister(event_name(), labels(), state()) -> state(). |
205 |
|
deregister(EventName, Labels, State) -> |
206 |
:-( |
case State of |
207 |
|
#{EventName := HandlerMap} -> |
208 |
:-( |
case maps:remove(Labels, HandlerMap) of |
209 |
|
Empty when Empty =:= #{} -> |
210 |
:-( |
maps:remove(EventName, State); |
211 |
|
NewHandlerMap -> |
212 |
:-( |
State#{EventName := NewHandlerMap} |
213 |
|
end; |
214 |
|
#{} -> |
215 |
:-( |
State |
216 |
|
end. |
217 |
|
|
218 |
|
-spec lookup(event_name(), labels()) -> {ok, handlers()} | {error, map()}. |
219 |
|
lookup(EventName, Labels) -> |
220 |
:-( |
try persistent_term:get(?MODULE) of |
221 |
|
State -> |
222 |
:-( |
lookup(EventName, Labels, State) |
223 |
|
catch |
224 |
|
%% Although persist/0 should be called before handling traffic, |
225 |
|
%% some instrumented events might happen before that, and they shouldn't fail. |
226 |
|
error:badarg -> |
227 |
:-( |
?LOG_INFO(#{what => mongoose_instrument_lookup_without_persistent_term, |
228 |
:-( |
event_name => EventName, labels => Labels}), |
229 |
:-( |
gen_server:call(?MODULE, {lookup, EventName, Labels}) |
230 |
|
end. |
231 |
|
|
232 |
|
-spec lookup(event_name(), labels(), state()) -> {ok, handlers()} | {error, map()}. |
233 |
|
lookup(EventName, Labels, State) -> |
234 |
:-( |
case State of |
235 |
|
#{EventName := #{Labels := Handlers}} -> |
236 |
:-( |
{ok, Handlers}; |
237 |
|
#{} -> |
238 |
:-( |
{error, #{what => event_not_registered, event_name => EventName, labels => Labels}} |
239 |
|
end. |
240 |
|
|
241 |
|
-spec label_keys(labels()) -> [atom()]. |
242 |
|
label_keys(Labels) -> |
243 |
:-( |
lists:sort(maps:keys(Labels)). |
244 |
|
|
245 |
|
-spec get_handlers(event_name(), labels()) -> handlers(). |
246 |
|
get_handlers(EventName, Labels) -> |
247 |
:-( |
case lookup(EventName, Labels) of |
248 |
:-( |
{ok, Handlers} -> Handlers; |
249 |
:-( |
{error, ErrorMap} -> error(ErrorMap) |
250 |
|
end. |
251 |
|
|
252 |
|
-spec handle_event(event_name(), labels(), measurements(), handlers()) -> ok. |
253 |
|
handle_event(Event, Labels, Measurements, {EventHandlers, Config}) -> |
254 |
:-( |
lists:foreach(fun(Handler) -> Handler(Event, Labels, Config, Measurements) end, EventHandlers). |
255 |
|
|
256 |
|
-spec handler_modules() -> [module()]. |
257 |
|
handler_modules() -> |
258 |
:-( |
[handler_module(Key) || Key <- maps:keys(mongoose_config:get_opt(instrumentation))]. |
259 |
|
|
260 |
|
-spec handler_module(atom()) -> binary(). |
261 |
|
handler_module(Key) -> |
262 |
159 |
list_to_existing_atom("mongoose_instrument_" ++ atom_to_list(Key)). |
263 |
|
|
264 |
|
-spec config_spec(atom()) -> mongoose_config_spec:config_section(). |
265 |
|
config_spec(Key) -> |
266 |
159 |
Module = handler_module(Key), |
267 |
159 |
case mongoose_lib:is_exported(Module, config_spec, 0) of |
268 |
53 |
true -> Module:config_spec(); |
269 |
106 |
false -> #section{} |
270 |
|
end. |
271 |
|
|
272 |
|
all_handlers() -> |
273 |
53 |
[prometheus, exometer, log]. |