[ Index ] [ Graphite classes ] [ Graphite elements ] [ All elements ]

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. $g = Graphite_GraphBuilder::builder()
  18.     ->title('Memory')
  19.     ->vtitle('MiB')
  20.     ->width(800)
  21.     ->height(600)
  22.     ->bgcolor('white')
  23.     ->fgcolor('black')
  24.     ->from('-2days')
  25.     ->area('stacked')
  26.     ->prefix('collectd')
  27.     ->prefix('com.example.host')
  28.     ->prefix('snmp')
  29.     ->buildSeries('memory-free')
  30.         ->cactistyle()
  31.         ->color('green')
  32.         ->alias('Free')
  33.         ->scale(1 / (1024 * 1024)) // B to MiB
  34.         ->build()
  35.     ->buildSeries('memory-used')
  36.         ->scale(1 / (1024 * 1024))
  37.         ->color('blue')
  38.         ->alias('Used')
  39.         ->cactiStyle()
  40.         ->build()
  41.     ;
  42. ?>
  43. <!DOCTYPE html>
  44. <html>
  45.   <head>
  46.     <title>Memory on host.example.com</title>
  47.   </head>
  48.   <body>
  49.     <img src="http://graphite.example.com/render?<?php echo $g; ?>">
  50.   </body>
  51. </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 output. This feature can be used to provide default
  7. ; values.
  8. ;
  9. ; Use like:
  10. ; $g = Graphite_GraphBuilder::build()
  11. ;     ->prefix('com.example.host')
  12. ;     ->ini('interface.ini', array('IF' => 'Tunnel0', 'IF_DESC' => 'tu0'));
  13. ; echo $g;
  14.  
  15. ;; Graph settings
  16. ; any values outside of a section will be treated as settings for the graph as
  17. ; a whole
  18. title = "Network Traffic {{IF_DESC}}"
  19. vtitle = "Bits Per Sec"
  20. bgcolor = "{{white}}"
  21. fgcolor = "333333"
  22. line_mode = "staircase"
  23.  
  24. [snmp]
  25. ; a "prefix" is a partial path to prepend to another metric
  26. :is = "prefix"
  27. prefix = "collectd.snmp"
  28.  
  29. [interface-octets]
  30. :is = "prefix"
  31. ; prefixes can use other prefixes if that makes keeping track easier
  32. :prefix = "snmp"
  33. prefix = "if_octets-{{IF}}"
  34.  
  35. [rx]
  36. ; prefix and section label define the metric to graph
  37. ; "collectd.snmp.if_octets-IF.rx" in this case
  38. :prefix = "interface-octets"
  39. ; "counter" is an alias for the "nonNegativeDerivative" function
  40. counter = true
  41. color = "green"
  42. alias = "Inbound"
  43.  
  44. [tx]
  45. :prefix = "interface-octets"
  46. counter = true
  47. scale = -1
  48. color = "blue"
  49. alias = "Outbound"
  50.  
  51. [95th_in-out]
  52. :prefix = "interface-octets"
  53. ; "metric" is the data point under prefix to plot
  54. ; default is taken from the section label if not provided
  55. metric = "*"
  56. ; "series" if provided must be a fully qualified graphite metric name
  57. ; it will not be expended with the default or explicit prefixes
  58. ; This can also be used for functions no yet supported by the API
  59. ; series = movingMedian(foo.bar.baz, 5)
  60. counter = true
  61. sum = true
  62. npercentile = 95
  63. color = "red"
  64. dashed = 10
  65. 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/