[Introduction]
[Requirements]
[Installing]
[Configuration]
[Database]
[MySQL]
[PostgreSQL]
[SQLite]
[Calendar]
[Caching]
[Graphing]
[Charts]
[Images]
[Troubleshooting]
[Error reporting and support]
Introduction
taloLoggerGraph is a graphing application that reads log data from
a database table and draws graphical plots on time axis including
history data and recent data to user provided image graphs. Data should be
in a supported database, in one table or view and the data must contain a
timestamp of the moment the data has been recorded. The result graphs
are viewed in a web browser.
The application is implemented in PHP
and utilises the JpGraph and/or
D3 Data-Driven Documents library to
draw the plot graphs. Supported databases are
MySQL and
SQLite.
However the taloLoggerGraph is implemented and distributed closely with the
taloLogger application, it can also be used
to graph any other suitable data.
Requirements
The taloLoggerGraph application requires a PHP
version 5.1 or newer.
The graph plotting functions require
JpGraph (tested with version 3.0.7,
the beta version 3.5.0b1 is not recommended as does not generate as
clear plots as the latest release version and has still some bugs).
Image creating functionality requires GD support for PHP. If only
javascript graphing mode is used, JpGraph and GD-support are not required.
Accessing logged data in a database requires PDO database support or native interface for PHP for
MySQL and/or SQLite.
Installing
These installation instructions provide a one perspective on installin
the taloLoggerGraph PHP application. There are multiple ways to make
a web PHP application work. The way you should use depends on your
system setup, your expertise and the requirements that your system
has about using PHP code in your web pages.
In this example I have a user named talo that installs the
taloLoggerGraph in its public_html folder. In my system I have distinct
web and PHP configuration for each user (distinct Location-directive in
httpd.conf). The PHP configuration could also be global for httpd server
or defined in system php.ini.
taloLoggerGraph
- Install and configure all required applications and libraries.
- Download the taloLoggerGraph
application zip archive.
- Extract the archive to some desired location on your system where the
httpd and PHP can access it. In the example in this document
the package is extracted to
/home/talo/public_html/scripts.
Extracting the archive in directory will create
taloLoggerGraph directory with the application code files.
% cd /home/talo/public_html/scripts
% unzip /.../taloLoggerGraph_vxxx.zip
- Copy or move the
index.php and taloLoggerGraph.conf
files to your web folder containing the web documents you view.
In this example I use folder /home/talo/public_html/log.
% cd /home/talo/public_html/scripts/taloLogger
% cp index.php taloLoggerGraph.conf /home/talo/public_html/log
- Have the file
taloLoggerGraph_getchart.php available also
to the web folder. This can be accomplished either by creating a
symbolic link to the file, which makes further upgrading the taloLoggerGraph
version easier, or copying the code file to the web folder.
% cd /home/talo/public_html/log
% ln -s ../scripts/taloLoggerGraph/taloLoggerGraph_getchart.php
- Make sure that the user id used to execute PHP code in the httpd server
has access to the files (chmod if necessary).
- Configure httpd and PHP so that the web location you are using can
execute PHP code and has access to the JpGraph libraries (optional
since v1.2b) and
taloLoggerGraph libraries. The configuration can be done to the
httpd server configuration or to system
php.ini.
As an example I added the following section
to my Apache httpd httpd.conf configuration file to enable
taloLoggerGraph to my web location.
<Location /talo/>
php_value doc_root /home/talo/public_html
php_value open_basedir /home/talo/public_html
php_value include_path .:/home/talo/public_html/scripts/taloLoggerGraph:/usr/local/jpgraph/src
php_flag safe_mode yes
</Location>
See taloLoggerGraph FAQ for other possibilities
to configure include_path.
- Activate the httpd server configuration changes (at least with Apache):
# /etc/init.d/httpd graceful
- Edit the
taloLoggerGraph.conf
configuration file in your web directory
to reflect your database setup and desired graph result.
- See the
index.php file in your web folder. The part of the
file that produces the graph application part is:
<?PHP
include("taloLoggerGraph.inc");
taloLoggerGraph("taloLoggerGraph.conf");
?>
This part can be utilised in any of your own PHP web documents.
The configuration file name in the taloLoggerGraph function call
can be varied to have multiple graph configurations in your web
pages.
- Try to load the index.php with your browser. (I would use: http://olammi.iki.fi/talo/log/index.php)
Configuration
This section describes how to create the taloLoggerGraph configuration and
write the configuration file for the application. Use the default
taloLoggerGraph.conf confguration file delivered in the
application archive as a base for the application configuration.
The configuration file describes one taloLoggerGraph page with access to
one database table and producing one to many separate chart images. Only
one database table is available for one chart configuration file. If you
need to combine data from multiple tables, at the moment this can only
be achieved by using database views to combine the data to one table.
The configuration file consists of key value pairs, comments, section
markers and list key value pairs. The keys are described below and also
in the comments of the sample configuration file in the application package.
Database configuration
The configuration describes the following configuration directives
that are common to all database types:
| Configuration directive |
Description |
Values |
DB_TYPE |
Type of the database used. |
MYSQL, POSTGRESQL or SQLITE |
DB_TALOLOGGER_SCHEMA_VERSION |
Version of the taloLogger native dynamic database schema
version to use. If configured and non-zero, taloLoggerGraph will
assume that data is stored to the configured database with
taloLogger and its native schema is used.
DB_TABLE and DB_TIMECOL
directives are ignored if this directive is configured. |
integer, 0 or 1 |
DB_TABLE |
Database table name containing the log data. |
string |
DB_TIMECOL |
Database table column name containing the timestamp for one
set of log samples. |
string |
MySQL configuration
MySQL database table specific configuration directives:
| Configuration directive |
Description |
Values |
MYSQLDB_HOST |
Hostname for the MySQL database server |
string |
MYSQLDB_USER |
Username for the MySQL database.
|
string |
MYSQLDB_PASSWD |
Password for the database.
|
string |
MYSQLDB_NAME |
The database name.
|
string |
PostgreSQL configuration
PostgreSQL database table specific configuration directives:
| Configuration directive |
Description |
Values |
POSTGRESQLDB_HOST |
Hostname for the PostgreSQL database server |
string |
POSTGRESQLDB_USER |
Username for the PostgreSQL database.
|
string |
POSTGRESQLDB_PASSWD |
Password for the database.
|
string |
POSTGRESQLDB_NAME |
The database name.
|
string |
SQLite configuration
SQLite database table specific configuration directives:
| Configuration directive |
Description |
Values |
SQLITEDB_NAME |
File name for the SQLite database |
file name (with path) |
Calendar configuration
Calendar specific configuration directives:
| Configuration directive |
Description |
Values |
HIDE_CALENDAR |
If true, the calendar is not displayed above the graphs. |
string, true/false |
Caching configuration
Configuration directives affecting the graph caching:
| Configuration directive |
Description |
Values |
CACHE_IMAGES |
When true, caches suitable graphs (eg. day graphs when the full
day has passed and no more new data is expected)
|
string, true/false |
CACHE_DIRECTORY |
Cache directory location on the file system. This directory should
be visible through the web server. This directory should be writable
for the user running the taloLoggerGraph (user running the web server).
|
string |
CACHE_URL_PATH |
Location of the cache directory in the web servers URL path. The base URL
pointing to the cache directory configured by CACHE_DIRECTORY.
|
string |
Graphing configuration
Configuration directives affecting the graph drawing:
| Configuration directive |
Description |
Values |
JAVASCRIPT_CHARTS |
How to draw the result graphs:
false - default, draw images server side (JpGraph)
true - use javascript (d3js) in browser to visualize the graphs |
string, true/false |
Chart configuration
At the moment this section of the configuration is under construction.
Please see the taloLoggerGraph.conf distributed with the package for
information about the configuration syntax. The documentative part
of the example configuration file is also included below.
#############################################################################
# Chart1 configuration
#############################################################################
# Start a new chart
*CHART*
# Chart title, appears in the chart image (may be left empty)
TITLE = Temperatures
# Chart Y-axis configuration for axis 1 and optionally for axis 2
#
# Syntax: AXIS_n=min:max:major_tick:minor_tick:title
#
# n - Y-axis number (1 to N)
#
# min - minimum value visible in axis scale
# (auto for automatic scaling)
#
# max - maximum value visible in axis scale
# (auto for automatic scaling)
#
# major_tick - interval for major tickmarks in axis,
# the axis labels will be printed next to the
# major tick marks
# (auto for automatic scaling)
#
# minor_tick - interval for minor tickmarks in axis,
# use same value as for major_tick to hide
# minor tick marks
# (auto for automatic scaling)
#
# title - axis title (eg. unit)
#
# Example: AXIS_1 = -30.0:30.0:10.0:5.0:C
# Example: AXIS_2 = auto:auto:10:5:C
#
AXIS_1 = -30:30:10:5:C
#AXIS_2 = 10:70:10:5:C
# Chart image size configuration, in pixels (optional)
# (NOTE: The actual y-size of the result image depends also
# on the chart legend height. The legend is added
# to the result image height.)
#
# Syntax: SIZE=xsize:ysize
#
SIZE = 800:694
# Chart legend configuration
#
# Syntax: LEGEND=cols:values
#
# cols - Number of columns in the chart legend.
# (0 for no legend)
#
# value - Configures whether the legend will contain
# numerical data (last value or average).
# Possible values are:
# 0 - no data
#
# 1 - for today's chart the recent data value
# and for history charts the average data value
#
# 2 - for today's chart both recent and average
# data values and for history charts the average
# data value
#
# 3 - average data values for all charts
#
# Example: LEGEND = 3:1
#
LEGEND = 6:2
# Chart data series configuration
#
# Syntax: @SERIES=type:db_column:legend:color:
#
# type - type of the series. Possible values are:
# NORMAL - Series will be drawn as a
# coloured line indicating the
# series value at each time.
# STATE - Series will be drawn as
# a coloured bar on top of the
# X-axis indicating the times
# the state was active.
# COUNTER - Series will be drawn as a
# coloured line indicating
# the amount a counter value
# has increased in average in one
# second between the last value
# and new value.
#
# db_column - name of the database table column to evaluate
# with this series
#
# legend - title text that will appear in the legend
# box
#
# color - color that will be used to draw this data series,
# color value may be a RGB value given in the
# hexadecimal format (example: #E0E0E0) or as
# a JpGraph predefined color name
# (http://jpgraph.net/download/manuals/chunkhtml/apd.html)
#
# - additional parameters depending on the
# series type:
#
# For NORMAL type:
#
# Syntax: axis:factor
#
# axis - number of Y-axis for this series
#
# factor - the values in the database column will
# be multiplied with this factor before
# drawing
#
# For COUNTER type:
#
# Syntax: axis:factor:cnttype[:maxvalue]
#
# axis - number of Y-axis for this series
#
# factor - the values in the database column will
# be multiplied with this factor before
# drawing
#
# cnttype - type of the counter value
# 0 - when the counter value has not changed
# since last value, the value drawn is
# zero
# 1 - when the counter value has not changed
# since last value, consider this measurement
# non existing. The next change in the counter
# will result as average line over the period
# the value stayed unchanged
# 2 - cumulative counter type. Outputs a daily
# cumulative counter graph.
#
# maxvalue - Maximum value for counter (optional)
#
# For STATE type:
# Syntax: statement
#
# statement - this statement will be evaluated
# for the database value (marked as
# %VALUE% in the statement). If the
# statement is true for a value at a time
# the state bar will be drawn for that
# time in the chart.
#
# Examples:
#
# @SERIES = NORMAL:outdoor:Outdoor temp:orange:2:0.01
#
# A data series will be read from database column outdoor,
# divided by 100 (same as multiplied by 0.01) and drawn
# in orange color against the axis number 2 in the chart.
# The legend text for the data series is "Outdoor temp".
#
# @SERIES = STATE:statevalue:Compressor:yellowgreen:(%VALUE% & 16) != 0
#
# A state bar will be drawn in yellowish green indicating
# whether the database column walue "statevalue" has bit 4 set
# (and with value 16 results to a non zero value). The legend
# text for the state bar is "Compressor".
#
# @SERIES = STATE:water_top:Hot water:red:%VALUE% > 45.0
#
# A state bar will be drawn in red indicating
# whether the database column walue "water_top" is higher
# than 45.0. The legend text for the state bar is "Hot water".
#
# @SERIES = COUNTER:kwh_counter:El. power:blue:1:3.6:0
#
# A counter data series will be read from database column
# "kwh_counter". The counter difference with the last received value
# is calculated and averaged over the time span to indicate how much
# the counter in average has increased during each second in the
# interval. Then the average per second increase will be multiplied
# by the factor 3.6 (the factor parameter). The series will be
# drawn against the axis number 1. The legend text for the
# data series is "El. power".
#
@SERIES = NORMAL:dummy:outdoor:orange:1:1.0
@SERIES = STATE:dummy:freezing:blue:%VALUE% < 0.0
#############################################################################
# Image1 configuration
#############################################################################
*IMAGE*
# Background image (must be in png format).
BACKGROUND = docs/ghp_process.png
# Title for the image (can be commented out for no title)
#
# Syntax: TITLE = xpos:ypos:color:title
#
TITLE = 235:295:black:GHP process
# Image data position configuration
#
# Syntax: @POSITION=type:db_column:xpos:ypos:subtype:
#
# type - type of the series. Possible values are:
# NORMAL - Database column contains
# the direct data. Values are
# multiplied by the factor given.
# STATE - State will be calculated
# using the statement given.
# A coloured circle will be drawn
# as a indication of active status
# COUNTER - Database column contains counter
# data. The result value is determined by
# calculating how much counter value
# has increased in average in one
# second between the last value
# and new value. The result is multiplied
# by the factor given.
#
# db_column - name of the database table column to evaluate
# with this position
#
# xpos - x position in pixels of the top left corner of the
# label text or center of the state circle starting
# from the left of the image
#
# ypos - y position in pixels of the top left corner of the
# label text or center of the state circle starting
# from the top of the image
#
# subtype - type to output
# VAL - current value or state circle
#
# MIN - minimum value for the current period
# (not valid for the STATE type)
#
# MAX - minimum value for the current period
# (not valid for the STATE type)
#
# AVG - average value for the current period
# (average ON percent for the STATE type)
#
# - additional parameters depending on the
# position type:
#
# For NORMAL and COUNTER types:
#
# Syntax: factor:lowcolor:highcolor:lowvalue:highvalue:unit
# (for COUNTER type add :cnttype[:maxvalue] after unit)
#
# factor - the values in the database column will
# be multiplied with this factor before
# evaluating
#
# lowcolor - color that will be used to write this data label,
# when the value is less than or equal to the lowvalue
# parameter. Color value may be a RGB value given in the
# hexadecimal format (example: #E0E0E0) or as a JpGraph
# predefined color name
# (http://jpgraph.net/download/manuals/chunkhtml/apd.html)
#
# highcolor - color that will be used to write this data label when
# the value is greater than or equal to the highvalue
# parameter. See lowcolor for the color format.
#
# lowvalue - Value when the label color reaches the lowcolor.
# Values between lowvalue to highvalue will be
# drawn using a color between lowcolor and highcolor.
#
# highvalue - Value when the label color reaches the highcolor.
#
# unit - Unit label for the position (eg. kW)
#
# Additionally for COUNTER type:
#
# cnttype - type of the counter value
# 0 - when the counter value has not changed
# since last value, the value drawn is
# zero
# 1 - when the counter value has not changed
# since last value, consider this measurement
# non existing. The next change in the counter
# will result as average line over the period
# the value stayed unchanged
# 2 - cumulative counter type. Outputs a daily
# cumulative counter increment.
#
# maxvalue - Maximum value for counter (optional)
#
# For STATE type:
# Syntax: color:size:statement
#
# color - color that will be used to draw the active
# state circle in the image. See lowcolor for
# the color format.
#
# size - size in pixels for the circle
#
# statement - this statement will be evaluated
# for the database value (marked as
# %VALUE% in the statement). If the
# statement is true for a value at a time
# the state circle will be drawn to the
# image.
#
# Examples:
#
# @POSITION = NORMAL:floor_out:552:200:VAL:1.0:blue:red:19.0:32.0:C
#
# A data series will be read from database column floor_out,
# not scaled (same as multiplied by 1.0) and the data label
# will be written in color between blue and red when the
# value is between 19.0 and 32.0. The label text is drawn
# in (x,y) position (552,200) in the image. The unit label
# is "C".
#
# @POSITION = STATE:statevalue:136:157:VAL:yellowgreen:20:(%VALUE% & 16) != 0
#
# A state circle will be drawn in yellowish green indicating
# whether the database column walue "statevalue" has bit 4 set
# (and with value 16 results to a non zero value). The diamater of
# the circle is 20 pixels. The center of the circle is in
# in (x,y) position in the image (136,157).
#
@POSITION = NORMAL:dummy:50:50:VAL:1.0:blue:red:-20.0:20.0:C
# Additional label configuration
#
# Additional optional text labels can be added to the image using
# LABEL list directives. (optional)
#
# Syntax: @LABEL = xpos:ypos:color:label text
#
@LABEL = 0:50:black:Outdoor
Troubleshooting
Check your httpd server error logs to troubleshoot any problems
encountered with taloLoggerGraph. Mind also
any error messages in the response on the result web page.
Error reporting and support
If you still encounter problems running the application after following
instructions of this HOWTO documentation and after reading the
taloLoggerGraph FAQ, send a support request or
error report by email to the author of the application
(olammi at iki dot fi). Please include the following data to the mail:
- description of the problem
- possible httpd error log rows concerning the problem
- any possible error messages output to the browser by taloLoggerGraph
- taloLoggerGraph.conf configuration file used with the application when
the problems occur (
xxxxx the possible database username
and password from the configuration for security reasons)
