Graphite_GraphBuilder Manual

A DSL and ini-based templating language to assist in constructing query strings for use with Graphite.

About

Graphite provides several interfaces for creating graphs and dashboards, but one of its powerful features is an API for generating graphs and retrieving raw data. This allows easy embedding of graphs in custom dashboards and other applications.

The process of describing complex graphs is however cumbersome at best. Graphite_GraphBuilder attempts to reduce the complexity of embedding Graphite graphs in PHP based applications by providing a fluent API for describing graphs and a facility for loading full or partial graph descriptions from ini files.

Examples

DSL Usage

  1. <?php
  2. /**
  3.  * Example usage of the DSL API to construct a graph of memory usage.
  4.  *
  5.  * Graph last 2 days of snmp collected memory utilization on host
  6.  * host.example.com.
  7.  *
  8.  * Show both free and used memory as stacked series after scaling values from
  9.  * bytes to megabytes (or more properly mebibytes).
  10.  *
  11.  * This example shows two different ways that the Graphite_Graph_Series DSL can
  12.  * be used to construct a target series for graphing.
  13.  */
  14.  
  15. require_once dirname(__FILE__'/../src/autoload.php';
  16.  
  17.     ->title('Memory')
  18.     ->vtitle('MiB')
  19.     ->width(800)
  20.     ->height(600)
  21.     ->bgcolor('white')
  22.     ->fgcolor('black')
  23.     ->from('-2days')
  24.     ->area('stacked')
  25.     ->prefix('collectd')
  26.     ->prefix('com.example.host')
  27.     ->prefix('snmp')
  28.     ->buildSeries('memory-free')
  29.         ->cactistyle()
  30.         ->color('green')
  31.         ->alias('Free')
  32.         ->scale((1024 1024)) // B to MiB
  33.         ->build()
  34.     ->buildSeries('memory-used')
  35.         ->scale((1024 1024))
  36.         ->color('blue')
  37.         ->alias('Used')
  38.         ->cactiStyle()
  39.         ->build()
  40.     ;
  41. ?>
  42. <!DOCTYPE html>
  43. <html>
  44.   <head>
  45.     <title>Memory on host.example.com</title>
  46.   </head>
  47.   <body>
  48.     <img src="http://graphite.example.com/render?<?php echo $g?>">
  49.   </body>
  50. </html>


Ini Usage

See Graphite_IniParser documentation for more details on the Mustache-like template expansion available within the ini files.

  1. Example ini configuration file supporting variable expansion.
  2. ;
  3. Variables are declared by surrounding any string with double braces{{VAR}}
  4. ;
  5. If no value is provided for a given variable at load time then the variable
  6. name itself will be outputThis feature can be used to provide default
  7. values.
  8. ;
  9. Use like:
  10. ;     ->prefix('com.example.host')
  11. ;     ->ini('interface.ini'array('IF' => 'Tunnel0''IF_DESC' => 'tu0'));
  12. echo $g;
  13.  
  14. ;; Graph settings
  15. any values outside of a section will be treated as settings for the graph as
  16. a whole
  17. title "Network Traffic {{IF_DESC}}"
  18. vtitle "Bits Per Sec"
  19. bgcolor "{{white}}"
  20. fgcolor "333333"
  21. line_mode "staircase"
  22.  
  23. [snmp]
  24. "prefix" is a partial path to prepend to another metric
  25. :is "prefix"
  26. prefix "collectd.snmp"
  27.  
  28. [interface-octets]
  29. :is "prefix"
  30. prefixes can use other prefixes if that makes keeping track easier
  31. :prefix "snmp"
  32. prefix "if_octets-{{IF}}"
  33.  
  34. [rx]
  35. prefix and section label define the metric to graph
  36. "collectd.snmp.if_octets-IF.rx" in this case
  37. :prefix "interface-octets"
  38. "counter" is an alias for the "nonNegativeDerivative" function
  39. counter true
  40. color "green"
  41. alias "Inbound"
  42.  
  43. [tx]
  44. :prefix "interface-octets"
  45. counter true
  46. scale = -1
  47. color "blue"
  48. alias "Outbound"
  49.  
  50. [95th_in-out]
  51. :prefix "interface-octets"
  52. "metric" is the data point under prefix to plot
  53. default is taken from the section label if not provided
  54. metric "*"
  55. "series" if provided must be a fully qualified graphite metric name
  56. it will not be expended with the default or explicit prefixes
  57. This can also be used for functions no yet supported by the API
  58. series movingMedian(foo.bar.baz5)
  59. counter true
  60. sum true
  61. npercentile 95
  62. color "red"
  63. dashed 10
  64. alias "95th Percentile in+out"


Download

Install with Composer

Graphite_GraphBuilder can be installed via {@link http://getcomposer.org/ Composer} as "{@link http://packagist.org/packages/graphite-graph/graphite-graph graphite-graph/graphite-graph}". The "dev-master" branch tracks stable development.

{
  "require": {
    "graphite-graph/graphite-graph": "dev-master"
  }
}
          


Get the Source

You can download this source in {@link https://github.com/bd808/graphite-graph-php/zipball/master zip} and tar formats.

You can also clone the project with Git by running:

          $ git clone git://github.com/bd808/graphite-graph-php
          


Contributing

Fork this project on GitHub : bd808/graphite-graph-php


Credits

Written by Bryan Davis with support from Keynetics.

Inspired by https://github.com/ripienaar/graphite-graph-dsl/