Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
projects:telegraph [2018/11/11 20:21] darron |
projects:telegraph [2020/09/03 09:12] (current) darron [User defined function] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ==== Telegraph ==== | ==== Telegraph ==== | ||
| <wrap right> | <wrap right> | ||
| + | {{: | ||
| + | {{: | ||
| {{: | {{: | ||
| </ | </ | ||
| - | Telegraph is a multi-purpose tool which provides sensor | + | Telegraph is a multi-purpose tool which provides sensor |
| - | For sensors, | + | Telegraph |
| - | Telegraph | + | Telegraph also supports networking and can use ICMP to measure network latency |
| - | Telegraph is run from CRON at regular | + | Telegraph is run from CRON at 5 minute intervals for data gathering and the sensor processes |
| - | PHP scripts demonstrate how you can access the RRD files and generate graphs on a web page like the one shown above. | + | At each CRON iteration Telegraph |
| - | Telegraph can also report | + | PHP scripts demonstrate how you can access the RRD files containing the data to generate graphs for the web like the one shown above. |
| + | |||
| + | Telegraph can send reports | ||
| === Install === | === Install === | ||
| Line 28: | Line 32: | ||
| Now view the instructions found in the README file in the telegraph directory which explains the installation process. | Now view the instructions found in the README file in the telegraph directory which explains the installation process. | ||
| - | === Sensor | + | === Sensor |
| - | For the SNMP (simple network management protocol) daemon, Telegraph supplies the following sensor | + | For the SNMP (simple network management protocol) daemon, Telegraph supplies the following sensor processes. |
| ^ Process ^ Use ^ | ^ Process ^ Use ^ | ||
| Line 56: | Line 60: | ||
| | LEVEL | Value scaled 0..1 | | | | LEVEL | Value scaled 0..1 | | | ||
| | SCALE LEVEL| value scaled 0..N | | | | SCALE LEVEL| value scaled 0..N | | | ||
| - | | RESISTANCE | Resistance calculation | + | | RESISTANCE | Resistance calculation |
| | VOLTAGE | | VOLTAGE | ||
| | LM19 | Temperature | | LM19 | Temperature | ||
| Line 64: | Line 68: | ||
| | MCP9701 | | MCP9701 | ||
| | TMP36 | Temperature | | TMP36 | Temperature | ||
| - | | LDR | Light calculation | + | | LDR | Light calculation |
| - | | NTC | Temperature calculation |VCC - R - LEVEL - NTC - GND| | + | | NTC | Temperature calculation |VCC - R - VINPUT |
| - | Each probe has a set of command line arguments specific to that probe type. | + | Each process |
| < | < | ||
| Line 118: | Line 122: | ||
| B is known as the NTC B25 value and Ro is R25 on the datasheet for the device. R is the known resistance of the device at the current temperature and the B25/R25 values are representative of room temperature at 25'C. | B is known as the NTC B25 value and Ro is R25 on the datasheet for the device. R is the known resistance of the device at the current temperature and the B25/R25 values are representative of room temperature at 25'C. | ||
| - | === SNMP === | + | === Simple Network Management Protocol |
| - | The SNMP configuration uses the net-snmp extend feature | + | The SNMP server |
| - | allows | + | |
| - | text string representing a numerical value, else U which means UKNOWN. | + | |
| / | / | ||
| < | < | ||
| - | rocommunity public | + | rocommunity public |
| extend cpu / | extend cpu / | ||
| </ | </ | ||
| - | In this simple example, a net-snmp extend is set to return the CPU temperature when queried. | + | In this simple example, a net-snmp extend is set to return the CPU temperature when queried. The first line is access control with rocommunity describing a read-only group and public being that groups authentication. The network range limits any queries for this group to that range. |
| - | After changing the snmp config it must be restart for the new setting to take efect. | + | Any number of extend entries can be made with each having a unique name and purpose. |
| + | Whenever a change to the SNMP server configuration is made the server must be restarted for any new settings to take effect. | ||
| < | < | ||
| / | / | ||
| </ | </ | ||
| + | |||
| === Data gathering === | === Data gathering === | ||
| - | This configuration file sets up a query for the above cpu temperature in snmpd.conf. | + | At periodic intervals Telegraph is run from CRON to gather data. The data can represent gauges which are ranges of values, like temperature, |
| + | |||
| + | The type of data is configured as a gauge by default, but this can be overriden to any type supported by RRDTOOL when using an RRD. For SQL, this is user defined, and not documented here, please refer to the meter demo for assistance. | ||
| + | |||
| + | This configuration file sets up a query for cpu temperature | ||
| / | / | ||
| Line 147: | Line 155: | ||
| < | < | ||
| < | < | ||
| - | < | + | < |
| </ | </ | ||
| </ | </ | ||
| Line 154: | Line 162: | ||
| the head of a graph and with reporting it will be the subject of the report. | the head of a graph and with reporting it will be the subject of the report. | ||
| - | The rrd file is where data is stored, by default this will be in / | + | The RRD file is where data is stored, by default this will be in / |
| but a path may be specified if required. | but a path may be specified if required. | ||
| Line 160: | Line 168: | ||
| each new query. | each new query. | ||
| - | Only similar | + | Only the same data types can exist in any one configuration file, for example, only |
| temperature or only network activity. Data types cannot be mixed and demand | temperature or only network activity. Data types cannot be mixed and demand | ||
| - | separate | + | separate |
| If an RRD file exists and a new query is added, it will not work and a new column | If an RRD file exists and a new query is added, it will not work and a new column | ||
| Line 169: | Line 177: | ||
| Telegraph supplies a command line tool ' | Telegraph supplies a command line tool ' | ||
| to allow new sources to be added easily to an already existing RRD file. | to allow new sources to be added easily to an already existing RRD file. | ||
| - | |||
| - | |||
| - | |||
| - | |||
| === CRON === | === CRON === | ||
| - | CRON should run Telegraph every 5 minutes to gather data. | + | CRON is a daemon in Unix which invokes processes at specific times and intervals. |
| + | |||
| + | CRON should run Telegraph every 5 minutes to gather data like this. | ||
| < | < | ||
| */5 * * * * / | */5 * * * * / | ||
| </ | </ | ||
| - | This cron job will fetch values and store them in the database as configured by cpu.xml | + | CRON configuration is in TABLES, or CRONTABS, and is edited like this for Telegraph. It should be noted that Telegraph only uses root to set up ICMP and runs as an unprivileged user otherwise. |
| + | < | ||
| + | sudo crontab -e | ||
| + | </ | ||
| + | |||
| + | This CRON job will fetch values and store them in the database as configured by cpu.xml | ||
| - | The -d option is a delay value, it can be used to delay the process from cron | + | The -d option is a delay value, it can be used to delay the process from CRON |
| when multiple telegraph processes are executed in parallel to stagger their | when multiple telegraph processes are executed in parallel to stagger their | ||
| processing and potential load on the system or target systems. | processing and potential load on the system or target systems. | ||
| < | < | ||
| - | */5 * * * * / | + | */5 * * * * / |
| */5 * * * * / | */5 * * * * / | ||
| </ | </ | ||
| - | === World wide web === | ||
| - | Example configuration exists in the demo directory of the project which is used to demonstrate its operation | + | In these CRON entries every 5 minutes a Telegraph process gathers cpu data whilst another waits 30 seconds before gathering network statistics. |
| - | with PHP scripts that are installed in / | + | |
| + | === User defined function === | ||
| + | |||
| + | A user defined function may be forked every time Telegraph fetches new data. Forking allows a new process to be created and run in parallel by the process creating the fork. | ||
| + | |||
| + | The user option in the configuration file informs telegraph to fork the named process. | ||
| + | |||
| + | < | ||
| + | <user fork="/ | ||
| + | </ | ||
| + | |||
| + | With this line, the executable / | ||
| + | |||
| + | The command line arguments for the process are the process name, the telegraph title and then every result for each source in turn. This means that argv[2] would represent source 0 and argv[3] source 1, etc. | ||
| + | |||
| + | === Web graphing === | ||
| + | |||
| + | Example configuration exists in the demo directory of the project which is used to demonstrate its operation with PHP scripts that are installed in / | ||
| - | The london demo can be seen [[http:// | + | The london demo can be seen [[http:// |
| - | graphs may be slightly dated. | + | |
| The demo has been designed to work with apache2 but nginx will also work well. | The demo has been designed to work with apache2 but nginx will also work well. | ||
| - | === Reporting | + | === Status reporting |
| Telegraph can report problems it finds when gathering data or when a returned value is out of range. | Telegraph can report problems it finds when gathering data or when a returned value is out of range. | ||
| Line 213: | Line 239: | ||
| Three types of report delivery exist, e-mail, XMPP and HTTP POST. | Three types of report delivery exist, e-mail, XMPP and HTTP POST. | ||
| - | E-mail reporting requires sendmail or equivalent to be installed and XMPP demands a valid jabber/xmpp account to use as a sender. HTTP POST is set up to work with the RUN/STOP watchdog service at runstop.uk | + | E-mail reporting requires sendmail or equivalent to be installed and XMPP demands a valid jabber/xmpp account to use as a sender. HTTP POST is set up to work with the RUN/STOP watchdog service at [[https://runstop.uk|runstop.uk]] |
| The Telegraph XML configuration file is updated for reporting. | The Telegraph XML configuration file is updated for reporting. | ||
| - | <Code> | + | <code> |
| - | < | + | <monitor filename=" |
| - | <report type=" | + | <report type=" |
| - | <report type=" | + | <report type=" |
| - | <report type=" | + | <report type=" |
| </ | </ | ||
| Line 227: | Line 253: | ||
| The three report lines demonstrate sending reports. The first is e-mail, the second sends a jabber message to the destination using credentials found in | The three report lines demonstrate sending reports. The first is e-mail, the second sends a jabber message to the destination using credentials found in | ||
| - | the file / | + | the file / |
| The content of a report contains 1 or more lines in CSV format. | The content of a report contains 1 or more lines in CSV format. | ||
| Line 246: | Line 272: | ||
| </ | </ | ||
| - | This report show that a HIGH level or 20 has been reached by a temperature probe. | + | This report show that a HIGH level of 20 has been reached by a temperature probe. |
| === Other tools === | === Other tools === | ||
| Line 269: | Line 294: | ||
| < | < | ||
| - | $ snmpget -v2c -c public | + | $ snmpget -v2c -c public |
| NET-SNMP-EXTEND-MIB:: | NET-SNMP-EXTEND-MIB:: | ||
| </ | </ | ||
| How you use the MIB in other tools is of course, tool specific. | How you use the MIB in other tools is of course, tool specific. | ||
| + | |||
