====== Perl class Grafana  ======



Perl class to provide management of Grafana dashboards and panels.

The class is used for Grafana __provisioning__. //It does not use the Grafana Web API// to directly modify Dashboards and Panels, put manages provisioning files for Grafana.

It is used by Stats4Lox for provisioning currently one default dashboard and panels of enabled statistics.

\\


====== Dashboard and Panel templates ======

These two functions allow to create a dashboard, and panels, from templates.

Every **Dashboard** manages an user-defined "uid" (a string, max 40 bytes) property to access the Dashboard by a unique key.\\
Every **Panel** has an "id" (an integer) property to directly access that Panel. 

The Grafana class creates and manages these uid's and id's automatically, and if you want to address dashboards and panels from otherwhere, you need to store these uid's and id's somewhere.

The usage of both functions is:

  * Call the function to get the template
  * Change properties of the template as you desire in your code
  * Call the save function to write the changes to disk.

**Be aware of arrays** in the templates! If you require to change properties of an array element, you need to access the array element by it's key (e.g. [0] ).

==== File locking ====

All files to be modified will be locked exclusively, also afterwards the save() function. To make sure to unlock the file, clear the object variable (e.g. ''%%undef $dashboard%%''). Templates (that are not modified) use a shared lock. All locked files also are unlocked if the object runs out of scope, or your program exits. 

==== Error handling ====

All functions ''%%die%%'' with wrong parameters or on any errors. There is no "silent ignore" of errors. Use ''%%eval%%'' to catch errors.

===== Define templates =====

You can define a **Dashboard template** directly in Grafana, by creating and customizing a dashboard. With //Settings / JSON Model// you can view a json file. Create a file out of this json. This is your Dashboard template. From this template, clear the "panels" array to look like ''%%"panels" : [],%%'' otherwise your Dashboard template will contain panels.  

To define a **Panel template**, create a Dashboard with a panel directly in Grafana.  Style and customize this panel as you require. Again, use //Settings / JSON model// to view the json of the Dashboard. Search the "panels" array, it will look like ''%%panels : [ { ...... } ]%%''. Copy the ''%%{ .... }%%'' part //without the array braces// and put this into a file. This is your Panel template.

===== DashboardFromTemplate =====

Creates/updates a Dashboard from a Dashboard template. Dashboards and Dashboard templates are stored in json files.

If the Dashboard exists and has Panels, the Panels will be preserved.

Returns: Dashboard uid

Syntax is:

''%%my $dashboard = DashboardFromTemplate Grafana( $dashboard_filename, $dashboardtemplate_filename );%%''

''%%$d%%''''%%ashboard->{title} = "My dashboard";%%''

''%%my $dashboard_uid = Grafana->save( $dashboard );%%''

==== Example ====

<code syntaxhighlighter-pre>
my $dashboard = DashboardFromTemplate Grafana( 
    "$Globals::s4l_provisioning_dir/dashboards/defaultDashboard.json",
    "$Globals::s4l_provisioning_dir/templates/template_defaultDashboard.json"
);

$dashboard->{title} = "LoxBerry Stats4Lox " . int(rand(100));
$dashboard->{links}[0]->{url} = "http://".lbhostname();
print $dashboard->{title} . "\n";
my $dashboard_uid = Grafana->save( $dashboard );
</code>



==== About Dashboard uid ====

  * If an existing  ''%%$dashboard_filename%%'' already has an uid, this uid is preserved.
  * If you change the uid with $dashboard->{uid}, your new uid is used
  * If a uid exists neither in ''%%$dashboard_filename %%''nor in your modification, a new uid is created.
  * save( $dashboard ) always responds with the uid of the written Dashboard

===== PanelFromTemplate =====

Creates a Panel from a Panel template, and adds/updates the Panel in the given Dashboard.

Returns: Panel id

Syntax is:

''%%my $panel = PanelFromTemplate Grafana( $dashboard_filename, $panel_template_filename );%%''

''%%$panel->{title} = "This is a panel" . int(rand(100));%%''

''%%my $panel_id = Grafana->save( $panel );%%''

Example:

<code syntaxhighlighter-pre>
my $panel = PanelFromTemplate Grafana( 
    "$Globals::s4l_provisioning_dir/dashboards/defaultDashboard.json",
    "$Globals::s4l_provisioning_dir/templates/template_panel_graph.json"
);

$panel->{title} = "Panel Title (Room/Category)" . int(rand(100));

my $panel_id = Grafana->save( $panel );
</code>



==== About Panel id ====

  * If you don't set the id by ''%%$panel->{id} = ....%%'' ,  a new panel will be created and added to the Dashboard. You will get a new panel id in the save() response.
  * If you set the id, and the id is not present in the current Dashboard, also the Panel will be added as new Panel to the Dashboard. 
  * If you set the id, and the id is an existing Panel in the Dashboard, the Panel will be updated at the same position of the panels array.
  * If a new Panel id needs to be created from the function, the new panel id is (highest existing panel id)+1.
  * Panel id's must be unique. Grafana will fail to show the Dashboard, if multiple panels with same id exists.
  * Panel id's must be defined. Grafana will fail to show the Dashboard, if a panel has no id. 

====== Managing Dashboards and Panels ======

This functions are used to directly modify Dashboards and it's Panels. 

===== deletePanelFromDashboard =====

Deletes all panels with a specific pnael id from the passed Dashboard file.

Allows a scalar or an arrayref for panel_id: ''%%$panel_id%%'' (as scalar) or ''%%[$panel_id1, $panel_id2,...]%%'' (as implicitely created arrayref), or ''%%\@panels_to_delete%%'' (using a predefined array and submit it's reference)

Returns: Count of deleted panels

The return should usually be 1 or 0 with one panel deleted. If the function is called with an array, will delete all these Panels and return the number of deletions, e.g. 3.

Syntax is:

''%%my $delcount = deletePanelFromDashboard Grafana( $dashboard_filename, $panel_id );%%''

''%%my $delcount = deletePanelFromDashboard Grafana( $dashboard_filename, [$panel_id1, $panel_id2] );%%''

===== deleteAllPanelsFromDashboard =====

Deletes all panels of the given Dashboard file.

Returns: nothing

Syntax is:

''%%deleteAllPanelsFromDashboard Grafana( $dashboard_filename );%%''

===== modifyDashboard =====

Modifies an existing Dashboard. You get the full Dashboard including it's Panels, therefore your also can modify the Panels. For modifying the Panels, you might prefer the ''%%modifyPanel%%'' function, as the function manages the panel id's.

Returns: Dashboard uid

If the Dashboard currently has no uid, and you've not set an uid, the function will create an uid. 

''%%my $dashboard = modifyDashboard Grafana( $dashboard_filename );%%''

''%%$d%%''''%%ashboard->{title} = "My dashboard";%%''

''%%my $dashboard_uid = Grafana->save( $dashboard );%%''

===== modifyPanel =====

Modifies an existing Panel in the given Dashboard file. The Panel is identified by your given Panel id.

Returns: Panel id

''%%my $panel = modifyPanel Grafana( $dashboard_filename, $panel_id );%%''

''%%$panel->{title} = "This is a panel" . int(rand(100));%%''

''%%my $panel_id = Grafana->save( $panel );%%''

Modifying the id is possible but dangerous. You need to keep panel id's unique, otherwise Grafana fails loading the Dashboard. On save, the Panel will be updated with the changed id. The position in the Dashboard will be preserved.

\\