poa-netstats-agent/doc/POAAgent.Plugins.Collector....

409 lines
15 KiB
HTML
Raw Permalink Normal View History

2018-07-06 13:59:27 -07:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.18.3">
<title>POAAgent.Plugins.Collector poa_agent v0.1.0</title>
<link rel="stylesheet" href="dist/app-480ffdc169.css" />
2018-08-22 10:49:21 -07:00
<script src="dist/sidebar_items-75149ca71e.js"></script>
2018-07-06 13:59:27 -07:00
</head>
<body data-type="modules">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
2018-08-20 17:35:56 -07:00
<a href="POAAgent.html" class="sidebar-projectLink">
2018-07-06 13:59:27 -07:00
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
poa_agent
</h1>
<h2 class="sidebar-projectVersion">
v0.1.0
</h2>
</div>
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">poa_agent v0.1.0</small>
POAAgent.Plugins.Collector <small>behaviour</small>
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent/plugins/collector.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>Defines a Collector Plugin.</p>
<p>A Collector plugin will run in an independent process and will run the <code class="inline">collect/1</code>
function in a given <code class="inline">frequency</code>.</p>
2018-08-20 17:35:56 -07:00
<p><a href="POAAgent.html"><code class="inline">POAAgent</code></a> app reads the Collectors configuration from the <code class="inline">config.exs</code> file when bootstrap and will create a
2018-07-06 13:59:27 -07:00
process per each one of them. That configuration is referenced by :collectors key.</p>
<pre><code class="elixir">config :poa_agent,
:collectors,
[
{name, module, frequency, label, args}
]</code></pre>
<p>for example</p>
<pre><code class="elixir">config :poa_agent,
:collectors,
[
{:my_collector, POAAgent.Plugins.Collectors.MyCollector, 5000, :my_metrics, [host: &quot;localhost&quot;, port: 1234]}
]</code></pre>
<p><code class="inline">name</code>, <code class="inline">module</code>, <code class="inline">frequency</code>, <code class="inline">label</code> and <code class="inline">args</code> must be defined in the configuration file.</p>
<ul>
<li><code class="inline">name</code>: Name for the new created process. Must be unique
</li>
<li><code class="inline">module</code>: Module which implements the Collector behaviour
</li>
<li><code class="inline">frequency</code>: time in milliseconds after which the function <code class="inline">collect/1</code> will be called
</li>
<li><code class="inline">label</code>: The data collected will be prefixed with this label. ie <code class="inline">{:eth_metrics, &quot;data&quot;}</code>
</li>
<li><code class="inline">args</code>: Initial args which will be passed to the <code class="inline">init_collector/1</code> function
</li>
</ul>
<p>In order to work properly we have to define in the configuration file also the mapping between the Collector
and the Transfers related with it. A <code class="inline">Transfer</code> is a Plugin process which transfers the data to outside the agent node
(external Database, Dashboard server…).</p>
<pre><code class="elixir">config :poa_agent,
:mappings,
[
{collector_name, [transfer_name1, transfer_name2]}
]</code></pre>
<p>for example</p>
<pre><code class="elixir">config :poa_agent,
:mappings,
[
{:my_collector, [:my_transfer]}
]</code></pre>
<h2 id="module-implementing-a-collector-plugin" class="section-heading">
<a href="#module-implementing-a-collector-plugin" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Implementing A Collector Plugin
</h2>
2018-08-22 10:49:21 -07:00
<p>In order to implement your Collector Plugin you must implement 4 functions.</p>
2018-07-06 13:59:27 -07:00
<ul>
<li><code class="inline">init_collector/1</code>: Called only once when the process starts
</li>
<li><code class="inline">collect/1</code>: This function is called periodically after <code class="inline">frequency</code> milliseconds. It is responsible
of retrieving the metrics
</li>
2018-08-22 10:49:21 -07:00
<li><code class="inline">metric_type/0</code>: This function must return the metric type in <code class="inline">string</code> format (i.e “ethereum_metric”)
</li>
2018-07-06 13:59:27 -07:00
<li><code class="inline">terminate/1</code>: Called just before stopping the process
</li>
</ul>
<p>This is a simple example of custom Collector Plugin</p>
<pre><code class="elixir">defmodule POAAgent.Plugins.Collectors.MyCollector do
use POAAgent.Plugins.Collector
def init_collector(args) do
{:ok, :no_state}
end
def collect(:no_state) do
IO.puts &quot;I am collecting data!&quot;
{:transfer, &quot;data retrieved&quot;, :no_state}
end
2018-08-22 10:49:21 -07:00
def metric_type do
&quot;my_metrics_type&quot;
end
2018-07-06 13:59:27 -07:00
def terminate(_state) do
:ok
end
end</code></pre>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-callbacks summary">
<h2>
<a href="#callbacks">Callbacks</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:collect/1">collect(state)</a>
</div>
<div class="summary-synopsis"><p>In this callback is where the metrics collection logic must be placed.
It must return <code class="inline">{:transfer, data, state}</code> where <code class="inline">data</code> is the retrieved metrics or
<code class="inline">{:notransfer, state}</code> when for some reason we dont want to send data to the transfer int
that moment</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:init_collector/1">init_collector(args)</a>
</div>
<div class="summary-synopsis"><p>A callback executed when the Collector Plugin starts.
The argument is retrieved from the configuration file when the Collector is defined
It can return <code class="inline">{:ok, state}</code>, that <code class="inline">state</code> will be keept as in <a href="https://hexdocs.pm/elixir/GenServer.html"><code class="inline">GenServer</code></a> and can be
retrieved in the <code class="inline">collect/1</code> function.
There are some cases where we want to send data to the transfer after initialize the
Collector, if that is the case you must return <code class="inline">{:transfer, data, state}</code> where the data is the
metrics we want to send to the transfer</p>
</div>
2018-08-22 10:49:21 -07:00
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:metric_type/0">metric_type()</a>
</div>
<div class="summary-synopsis"><p>This callback must return the metric type in <code class="inline">string</code> format. For example, if your collector is gathering metrics about
Ethereum you can use “ethereum_metric” here</p>
</div>
2018-07-06 13:59:27 -07:00
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#c:terminate/1">terminate(state)</a>
</div>
<div class="summary-synopsis"><p>This callback is called just before the Process goes down. This is a good place for closing connections</p>
</div>
</div>
</div>
</section>
<section id="callbacks" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#callbacks">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Callbacks
</h1>
<div class="detail" id="c:collect/1">
<div class="detail-header">
<a href="#c:collect/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">collect(state)</span>
2018-08-22 10:49:21 -07:00
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent/plugins/collector.ex#L106" class="view-source" rel="help" title="View Source">
2018-07-06 13:59:27 -07:00
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>collect(state :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()) ::
{:transfer, data :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>(), state :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()} | {:notransfer, state :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()}</pre>
</div>
</div>
<section class="docstring">
<p> In this callback is where the metrics collection logic must be placed.
It must return <code class="inline">{:transfer, data, state}</code> where <code class="inline">data</code> is the retrieved metrics or
<code class="inline">{:notransfer, state}</code> when for some reason we dont want to send data to the transfer int
that moment</p>
</section>
</div>
<div class="detail" id="c:init_collector/1">
<div class="detail-header">
<a href="#c:init_collector/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">init_collector(args)</span>
2018-08-22 10:49:21 -07:00
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent/plugins/collector.ex#L97" class="view-source" rel="help" title="View Source">
2018-07-06 13:59:27 -07:00
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>init_collector(args :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()) ::
{:ok, state :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()} | {:transfer, data :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>(), state :: <a href="https://hexdocs.pm/elixir/typespecs.html#basic-types">any</a>()}</pre>
</div>
</div>
<section class="docstring">
<p> A callback executed when the Collector Plugin starts.
The argument is retrieved from the configuration file when the Collector is defined
It can return <code class="inline">{:ok, state}</code>, that <code class="inline">state</code> will be keept as in <a href="https://hexdocs.pm/elixir/GenServer.html"><code class="inline">GenServer</code></a> and can be
retrieved in the <code class="inline">collect/1</code> function.
There are some cases where we want to send data to the transfer after initialize the
Collector, if that is the case you must return <code class="inline">{:transfer, data, state}</code> where the data is the
metrics we want to send to the transfer</p>
</section>
</div>
2018-08-22 10:49:21 -07:00
<div class="detail" id="c:metric_type/0">
<div class="detail-header">
<a href="#c:metric_type/0" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">metric_type()</span>
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent/plugins/collector.ex#L113" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>metric_type() :: <a href="https://hexdocs.pm/elixir/String.html#t:t/0">String.t</a>()</pre>
</div>
</div>
<section class="docstring">
<p>This callback must return the metric type in <code class="inline">string</code> format. For example, if your collector is gathering metrics about
Ethereum you can use “ethereum_metric” here.</p>
</section>
</div>
2018-07-06 13:59:27 -07:00
<div class="detail" id="c:terminate/1">
<div class="detail-header">
<a href="#c:terminate/1" class="detail-link" title="Link to this callback">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this callback</span>
</a>
<span class="signature">terminate(state)</span>
2018-08-22 10:49:21 -07:00
<a href="https://github.com/poanetwork/poa-netstats-agent/blob/v0.1.0/lib/poa_agent/plugins/collector.ex#L118" class="view-source" rel="help" title="View Source">
2018-07-06 13:59:27 -07:00
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<div class="specs">
<pre>terminate(state :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()) :: <a href="https://hexdocs.pm/elixir/typespecs.html#built-in-types">term</a>()</pre>
</div>
</div>
<section class="docstring">
<p> This callback is called just before the Process goes down. This is a good place for closing connections.</p>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" rel="help" target="_blank">ExDoc</a> (v0.18.3),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-9bd040e5e5.js"></script>
</body>
</html>