1================== 2The Render URL API 3================== 4 5The graphite webapp provides a ``/render`` endpoint for generating graphs 6and retrieving raw data. This endpoint accepts various arguments via query 7string parameters. These parameters are separated by an ampersand (``&``) 8and are supplied in the format: 9 10.. code-block:: none 11 12 &name=value 13 14To verify that the api is running and able to generate images, open 15``http://GRAPHITE_HOST:GRAPHITE_PORT/render`` in a browser. The api should 16return a simple 330x250 image with the text "No Data". 17 18Once the api is running and you've begun 19:doc:`feeding data into carbon </feeding-carbon>`, use the parameters below to 20customize your graphs and pull out raw data. For example: 21 22.. code-block:: none 23 24 # single server load on large graph 25 http://graphite/render?target=server.web1.load&height=800&width=600 26 27 # average load across web machines over last 12 hours 28 http://graphite/render?target=averageSeries(server.web*.load)&from=-12hours 29 30 # number of registered users over past day as raw json data 31 http://graphite/render?target=app.numUsers&format=json 32 33 # rate of new signups per minute 34 http://graphite/render?target=summarize(derivative(app.numUsers),"1min")&title=New_Users_Per_Minute 35 36.. note:: 37 38 Most of the functions and parameters are case sensitive. 39 For example ``&linewidth=2`` will fail silently. 40 The correct parameter in this case is ``&lineWidth=2`` 41 42Graphing Metrics 43================ 44 45To begin graphing specific metrics, pass one or more target_ parameters 46and specify a time window for the graph via `from / until`_. 47 48target 49------ 50 51The ``target`` parameter specifies a path identifying one or several metrics, optionally with functions acting on 52those metrics. Paths are documented below, while functions are listed on the :doc:`functions` page. 53 54.. _paths-and-wildcards: 55 56Paths and Wildcards 57^^^^^^^^^^^^^^^^^^^ 58 59Metric paths show the "." separated path from the root of the metrics tree (often starting with ``servers``) to 60a metric, for example ``servers.ix02ehssvc04v.cpu.total.user``. 61 62Paths also support the following wildcards, which allows you to identify more than one metric in a single path. 63 64*Asterisk* 65 The asterisk (``*``) matches zero or more characters. It is non-greedy, so you can have more 66 than one within a single path element. 67 68 Example: ``servers.ix*ehssvc*v.cpu.total.*`` will return all total CPU metrics for all servers matching the 69 given name pattern. 70 71*Character list or range* 72 Characters in square brackets (``[...]``) specify a single character position in the path string, and match if the character 73 in that position matches one of the characters in the list or range. 74 75 A character range is indicated by 2 characters separated by a dash (``-``), and means that any character between 76 those 2 characters (inclusive) will match. More than one range can be included within the square brackets, e.g. 77 ``foo[a-z0-9]bar`` will match ``foopbar``, ``foo7bar`` etc.. 78 79 If the characters cannot be read as a range, they are treated as a list - any character in the list will match, 80 e.g. ``foo[bc]ar`` will match ``foobar`` and ``foocar``. If you want to include a dash (``-``) in your list, 81 put it at the beginning or end, so it's not interpreted as a range. 82 83*Value list* 84 Comma-separated values within curly braces (``{foo,bar,...}``) are treated as value lists, and match if any of the 85 values matches the current point in the path. For example, ``servers.ix01ehssvc04v.cpu.total.{user,system,iowait}`` 86 will match the user, system and I/O wait total CPU metrics for the specified server. 87 88.. note:: 89 All wildcards apply only within a single path element. In other words, they do not include or cross dots (``.``). 90 Therefore, ``servers.*`` will not match ``servers.ix02ehssvc04v.cpu.total.user``, while ``servers.*.*.*.*`` will. 91 92Tagged Series 93^^^^^^^^^^^^^ 94 95When querying tagged series, we start with the `seriesByTag <functions.html#graphite.render.functions.seriesByTag>`_ function: 96 97.. code-block:: none 98 99 # find all series that have tag1 set to value1 100 seriesByTag('tag1=value1') 101 102See :ref:`querying tagged series <querying-tagged-series>` for more detail on using `seriesByTag <functions.html#graphite.render.functions.seriesByTag>`_. 103 104Examples 105^^^^^^^^ 106 107This will draw one or more metrics 108 109Example: 110 111.. code-block:: none 112 113 &target=company.server05.applicationInstance04.requestsHandled 114 (draws one metric) 115 116Let's say there are 4 identical application instances running on each server. 117 118.. code-block:: none 119 120 &target=company.server05.applicationInstance*.requestsHandled 121 (draws 4 metrics / lines) 122 123Now let's say you have 10 servers. 124 125.. code-block:: none 126 127 &target=company.server*.applicationInstance*.requestsHandled 128 (draws 40 metrics / lines) 129 130You can also run any number of :doc:`functions </functions>` on the various metrics before graphing. 131 132.. code-block:: none 133 134 &target=averageSeries(company.server*.applicationInstance.requestsHandled) 135 (draws 1 aggregate line) 136 137Multiple function calls can be chained together either by nesting them or by piping the result into another function (it will be passed to the piped function as its first parameter): 138 139.. code-block:: none 140 141 &target=movingAverage(aliasByNode(company.server*.applicationInstance.requestsHandled,1),"5min") 142 &target=aliasByNode(company.server*.applicationInstance.requestsHandled,1)|movingAverage("5min") 143 &target=company.server*.applicationInstance.requestsHandled|aliasByNode(1)|movingAverage("5min") 144 &target=movingAverage(company.server*.applicationInstance.requestsHandled|aliasByNode(1),"5min") 145 (these are all equivalent) 146 147The target param can also be repeated to graph multiple related metrics. 148 149.. code-block:: none 150 151 &target=company.server1.loadAvg&target=company.server1.memUsage 152 153.. note:: 154 If more than 10 metrics are drawn the legend is no longer displayed. See the hideLegend_ parameter for details. 155 156from / until 157------------ 158 159These are optional parameters that specify the relative or absolute time period to graph. 160``from`` specifies the beginning, ``until`` specifies the end. 161If ``from`` is omitted, it defaults to 24 hours ago. 162If ``until`` is omitted, it defaults to the current time (now). 163 164There are multiple formats for these functions: 165 166.. code-block:: none 167 168 &from=-RELATIVE_TIME 169 &from=ABSOLUTE_TIME 170 171RELATIVE_TIME is a length of time since the current time. 172It is always preceded by a minus sign ( - ) and followed by a unit of time. 173Valid units of time: 174 175============== =============== 176Abbreviation Unit 177============== =============== 178s Seconds 179min Minutes 180h Hours 181d Days 182w Weeks 183mon 30 Days (month) 184y 365 Days (year) 185============== =============== 186 187ABSOLUTE_TIME is in the format HH:MM_YYYYMMDD, YYYYMMDD, MM/DD/YY, or any other 188``at(1)``-compatible time format. 189 190============= ======= 191Abbreviation Meaning 192============= ======= 193HH Hours, in 24h clock format. Times before 12PM must include leading zeroes. 194MM Minutes 195YYYY 4 Digit Year. 196MM Numeric month representation with leading zero 197DD Day of month with leading zero 198============= ======= 199 200``&from`` and ``&until`` can mix absolute and relative time if desired. 201 202Examples: 203 204.. code-block:: none 205 206 &from=-8d&until=-7d 207 (shows same day last week) 208 209 &from=04:00_20110501&until=16:00_20110501 210 (shows 4AM-4PM on May 1st, 2011) 211 212 &from=20091201&until=20091231 213 (shows December 2009) 214 215 &from=noon+yesterday 216 (shows data since 12:00pm on the previous day) 217 218 &from=6pm+today 219 (shows data since 6:00pm on the same day) 220 221 &from=january+1 222 (shows data since the beginning of the current year) 223 224 &from=monday 225 (show data since the previous monday) 226 227template 228-------- 229 230The ``target`` metrics can use a special ``template`` function which 231allows the metric paths to contain variables. Values for these variables 232can be provided via the ``template`` query parameter. 233 234Examples 235^^^^^^^^ 236 237Example: 238 239.. code-block:: none 240 241 &target=template(hosts.$hostname.cpu)&template[hostname]=worker1 242 243Default values for the template variables can also be provided: 244 245.. code-block:: none 246 247 &target=template(hosts.$hostname.cpu, hostname="worker1") 248 249Positional arguments can be used instead of named ones: 250 251.. code-block:: none 252 253 &target=template(hosts.$1.cpu, "worker1") 254 &target=template(hosts.$1.cpu, "worker1")&template[1]=worker* 255 256In addition to path substitution, variables can be used for numeric and string literals: 257 258.. code-block:: none 259 260 &target=template(constantLine($number))&template[number]=123 261 &target=template(sinFunction($name))&template[name]=nameOfMySineWaveMetric 262 263 264Data Display Formats 265==================== 266 267Along with rendering an image, the api can also generate 268`SVG <http://www.w3.org/Graphics/SVG/>`_ with embedded metadata, PDF, or return the raw data in various 269formats for external graphing, analysis or monitoring. 270 271format 272------ 273 274Controls the format of data returned. 275Affects all ``&targets`` passed in the URL. 276 277Examples: 278 279.. code-block:: none 280 281 &format=png 282 &format=raw 283 &format=csv 284 &format=json 285 &format=svg 286 &format=pdf 287 &format=dygraph 288 &format=rickshaw 289 290png 291^^^ 292Renders the graph as a PNG image of size determined by width_ and height_ 293 294raw 295^^^ 296Renders the data in a custom line-delimited format. Targets are output one per line and are of the format 297``<target name>,<start timestamp>,<end timestamp>,<series step>|[data]*`` 298 299.. code-block:: none 300 301 entries,1311836008,1311836013,1|1.0,2.0,3.0,5.0,6.0 302 303csv 304^^^ 305Renders the data in a CSV format suitable for import into a spreadsheet or for processing in a script 306 307.. code-block:: none 308 309 entries,2011-07-28 01:53:28,1.0 310 entries,2011-07-28 01:53:29,2.0 311 entries,2011-07-28 01:53:30,3.0 312 entries,2011-07-28 01:53:31,5.0 313 entries,2011-07-28 01:53:32,6.0 314 315json 316^^^^ 317Renders the data as a json object. The jsonp_ option can be used to wrap this data in a named call 318for cross-domain access 319 320.. code-block:: none 321 322 [{ 323 "target": "entries", 324 "datapoints": [ 325 [1.0, 1311836008], 326 [2.0, 1311836009], 327 [3.0, 1311836010], 328 [5.0, 1311836011], 329 [6.0, 1311836012] 330 ] 331 }] 332 333svg 334^^^ 335Renders the graph as SVG markup of size determined by width_ and height_. Metadata about 336the drawn graph is saved as an embedded script with the variable ``metadata`` being set to 337an object describing the graph 338 339.. code-block:: none 340 341 <script> 342 <![CDATA[ 343 metadata = { 344 "area": { 345 "xmin": 39.195507812499997, 346 "ymin": 33.96875, 347 "ymax": 623.794921875, 348 "xmax": 1122 349 }, 350 "series": [ 351 { 352 "start": 1335398400, 353 "step": 1800, 354 "end": 1335425400, 355 "name": "summarize(test.data, \"30min\", \"sum\")", 356 "color": "#859900", 357 "data": [null, null, 1.0, null, 1.0, null, 1.0, null, 1.0, null, 1.0, null, null, null, null], 358 "options": {}, 359 "valuesPerPoint": 1 360 } 361 ], 362 "y": { 363 "labelValues": [0, 0.25, 0.5, 0.75, 1.0], 364 "top": 1.0, 365 "labels": ["0 ", "0.25 ", "0.50 ", "0.75 ", "1.00 "], 366 "step": 0.25, 367 "bottom": 0 368 }, 369 "x": { 370 "start": 1335398400, 371 "end": 1335423600 372 }, 373 "font": { 374 "bold": false, 375 "name": "Sans", 376 "italic": false, 377 "size": 10 378 }, 379 "options": { 380 "lineWidth": 1.2 381 } 382 } 383 ]]> 384 </script> 385 386pdf 387^^^ 388Renders the graph as a PDF of size determined by width_ and height_. 389 390dygraph 391^^^^^^^ 392Renders the data as a json object suitable for passing to a `Dygraph <http://dygraphs.com/data.html>`_ object. 393 394.. code-block:: none 395 396 { 397 "labels" : [ 398 "Time", 399 "entries" 400 ], 401 "data" : [ 402 [1468791890000, 0.0], 403 [1468791900000, 0.0] 404 ] 405 } 406 407rickshaw 408^^^^^^^^ 409Renders the data as a json object suitable for passing to a `Rickshaw <http://code.shutterstock.com/rickshaw/tutorial/introduction.html>`_ object. 410 411.. code-block:: none 412 413 [{ 414 "target": "entries", 415 "datapoints": [{ 416 "y": 0.0, 417 "x": 1468791890 418 }, { 419 "y": 0.0, 420 "x": 1468791900 421 }] 422 }] 423 424pickle 425^^^^^^ 426Returns a Python `pickle <http://docs.python.org/library/pickle.html>`_ (serialized Python object). 427The response will have the MIME type 'application/pickle'. The pickled object is a list of 428dictionaries with the keys: ``name``, ``start``, ``end``, ``step``, and ``values`` as below: 429 430.. code-block:: python 431 432 [ 433 { 434 'name' : 'summarize(test.data, "30min", "sum")', 435 'start': 1335398400, 436 'end' : 1335425400, 437 'step' : 1800, 438 'values' : [None, None, 1.0, None, 1.0, None, 1.0, None, 1.0, None, 1.0, None, None, None, None], 439 } 440 ] 441 442rawData 443------- 444 445.. deprecated:: 0.9.9 446 447 This option is deprecated in favor of format 448 449Used to get numerical data out of the webapp instead of an image. 450Can be set to true, false, csv. 451Affects all ``&targets`` passed in the URL. 452 453Example: 454 455.. code-block:: none 456 457 &target=carbon.agents.graphiteServer01.cpuUsage&from=-5min&rawData=true 458 459Returns the following text: 460 461.. code-block:: none 462 463 carbon.agents.graphiteServer01.cpuUsage,1306217160,1306217460,60|0.0,0.00666666520965,0.00666666624282,0.0,0.0133345399694 464 465.. _graph-parameters : 466 467Graph Parameters 468================ 469 470.. _param-areaAlpha: 471 472areaAlpha 473--------- 474*Default: 1.0* 475 476Takes a floating point number between 0.0 and 1.0 477 478Sets the alpha (transparency) value of filled areas when using an areaMode_ 479 480.. _param-areaMode: 481 482areaMode 483-------- 484*Default: none* 485 486Enables filling of the area below the graphed lines. Fill area is the same color as 487the line color associated with it. See areaAlpha_ to make this area transparent. 488Takes one of the following parameters which determines the fill mode to use: 489 490``none`` 491 Disables areaMode 492``first`` 493 Fills the area under the first target and no other 494``all`` 495 Fills the areas under each target 496``stacked`` 497 Creates a graph where the filled area of each target is stacked on one another. 498 Each target line is displayed as the sum of all previous lines plus the value of the current line. 499 500.. _param-bgcolor: 501 502bgcolor 503------- 504*Default: value from the [default] template in graphTemplates.conf* 505 506Sets the background color of the graph. 507 508============ ============= 509Color Names RGB Value 510============ ============= 511black 0,0,0 512white 255,255,255 513blue 100,100,255 514green 0,200,0 515red 200,0,50 516yellow 255,255,0 517orange 255, 165, 0 518purple 200,100,255 519brown 150,100,50 520aqua 0,150,150 521gray 175,175,175 522grey 175,175,175 523magenta 255,0,255 524pink 255,100,100 525gold 200,200,0 526rose 200,150,200 527darkblue 0,0,255 528darkgreen 0,255,0 529darkred 255,0,0 530darkgray 111,111,111 531darkgrey 111,111,111 532============ ============= 533 534RGB can be passed directly in the format #RRGGBB[AA] where RR, GG, and BB are 2-digit hex values for red, green and blue, respectively. AA is an optional addition describing the opacity ("alpha"). Where FF is fully opaque, 00 fully transparent. 535 536Examples: 537 538.. code-block:: none 539 540 &bgcolor=blue 541 &bgcolor=2222FF 542 &bgcolor=5522FF60 543 544.. _param-cacheTimeout: 545 546cacheTimeout 547------------ 548*Default: The value of DEFAULT_CACHE_DURATION from local_settings.py* 549 550The time in seconds for the rendered graph to be cached (only relevant if memcached is configured) 551 552.. _param-colorList: 553 554colorList 555--------- 556*Default: value from the [default] template in graphTemplates.conf* 557 558Takes one or more comma-separated color names or RGB values (see bgcolor for a list of color names) and uses that list in order as the colors of the lines. 559If more lines / metrics are drawn than colors passed, the list is reused in order. Any RGB value can also have an optional transparency (00 being fully transparent, FF being opaque), as shown in the second example. 560 561Example: 562 563.. code-block:: none 564 565 &colorList=green,yellow,orange,red,purple,DECAFF 566 &colorList=FF000055,00FF00AA,DECAFFEF 567 568.. _param-drawNullAsZero: 569 570drawNullAsZero 571-------------- 572*Default: false* 573 574Converts any None (null) values in the displayed metrics to zero at render time. 575 576.. _param-fgcolor: 577 578fgcolor 579------- 580*Default: value from the [default] template in graphTemplates.conf* 581 582Sets the foreground color. 583This only affects the title, legend text, and axis labels. 584 585See majorGridLineColor_, and minorGridLineColor_ for further control of colors. 586 587See bgcolor_ for a list of color names and details on formatting this parameter. 588 589.. _param-fontBold: 590 591fontBold 592-------- 593*Default: value from the [default] template in graphTemplates.conf* 594 595If set to true, makes the font bold. 596 597Example: 598 599.. code-block:: none 600 601 &fontBold=true 602 603.. _param-fontItalic: 604 605fontItalic 606---------- 607*Default: value from the [default] template in graphTemplates.conf* 608 609If set to true, makes the font italic / oblique. 610Default is false. 611 612Example: 613 614.. code-block:: none 615 616 &fontItalic=true 617 618.. _param-fontName: 619 620fontName 621-------- 622*Default: value from the [default] template in graphTemplates.conf* 623 624Change the font used to render text on the graph. 625The font must be installed on the Graphite Server. 626 627Example: 628 629.. code-block:: none 630 631 &fontName=FreeMono 632 633.. _param-fontSize: 634 635fontSize 636-------- 637*Default: value from the [default] template in graphTemplates.conf* 638 639Changes the font size. 640Must be passed a positive floating point number or integer equal to or greater than 1. 641Default is 10 642 643Example: 644 645.. code-block:: none 646 647 &fontSize=8 648 649.. _param-format: 650 651format 652------ 653See: `Data Display Formats`_ 654 655.. _param-from: 656 657from 658---- 659See: `from / until`_ 660 661.. _param-graphOnly: 662 663graphOnly 664--------- 665*Default: False* 666 667Display only the graph area with no grid lines, axes, or legend 668 669.. _param-graphType: 670 671graphType 672--------- 673*Default: line* 674 675Sets the type of graph to be rendered. Currently there are only two graph types: 676 677``line`` 678 A line graph displaying metrics as lines over time 679``pie`` 680 A pie graph with each slice displaying an aggregate of each metric calculated using the function 681 specified by pieMode_ 682 683.. _param-hideLegend: 684 685hideLegend 686---------- 687*Default: <unset>* 688 689If set to ``true``, the legend is not drawn. 690If set to ``false``, the legend is drawn. 691If unset, the ``LEGEND_MAX_ITEMS`` settings in ``local_settings.py`` is used to determine 692whether or not to display the legend. 693 694Hint: If set to ``false`` the ``&height`` parameter may need to be increased to accommodate the additional text. 695 696Example: 697 698.. code-block:: none 699 700 &hideLegend=false 701 702.. _param-hideNullFromLegend: 703 704hideNullFromLegend 705------------------ 706*Default: False* 707 708If set to ``true``, series with all null values will not be reported in the legend. 709 710Example: 711 712.. code-block:: none 713 714 &hideNullFromLegend=true 715 716.. _param-hideAxes: 717 718hideAxes 719-------- 720*Default: False* 721 722If set to ``true`` the X and Y axes will not be rendered 723 724Example: 725 726.. code-block:: none 727 728 &hideAxes=true 729 730.. _param-hideXAxis: 731 732hideXAxis 733--------- 734*Default: False* 735 736If set to ``true`` the X Axis will not be rendered 737 738.. _param-hideYAxis: 739 740hideYAxis 741--------- 742*Default: False* 743 744If set to ``true`` the Y Axis will not be rendered 745 746.. _param-hideGrid: 747 748hideGrid 749-------- 750*Default: False* 751 752If set to ``true`` the grid lines will not be rendered 753 754Example: 755 756.. code-block:: none 757 758 &hideGrid=true 759 760.. _param-height: 761 762height 763------ 764*Default: 250* 765 766Sets the height of the generated graph image in pixels. 767 768See also: width_ 769 770Example: 771 772.. code-block:: none 773 774 &width=650&height=250 775 776.. _param-jsonp: 777 778jsonp 779----- 780*Default: <unset>* 781 782If set and combined with ``format=json``, wraps the JSON response in a function call 783named by the parameter specified. 784 785.. _param-leftColor: 786 787leftColor 788--------- 789*Default: color chosen from* colorList_ 790 791In dual Y-axis mode, sets the color of all metrics associated with the left Y-axis. 792 793.. _param-leftDashed: 794 795leftDashed 796---------- 797*Default: False* 798 799In dual Y-axis mode, draws all metrics associated with the left Y-axis using dashed lines 800 801.. _param-leftWidth: 802 803leftWidth 804--------- 805*Default: value of the parameter* lineWidth_ 806 807In dual Y-axis mode, sets the line width of all metrics associated with the left Y-axis 808 809.. _param-lineMode: 810 811lineMode 812-------- 813*Default: slope* 814 815Sets the line drawing behavior. Takes one of the following parameters: 816 817``slope`` 818 Slope line mode draws a line from each point to the next. Periods with Null values will not be drawn 819``staircase`` 820 Staircase draws a flat line for the duration of a time period and then a vertical line up or down to the next value 821``connected`` 822 Like a slope line, but values are always connected with a slope line, regardless of whether or not there are Null values between them 823 824Example: 825 826.. code-block:: none 827 828 &lineMode=staircase 829 830.. _param-lineWidth: 831 832lineWidth 833--------- 834*Default: 1.2* 835 836Takes any floating point or integer (negative numbers do not error but will cause no line to be drawn). 837Changes the width of the line in pixels. 838 839Example: 840 841.. code-block:: none 842 843 &lineWidth=2 844 845.. _param-logBase: 846 847logBase 848------- 849*Default: <unset>* 850 851If set, draws the graph with a logarithmic scale of the specified base (e.g. 10 for common logarithm) 852 853.. _param-localOnly: 854 855localOnly 856--------- 857*Default: False* 858 859Set to prevent fetching from remote Graphite servers, only returning metrics which are accessible locally 860 861.. _param-majorGridLineColor: 862 863majorGridLineColor 864------------------ 865*Default: value from the [default] template in graphTemplates.conf* 866 867Sets the color of the major grid lines. 868 869See bgcolor_ for valid color names and formats. 870 871 872Example: 873 874.. code-block:: none 875 876 &majorGridLineColor=FF22FF 877 878.. _param-margin: 879 880margin 881------ 882*Default: 10* 883Sets the margin around a graph image in pixels on all sides. 884 885Example: 886 887.. code-block:: none 888 889 &margin=20 890 891.. _param-max: 892 893max 894--- 895.. deprecated:: 0.9.0 896 See yMax_ 897 898.. _param-maxDataPoints: 899 900maxDataPoints 901------------- 902Set the maximum numbers of datapoints for each series returned when using json content. 903 904If for any output series the number of datapoints in a selected range exceeds the maxDataPoints value then the datapoints over the whole period are consolidated. 905 906The function used to consolidate points can be set using the `consolidateBy <functions.html#graphite.render.functions.consolidateBy>`_ function. 907 908.. _param-minorGridLineColor: 909 910minorGridLineColor 911------------------ 912*Default: value from the [default] template in graphTemplates.conf* 913 914Sets the color of the minor grid lines. 915 916See bgcolor_ for valid color names and formats. 917 918Example: 919 920.. code-block:: none 921 922 &minorGridLineColor=darkgrey 923 924.. _param-minorY: 925 926minorY 927------ 928Sets the number of minor grid lines per major line on the y-axis. 929 930Example: 931 932.. code-block:: none 933 934 &minorY=3 935 936.. _param-min: 937 938min 939--- 940.. deprecated:: 0.9.0 941 See yMin_ 942 943.. _param-minXStep: 944 945minXStep 946-------- 947*Default: 1* 948 949Sets the minimum pixel-step to use between datapoints drawn. Any value below this will trigger a 950point consolidation of the series at render time. The default value of ``1`` combined with the default 951lineWidth of ``1.2`` will cause a minimal amount of line overlap between close-together points. To 952disable render-time point consolidation entirely, set this to ``0`` though note that series with more points 953than there are pixels in the graph area (e.g. a few month's worth of per-minute data) will look very 954'smooshed' as there will be a good deal of line overlap. In response, one may use lineWidth_ to compensate 955for this. 956 957.. _param-noCache: 958 959noCache 960------- 961*Default: False* 962 963Set to disable caching of rendered images 964 965.. _param-noNullPoints: 966 967noNullPoints 968------------ 969*Default: False* 970 971If set and combined with ``format=json``, removes all null datapoints from the series returned. 972 973.. _param-pickle: 974 975pickle 976------ 977.. deprecated:: 0.9.10 978 See `Data Display Formats`_ 979 980.. _param-pieLabels: 981 982pieLabels 983--------- 984*Default: horizontal* 985 986Orientation to use for slice labels inside of a pie chart. 987 988``horizontal`` 989 Labels are oriented horizontally within each slice 990``rotated`` 991 Labels are oriented radially within each slice 992 993.. _param-pieMode: 994 995pieMode 996------- 997*Default: average* 998 999The type of aggregation to use to calculate slices of a pie when ``graphType=pie``. 1000One of: 1001 1002``average`` 1003 The average of non-null points in the series 1004``maximum`` 1005 The maximum of non-null points in the series 1006``minimum`` 1007 THe minimum of non-null points in the series 1008 1009.. _param-pretty: 1010 1011pretty 1012------ 1013*Default: <unset>* 1014 1015If set to 1 and combined with ``format=json``, outputs human-friendly json. 1016 1017.. _param-rightColor: 1018 1019rightColor 1020---------- 1021*Default: color chosen from* colorList_ 1022 1023In dual Y-axis mode, sets the color of all metrics associated with the right Y-axis. 1024 1025.. _param-rightDashed: 1026 1027rightDashed 1028----------- 1029*Default: False* 1030 1031In dual Y-axis mode, draws all metrics associated with the right Y-axis using dashed lines 1032 1033.. _param-rightWidth: 1034 1035rightWidth 1036---------- 1037*Default: value of the parameter* lineWidth_ 1038 1039In dual Y-axis mode, sets the line width of all metrics associated with the right Y-axis 1040 1041.. _param-template: 1042 1043template 1044-------- 1045*Default: default* 1046 1047Used to specify a template from ``graphTemplates.conf`` to use for default 1048colors and graph styles. 1049 1050Example: 1051 1052.. code-block:: none 1053 1054 &template=plain 1055 1056.. _param-thickness: 1057 1058thickness 1059--------- 1060.. deprecated:: 0.9.0 1061 See: lineWidth_ 1062 1063.. _param-title: 1064 1065title 1066----- 1067*Default: <unset>* 1068 1069Puts a title at the top of the graph, center aligned. 1070If unset, no title is displayed. 1071 1072Example: 1073 1074.. code-block:: none 1075 1076 &title=Apache Busy Threads, All Servers, Past 24h 1077 1078.. _param-tz: 1079 1080tz 1081-- 1082*Default: The timezone specified in local_settings.py* 1083 1084Time zone to convert all times into. 1085 1086Examples: 1087 1088.. code-block:: none 1089 1090 &tz=America/Los_Angeles 1091 &tz=UTC 1092 1093.. note:: 1094 1095 To change the default timezone, edit ``webapp/graphite/local_settings.py``. 1096 1097.. _param-uniqueLegend: 1098 1099uniqueLegend 1100------------ 1101*Default: False* 1102 1103Display only unique legend items, removing any duplicates 1104 1105.. _param-until: 1106 1107until 1108----- 1109See: `from / until`_ 1110 1111.. _param-valueLabels: 1112 1113valueLabels 1114----------- 1115*Default: percent* 1116 1117Determines how slice labels are rendered within a pie chart. 1118 1119``none`` 1120 Slice labels are not shown 1121``numbers`` 1122 Slice labels are reported with the original values 1123``percent`` 1124 Slice labels are reported as a percent of the whole 1125 1126.. _param-valueLabelsColor: 1127 1128valueLabelsColor 1129---------------- 1130*Default: black* 1131 1132Color used to draw slice labels within a pie chart. 1133 1134.. _param-valueLabelsMin: 1135 1136valueLabelsMin 1137-------------- 1138*Default: 5* 1139 1140Slice values below this minimum will not have their labels rendered. 1141 1142.. _param-vtitle: 1143 1144vtitle 1145------ 1146*Default: <unset>* 1147 1148Labels the y-axis with vertical text. 1149If unset, no y-axis label is displayed. 1150 1151Example: 1152 1153.. code-block:: none 1154 1155 &vtitle=Threads 1156 1157.. _param-vtitleRight: 1158 1159vtitleRight 1160----------- 1161*Default: <unset>* 1162 1163In dual Y-axis mode, sets the title of the right Y-Axis (See: `vtitle`_) 1164 1165.. _param-width: 1166 1167width 1168----- 1169*Default: 330* 1170 1171Sets the width of the generated graph image in pixels. 1172 1173See also: height_ 1174 1175Example: 1176 1177.. code-block:: none 1178 1179 &width=650&height=250 1180 1181.. _param-xFilesFactor: 1182 1183xFilesFactor 1184------------ 1185*Default: DEFAULT_XFILES_FACTOR specified in local_settings.py or 0* 1186 1187Sets the default `xFilesFactor` value used when performing runtime aggregation across multiple 1188series and/or intervals. 1189 1190See the `xFilesFactor <functions.html#graphite.render.functions.setXFilesFactor>`_ function for 1191more information on the `xFilesFactor` value and how the default can be overridden for specific 1192targets or series. 1193 1194.. _param-xFormat: 1195 1196xFormat 1197------- 1198*Default: Determined automatically based on the time-width of the X axis* 1199 1200Sets the time format used when displaying the X-axis. See 1201`datetime.date.strftime() <http://docs.python.org/library/datetime.html#datetime.date.strftime>`_ 1202for format specification details. 1203 1204.. _param-yAxisSide: 1205 1206yAxisSide 1207--------- 1208*Default: left* 1209 1210Sets the side of the graph on which to render the Y-axis. Accepts values of ``left`` or ``right`` 1211 1212.. _param-yDivisors: 1213 1214yDivisors 1215--------- 1216*Default: 4,5,6* 1217 1218Sets the preferred number of intermediate values to display on the Y-axis (Y values between the 1219minimum and maximum). Note that Graphite will ultimately choose what values (and how many) to 1220display based on a 'pretty' factor, which tries to maintain a sensible scale (e.g. preferring 1221intermediary values like 25%,50%,75% over 33.3%,66.6%). To explicitly set the Y-axis values, 1222see `yStep`_ 1223 1224.. _param-yLimit: 1225 1226yLimit 1227------ 1228*Reserved for future use* 1229See: yMax_ 1230 1231.. _param-yLimitLeft: 1232 1233yLimitLeft 1234---------- 1235*Reserved for future use* 1236See: yMaxLeft_ 1237 1238.. _param-yLimitRight: 1239 1240yLimitRight 1241----------- 1242*Reserved for future use* 1243See: yMaxRight_ 1244 1245.. _param-yMin: 1246 1247yMin 1248---- 1249*Default: The lowest value of any of the series displayed* 1250 1251Manually sets the lower bound of the graph. Can be passed any integer or floating point number. 1252 1253Example: 1254 1255.. code-block:: none 1256 1257 &yMin=0 1258 1259.. _param-yMax: 1260 1261yMax 1262---- 1263*Default: The highest value of any of the series displayed* 1264 1265Manually sets the upper bound of the graph. Can be passed any integer or floating point number. 1266 1267Example: 1268 1269.. code-block:: none 1270 1271 &yMax=0.2345 1272 1273.. _param-yMaxLeft: 1274 1275yMaxLeft 1276-------- 1277In dual Y-axis mode, sets the upper bound of the left Y-Axis (See: `yMax`_) 1278 1279.. _param-yMaxRight: 1280 1281yMaxRight 1282--------- 1283In dual Y-axis mode, sets the upper bound of the right Y-Axis (See: `yMax`_) 1284 1285.. _param-yMinLeft: 1286 1287yMinLeft 1288-------- 1289In dual Y-axis mode, sets the lower bound of the left Y-Axis (See: `yMin`_) 1290 1291.. _param-yMinRight: 1292 1293yMinRight 1294--------- 1295In dual Y-axis mode, sets the lower bound of the right Y-Axis (See: `yMin`_) 1296 1297.. _param-yStep: 1298 1299yStep 1300----- 1301*Default: Calculated automatically* 1302 1303Manually set the value step between Y-axis labels and grid lines 1304 1305.. _param-yStepLeft: 1306 1307yStepLeft 1308--------- 1309In dual Y-axis mode, Manually set the value step between the left Y-axis labels and grid lines (See: `yStep`_) 1310 1311.. _param-yStepRight: 1312 1313yStepRight 1314---------- 1315In dual Y-axis mode, Manually set the value step between the right Y-axis labels and grid lines (See: `yStep`_) 1316 1317.. _param-yUnitSystem: 1318 1319yUnitSystem 1320----------- 1321*Default: si* 1322 1323Set the unit system for compacting Y-axis values (e.g. 23,000,000 becomes 23M). 1324Value can be one of: 1325 1326``si`` 1327 Use si units (powers of 1000) - K, M, G, T, P 1328``binary`` 1329 Use binary units (powers of 1024) - Ki, Mi, Gi, Ti, Pi 1330``sec`` 1331 Use time units (seconds) - m, H, D, M, Y 1332``msec`` 1333 Use time units (milliseconds) - s, m, H, D, M, Y 1334``none`` 1335 Dont compact values, display the raw number 1336 1337