Commits

Anonymous committed 09e2ab4

docs for riak_stat

Comments (0)

Files changed (1)

src/riak_stat.erl

-%%%-------------------------------------------------------------------
-%%% File    : riak_stat.erl
-%%% Author  : Bryan Fink <bryan@basho.com>
-%%% Description : Stats aggregator for Riak.
-%%%
-%%% Created : 10 Nov 2009 by Bryan Fink <bryan@basho.com>
-%%%-------------------------------------------------------------------
+%% This file is provided to you under the Apache License,
+%% Version 2.0 (the "License"); you may not use this file
+%% except in compliance with the License.  You may obtain
+%% a copy of the License at
+
+%%   http://www.apache.org/licenses/LICENSE-2.0
+
+%% Unless required by applicable law or agreed to in writing,
+%% software distributed under the License is distributed on an
+%% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+%% KIND, either express or implied.  See the License for the
+%% specific language governing permissions and limitations
+%% under the License.    
+
+%% @doc riak_stat is a long-lived gen_server process for aggregating
+%%      stats about the Riak node on which it is runing.
+%%
+%%      Update each stat with the exported function update/1.  Modify
+%%      the internal function update/3 to add storage for new stats.
+%%
+%%      Get the latest aggregation of stats with the exported function
+%%      get_stats/0.  Modify the internal function produce_stats/1 to
+%%      change how stats are represented.
+%%
+%%      Current stats:
+%%<dl><dt>  vnode_gets
+%%</dt><dd> Total number of gets handled by all vnodes on this node
+%%          in the last minute.
+%%</dd><dd> update(vnode_get)
+%%
+%%</dd><dt> vnode_puts
+%%</dt><dd> Total number of puts handled by all vnodes on this node
+%%          in the last minute.
+%%</dd><dd> update(vnode_put)
+%%
+%%</dd><dt> node_gets
+%%</dt><dd> Number of gets coordinated by this node in the last
+%%          minute.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_get_fsm_time_mean
+%%</dt><dd> Mean time, in microseconds, between when a riak_get_fsm is
+%%          started and when it sends a reply to the client, for the
+%%          last minute.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_get_fsm_time_median
+%%</dt><dd> Median time, in microseconds, between when a riak_get_fsm
+%%          is started and when it sends a reply to the client, for
+%%          the last minute.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_get_fsm_time_95
+%%</dt><dd> Response time, in microseconds, met or beaten by 95% of
+%%          riak_get_fsm executions.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_get_fsm_time_99
+%%</dt><dd> Response time, in microseconds, met or beaten by 99% of
+%%          riak_get_fsm executions.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_get_fsm_time_100
+%%</dt><dd> Response time, in microseconds, met or beaten by 100% of
+%%          riak_get_fsm executions.
+%%</dd><dd> update({get_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_puts
+%%</dt><dd> Number of puts coordinated by this node in the last
+%%          minute.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_put_fsm_time_mean
+%%</dt><dd> Mean time, in microseconds, between when a riak_put_fsm is
+%%          started and when it sends a reply to the client, for the
+%%          last minute.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_put_fsm_time_median
+%%</dt><dd> Median time, in microseconds, between when a riak_put_fsm
+%%          is started and when it sends a reply to the client, for
+%%          the last minute.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_put_fsm_time_95
+%%</dt><dd> Response time, in microseconds, met or beaten by 95% of
+%%          riak_put_fsm executions.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_put_fsm_time_99
+%%</dt><dd> Response time, in microseconds, met or beaten by 99% of
+%%          riak_put_fsm executions.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> node_put_fsm_time_100
+%%</dt><dd> Response time, in microseconds, met or beaten by 100% of
+%%          riak_put_fsm executions.
+%%</dd><dd> update({put_fsm_time, Microseconds})
+%%
+%%</dd><dt> cpu_nprocs
+%%</dt><dd> Value returned by {@link cpu_sup:nprocs/0}.
+%%
+%%</dd><dt> cpu_avg1
+%%</dt><dd> Value returned by {@link cpu_sup:avg1/0}.
+%%
+%%</dd><dt> cpu_avg5
+%%</dt><dd> Value returned by {@link cpu_sup:avg5/0}.
+%%
+%%</dd><dt> cpu_avg15
+%%</dt><dd> Value returned by {@link cpu_sup:avg15/0}.
+%%
+%%</dd><dt> mem_total
+%%</dt><dd> The first element of the tuple returned by
+%%          {@link memsup:get_memory_data/0}.
+%%
+%%</dd><dt> mem_allocated
+%%</dt><dd> The second element of the tuple returned by
+%%          {@link memsup:get_memory_data/0}.
+%%
+%%</dd><dt> disk
+%%</dt><dd> Value returned by {@link disksup:get_disk_data/0}.
+%%</dd></dl>
 -module(riak_stat).
 
 -behaviour(gen_server2).
 -record(state,{vnode_gets,vnode_puts,
                get_fsm_time,put_fsm_time}).
 
-%%====================================================================
-%% API
-%%====================================================================
-%%--------------------------------------------------------------------
-%% Function: start_link() -> {ok,Pid} | ignore | {error,Error}
-%% Description: Starts the server
-%%--------------------------------------------------------------------
+%% @spec start_link() -> {ok,Pid} | ignore | {error,Error}
+%% @doc Start the server.  Also start the os_mon application, if it's
+%%      not already running.
 start_link() ->
     case application:start(os_mon) of
         ok -> ok;
     end,
     gen_server2:start_link({local, ?MODULE}, ?MODULE, [], []).
 
+%% @spec get_stats() -> proplist()
+%% @doc Get the current aggregation of stats.
 get_stats() ->
     gen_server2:call(?MODULE, get_stats).
 
+%% @spec update(term()) -> ok
+%% @doc Update the given stat.
 update(Stat) ->
     gen_server2:cast(?MODULE, {update, Stat, riak_util:moment()}).
 
-%%====================================================================
-%% gen_server callbacks
-%%====================================================================
-
-%%--------------------------------------------------------------------
-%% Function: init(Args) -> {ok, State} |
-%%                         {ok, State, Timeout} |
-%%                         ignore               |
-%%                         {stop, Reason}
-%% Description: Initiates the server
-%%--------------------------------------------------------------------
+%% @private
 init([]) ->
     {ok, #state{vnode_gets=spiraltime:fresh(),
                 vnode_puts=spiraltime:fresh(),
                 get_fsm_time=slide:fresh(),
                 put_fsm_time=slide:fresh()}}.
 
-%%--------------------------------------------------------------------
-%% Function: %% handle_call(Request, From, State) -> {reply, Reply, State} |
-%%                                      {reply, Reply, State, Timeout} |
-%%                                      {noreply, State} |
-%%                                      {noreply, State, Timeout} |
-%%                                      {stop, Reason, Reply, State} |
-%%                                      {stop, Reason, State}
-%% Description: Handling call messages
-%%--------------------------------------------------------------------
+%% @private
 handle_call(get_stats, _From, State) ->
     {reply, produce_stats(State), State};
 handle_call(_Request, _From, State) ->
     Reply = ok,
     {reply, Reply, State}.
 
-%%--------------------------------------------------------------------
-%% Function: handle_cast(Msg, State) -> {noreply, State} |
-%%                                      {noreply, State, Timeout} |
-%%                                      {stop, Reason, State}
-%% Description: Handling cast messages
-%%--------------------------------------------------------------------
+%% @private
 handle_cast({update, Stat, Moment}, State) ->
     {noreply, update(Stat, Moment, State)};
 handle_cast(_Msg, State) ->
     {noreply, State}.
 
-%%--------------------------------------------------------------------
-%% Function: handle_info(Info, State) -> {noreply, State} |
-%%                                       {noreply, State, Timeout} |
-%%                                       {stop, Reason, State}
-%% Description: Handling all non call/cast messages
-%%--------------------------------------------------------------------
+%% @private
 handle_info(_Info, State) ->
     {noreply, State}.
 
-%%--------------------------------------------------------------------
-%% Function: terminate(Reason, State) -> void()
-%% Description: This function is called by a gen_server when it is about to
-%% terminate. It should be the opposite of Module:init/1 and do any necessary
-%% cleaning up. When it returns, the gen_server terminates with Reason.
-%% The return value is ignored.
-%%--------------------------------------------------------------------
+%% @private
 terminate(_Reason, _State) ->
     ok.
 
-%%--------------------------------------------------------------------
-%% Func: code_change(OldVsn, State, Extra) -> {ok, NewState}
-%% Description: Convert process state when code is changed
-%%--------------------------------------------------------------------
+%% @private
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 
 %%% Internal functions
 %%--------------------------------------------------------------------
 
+%% @spec update(Stat::term(), integer(), state()) -> state()
+%% @doc Update the given stat in State, returning a new State.
 update(vnode_get, Moment, State) ->
     spiral_incr(#state.vnode_gets, Moment, State);
 update(vnode_put, Moment, State) ->
 update(_, _, State) ->
     State.
 
+%% @spec spiral_incr(integer(), integer(), state()) -> state()
+%% @doc Increment the value of a spiraltime structure at a given
+%%      position of the State tuple.
 spiral_incr(Elt, Moment, State) ->
     setelement(Elt, State,
                spiraltime:incr(1, Moment, element(Elt, State))).
 
+%% @spec slide_incr(integer(), term(), integer(), state()) -> state()
+%% @doc Update a slide structure at a given position in the
+%%      STate tuple.
 slide_incr(Elt, Reading, Moment, State) ->
     setelement(Elt, State,
                slide:update(element(Elt, State), Reading, Moment)).
 
+%% @spec produce_stats(state()) -> proplist()
+%% @doc Produce a proplist-formatted view of the current aggregation
+%%      of stats.
 produce_stats(State) ->
     Moment = spiraltime:n(),
     lists:append(
        mem_stats(),
        disk_stats()]).
 
+%% @spec spiral_minute(integer(), integer(), state()) -> integer()
+%% @doc Get the count of events in the last minute from the spiraltime
+%%      structure at the given element of the state tuple.
 spiral_minute(Moment, Elt, State) ->
     Up = spiraltime:incr(0, Moment, element(Elt, State)),
     {_,Count} = spiraltime:rep_minute(Up),
     Count.
 
+%% @spec slide_minute(integer(), integer(), state()) ->
+%%         {Count::integer(), Mean::ustat(),
+%%          {Median::ustat(), NinetyFive::ustat(),
+%%           NinetyNine::ustat(), Max::ustat()}}
+%% @type ustat() = undefined | number()
+%% @doc Get the Count of readings, the Mean of those readings, and the
+%%      Median, 95th percentile, 99th percentile, and Maximum readings
+%%      for the last minute from the slide structure at the given
+%%      element of the state tuple.
+%%      If Count is 0, then all other elements will be the atom
+%%      'undefined'.
 slide_minute(Moment, Elt, State) ->
     {Count, Mean} = slide:mean(element(Elt, State), Moment),
     {_, Nines} = slide:nines(element(Elt, State), Moment),
     {Count, Mean, Nines}.
 
+%% @spec vnode_stats(integer(), state()) -> proplist()
+%% @doc Get the vnode-sum stats proplist.
 vnode_stats(Moment, State) ->
     [{F, spiral_minute(Moment, Elt, State)}
      || {F, Elt} <- [{vnode_gets, #state.vnode_gets},
                      {vnode_puts, #state.vnode_puts}]].
 
+%% @spec node_stats(integer(), state()) -> proplist()
+%% @doc Get the node stats proplist.
 node_stats(Moment, State) ->
     {Gets, GetMean, {GetMedian, GetNF, GetNN, GetH}} =
         slide_minute(Moment, #state.get_fsm_time, State),
      {node_put_fsm_time_99, PutNN},
      {node_put_fsm_time_100, PutH}].
 
+%% @spec cpu_stats() -> proplist()
+%% @doc Get stats on the cpu, as given by the cpu_sup module
+%%      of the os_mon application.
 cpu_stats() ->
     [{cpu_nprocs, cpu_sup:nprocs()},
      {cpu_avg1, cpu_sup:avg1()},
      {cpu_avg5, cpu_sup:avg5()},
      {cpu_avg15, cpu_sup:avg15()}].
 
+%% @spec mem_stats() -> proplist()
+%% @doc Get stats on the memory, as given by the memsup module
+%%      of the os_mon application.
 mem_stats() ->
     {Total, Alloc, _} = memsup:get_memory_data(),
     [{mem_total, Total},
      {mem_allocated, Alloc}].
 
+%% @spec disk_stats() -> proplist()
+%% @doc Get stats on the disk, as given by the disksup module
+%%      of the os_mon application.
 disk_stats() ->
     [{disk, disksup:get_disk_data()}].
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.