409 lines
15 KiB
HTML
409 lines
15 KiB
HTML
<!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" />
|
||
|
||
<script src="dist/sidebar_items-75149ca71e.js"></script>
|
||
|
||
|
||
|
||
|
||
</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">
|
||
|
||
|
||
<a href="POAAgent.html" class="sidebar-projectLink">
|
||
<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>
|
||
<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
|
||
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: "localhost", 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, "data"}</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>
|
||
|
||
<p>In order to implement your Collector Plugin you must implement 4 functions.</p>
|
||
<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>
|
||
<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>
|
||
<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 "I am collecting data!"
|
||
{:transfer, "data retrieved", :no_state}
|
||
end
|
||
|
||
def metric_type do
|
||
"my_metrics_type"
|
||
end
|
||
|
||
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 don’t 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>
|
||
|
||
</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>
|
||
|
||
</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>
|
||
|
||
<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">
|
||
<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 don’t 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>
|
||
|
||
<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">
|
||
<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>
|
||
<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>
|
||
<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>
|
||
|
||
<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">
|
||
<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>
|
||
|