Cacti (home)ForumsDocumentation

Differences

This shows you the differences between two versions of the page.

manual:088:3a_advanced_topics.1_data_input_methods [2009/03/23 10:42]
127.0.0.1 external edit
manual:088:3a_advanced_topics.1_data_input_methods [2019/10/29 15:16] (current)
Line 54: Line 54:
  
 One last thing to keep in mind when writing scripts for Cacti is that they will be executed as the user the data gatherer runs as. Sometimes a script may work correctly when executed as root, but fails due to permissions problems when executed as a less privileged user. One last thing to keep in mind when writing scripts for Cacti is that they will be executed as the user the data gatherer runs as. Sometimes a script may work correctly when executed as root, but fails due to permissions problems when executed as a less privileged user.
 +
 +**Note:** Spine requires, that multiple parameters are spit out by a single "print" statement. Do **not** print them in a loop!
 +
 ==== Walkthrough: My First Data Input Method ==== ==== Walkthrough: My First Data Input Method ====
  
Line 60: Line 63:
  
 <code>#!/usr/bin/perl <code>#!/usr/bin/perl
-$ping `ping -c 1 $ARGV[0] | grep icmp_seq`;+ 
 +# take care for tcp:hostname or TCP:[email protected] 
 +$host $ARGV[0]; 
 +$host =~ s/tcp:/$1/gis; 
 + 
 +# old linux version use "icmp_seq" 
 +# newer use "icmp_req" instead 
 +open(PROCESS, "ping -c 1 $host | grep 'icmp_[s|r]eq' | grep time |"); 
 +$ping = <PROCESS>; 
 +close(PROCESS);
 $ping =~ m/(.*time=)(.*) (ms|usec)/; $ping =~ m/(.*time=)(.*) (ms|usec)/;
-print $2;</code>+ 
 +if ($2 == "") { 
 +        print "U";              # avoid cacti errors, but do not fake rrdtool stats 
 +}elsif ($3 eq "usec") { 
 +        print $2/1000;  # re-calculate in units of "ms" 
 +}else{ 
 +        print $2; 
 +
 +</code>
  
 To define this script as a **Data Input Method** to cacti, please go to **Data Input Methods** and click **Add**. You should see: To define this script as a **Data Input Method** to cacti, please go to **Data Input Methods** and click **Add**. You should see:
  
-{{http://docs.cacti.net/files/images/r-dim1_0.png|Add a new Data Input Method}}+{{:manual:088:r-dim1_0.png|Add a new Data Input Method}}
  
 Please fill in **Name**, select **Script/Command** as Input Type and provide the command that should be used to retrieve the data. You may use <path_cacti> as a symbolical name for the path_to_your_cacti_installation. Those commands will be executed from crontab; so pay attention to providing full path to binaries if required (e.g. /usr/bin/perl instead of perl). Enter all **Input Parameters** in <> brackets. Click create to see: Please fill in **Name**, select **Script/Command** as Input Type and provide the command that should be used to retrieve the data. You may use <path_cacti> as a symbolical name for the path_to_your_cacti_installation. Those commands will be executed from crontab; so pay attention to providing full path to binaries if required (e.g. /usr/bin/perl instead of perl). Enter all **Input Parameters** in <> brackets. Click create to see:
  
-{{http://docs.cacti.net/files/images/r-dim2.png|Enter Data for new Data Input Method}}+{{:manual:088:r-dim2.png|Enter Data for new Data Input Method}}
  
 Now lets define the **Input Fields**. Click **Add** as given above to see: Now lets define the **Input Fields**. Click **Add** as given above to see:
  
-{{http://docs.cacti.net/files/images/r-dim3_0.png|Add new Input Field}}+{{:manual:087:r-dim3.png|Add new Input Field}}
  
 The DropDown **Field [Input]** contains one single value only. This is taken from the **Input String** <host> above. Fill **Friendly Name** to serve your needs. The **Special Type Code** allows you to provide parameters from the current **Device** to be queried. In this case, the **hostname** will be taken from the current device. The DropDown **Field [Input]** contains one single value only. This is taken from the **Input String** <host> above. Fill **Friendly Name** to serve your needs. The **Special Type Code** allows you to provide parameters from the current **Device** to be queried. In this case, the **hostname** will be taken from the current device.
 Click create to see: Click create to see:
  
-{{http://docs.cacti.net/files/images/r-dim4.png|Data Input Method with first Input Parameter}}+{{:manual:087:r-dim4.png|Data Input Method with first Input Parameter}}
  
 At least, define the **Output Fields**. Again, click **Add** as described above: At least, define the **Output Fields**. Again, click **Add** as described above:
  
-{{http://docs.cacti.net/files/images/r-dim5.png|Add new Output Field}}+{{:manual:087:r-dim5.png|Add new Output Field}}
  
 Provide a short **Field [Output]** name and a more meaningful **Friendly Name**. As you will want to save those data, select **Update RRD File**. Create to see: Provide a short **Field [Output]** name and a more meaningful **Friendly Name**. As you will want to save those data, select **Update RRD File**. Create to see:
  
-{{http://docs.cacti.net/files/images/r-dim6_0.png|Final Data Input Method}}+{{:manual:088:r-dim6_0.png|Final Data Input Method}}
  
 Click **Save** and you're done. Click **Save** and you're done.
Line 95: Line 115:
 Now you want to tell cacti, how to store the data retrieved from this script. Please go to **Data Templates** and click **Add**. You should see: Now you want to tell cacti, how to store the data retrieved from this script. Please go to **Data Templates** and click **Add**. You should see:
  
-{{http://docs.cacti.net/files/images/r-dt1.png|Add new Data Template}}+{{:manual:088:r-dt1.png|Add new Data Template}}
  
 Fill in the Data Templates **Name** with a reasonable text. This name will be used to find this Template among others. Then, please fill in the Data Source **Name**. This is the name given to the host-specific Data Source. The variable **|host_description|** is taken from the actual **Device**. This is to distinguish data sources for different devices. The **Data Input Method** is a DropDown containing all known scripts and the like. Select the Data Input Method you just created. The **Associated RRA's** is filled by default. At the moment there's no need to change this. The lower part of the screen looks like: Fill in the Data Templates **Name** with a reasonable text. This name will be used to find this Template among others. Then, please fill in the Data Source **Name**. This is the name given to the host-specific Data Source. The variable **|host_description|** is taken from the actual **Device**. This is to distinguish data sources for different devices. The **Data Input Method** is a DropDown containing all known scripts and the like. Select the Data Input Method you just created. The **Associated RRA's** is filled by default. At the moment there's no need to change this. The lower part of the screen looks like:
  
-{{http://docs.cacti.net/files/images/r-dt2.png|First Part of Data for new Data Template}}+{{:manual:088:r-dt2.png|First Part of Data for new Data Template}}
  
 The **Internal Data Source Name** may be defined at your wish. There's no need to use the same name as the Output Field of the Data Input Method, but it may look nicer. The **Internal Data Source Name** may be defined at your wish. There's no need to use the same name as the Output Field of the Data Input Method, but it may look nicer.
 Click create to see: Click create to see:
  
-{{http://docs.cacti.net/files/images/r-dt3.png|Internal Data Source Name for new Data Template}}+{{:manual:088:r-dt3.png|Internal Data Source Name for new Data Template}}
  
 Notice the new DropDown **Output Field**. As there is only one Output Field defined by our Data Input Method, you'll see only this. Here's how to connect the Data Source Name (used in the rrd file) to the Output Field of the Script. Click **Save** and you're done. Notice the new DropDown **Output Field**. As there is only one Output Field defined by our Data Input Method, you'll see only this. Here's how to connect the Data Source Name (used in the rrd file) to the Output Field of the Script. Click **Save** and you're done.
Line 112: Line 132:
 Now you want to tell cacti, how to present the data retrieved from this script. Please go to **Graph Templates** and click **Add**. You should see: Now you want to tell cacti, how to present the data retrieved from this script. Please go to **Graph Templates** and click **Add**. You should see:
  
-{{http://docs.cacti.net/files/images/r-gt1.png|Add new Graph Template}}+{{:manual:088:r-gt1.png|Add new Graph Template}}
  
 Fill in **Name** and **Title**. The variable **|host_description|** will again be filled from the Device's definition when generating the Graph. Keep the rest as is and **Create**. See: Fill in **Name** and **Title**. The variable **|host_description|** will again be filled from the Device's definition when generating the Graph. Keep the rest as is and **Create**. See:
  
-{{http://docs.cacti.net/files/images/r-gt2.png|Newly Created Graph Template}}+{{:manual:088:r-gt2.png|Newly Created Graph Template}}
  
 Now click **Add** to select the first item to be shown on the Graphs: Now click **Add** to select the first item to be shown on the Graphs:
  
-{{http://docs.cacti.net/files/images/r-gt3.png|Enter First Graph Item}}+{{:manual:088:r-gt3.png|Enter First Graph Item}}
  
 Select the correct **Data Source** from the DropDown, fill in a color of your liking and select AREA as a **Graph Item Type**. You want to fill in a **Text Format** that will be shown underneath the Graph as a legend. Again, **Create**: Select the correct **Data Source** from the DropDown, fill in a color of your liking and select AREA as a **Graph Item Type**. You want to fill in a **Text Format** that will be shown underneath the Graph as a legend. Again, **Create**:
  
-{{http://docs.cacti.net/files/images/r-gt4.png|Define First Graph Item}}+{{:manual:088:r-gt4.png|Define First Graph Item}}
  
 Notice, that not only an entry was made under **Graph Template Items**, but under **Graph Item Inputs** as well. Don't bother with that now. Lets fill some more nice legends, see: Notice, that not only an entry was made under **Graph Template Items**, but under **Graph Item Inputs** as well. Don't bother with that now. Lets fill some more nice legends, see:
  
-{{http://docs.cacti.net/files/images/r-gt5.png|Fill Legend for Graph Template}}+{{:manual:088:r-gt5.png|Fill Legend for Graph Template}}
  
 Notice, that the **Data Source** is filled in automagically. Select LEGEND as **Graph Item Type** (it is not really a Graph Item Type in rrdtool-speak, but a nice time-saver), and click **Create** to see: Notice, that the **Data Source** is filled in automagically. Select LEGEND as **Graph Item Type** (it is not really a Graph Item Type in rrdtool-speak, but a nice time-saver), and click **Create** to see:
  
-{{http://docs.cacti.net/files/images/r-gt6.png|Graph Template with Legend}}+{{:manual:088:r-gt6.png|Graph Template with Legend}}
  
 Wow! Three items filled with one action! You may want to define a **Vertical Label** at the very bottom of the screen and **Save**. Wow! Three items filled with one action! You may want to define a **Vertical Label** at the very bottom of the screen and **Save**.
Line 140: Line 160:
 Now go to the **Devices** and select the one of your choice. See the **Associated Graph Templates** in the middle of this page: Now go to the **Devices** and select the one of your choice. See the **Associated Graph Templates** in the middle of this page:
  
-{{http://docs.cacti.net/files/images/r-dev1.png|Devices AssDataQuery}}+{{:manual:088:r-dev1.png|Devices AssDataQuery}}
  
 Select your newly created Graph template from the **Add Graph Template** DropDown. Click **Add** to see: Select your newly created Graph template from the **Add Graph Template** DropDown. Click **Add** to see:
  
-{{http://docs.cacti.net/files/images/r-dev2.png|Added Graph Template}}+{{:manual:088:r-dev2.png|Added Graph Template}}
  
 The Template is added and shown as **Not Being Graphed**. On the top of the page you'll find the **Create Graphs for this Host** link. Click this to see: The Template is added and shown as **Not Being Graphed**. On the top of the page you'll find the **Create Graphs for this Host** link. Click this to see:
  
-{{http://docs.cacti.net/files/images/r-dev3.png|Creating Graph for new Graph Template}}+{{:manual:088:r-dev3.png|Creating Graph for new Graph Template}}
  
 Check the box that belongs to the new template and **Create**. See the results: Check the box that belongs to the new template and **Create**. See the results:
  
-{{http://docs.cacti.net/files/images/r-dev4.png|Newly Created Graph for this Host}}+{{:manual:088:r-dev4.png|Newly Created Graph for this Host}}
  
 This will automatically  This will automatically 
Line 161: Line 181:
 You'll have to wait at least for two polling cycles to find data in the Graph. Find your Graph by going to **Graph Management**, filtering for your host and selecting the appropriate Graph (there are other methods as well). This may look like: You'll have to wait at least for two polling cycles to find data in the Graph. Find your Graph by going to **Graph Management**, filtering for your host and selecting the appropriate Graph (there are other methods as well). This may look like:
  
-{{http://docs.cacti.net/files/images/graph1.png|New Graph after little time of polling}}+{{:manual:088:graph1.png|New Graph after little time of polling}}
  
 === Walkthrough: Script with more Output Parameters === === Walkthrough: Script with more Output Parameters ===
Line 261: Line 281:
 To define this script as a **Data Input Method** to cacti, please go to **Data Input Methods** and click **Add**.  To define this script as a **Data Input Method** to cacti, please go to **Data Input Methods** and click **Add**. 
  
-{{http://docs.cacti.net/files/images/dim-add01.preview.png|more-scripts_dim-add01}}+{{:manual:088:dim-add01.preview.png|more-scripts_dim-add01}}
  
 You should see: You should see:
  
-{{http://docs.cacti.net/files/images/dim-add02.preview.png|more-scripts_dim-add02}}+{{:manual:088:dim-add02.preview.png|more-scripts_dim-add02}}
  
 Enter the name of the new Data Input Method, select **Script/Command** and type in the command to call the script. Please use the **full path to the command interpreter**. Instead of entering the specific parameters, type **<symbolic variable name>** for each parameter the script needs. Save: Enter the name of the new Data Input Method, select **Script/Command** and type in the command to call the script. Please use the **full path to the command interpreter**. Instead of entering the specific parameters, type **<symbolic variable name>** for each parameter the script needs. Save:
  
-{{http://docs.cacti.net/files/images/dim-add03.preview.png|more-scripts_dim-add03}}+{{:manual:088:dim-add03.preview.png|more-scripts_dim-add03}}
  
 Now **Add** each of the input parameters in the **Input Fields** section, one after the other. All of them are listed in sequence, starting with <host>: Now **Add** each of the input parameters in the **Input Fields** section, one after the other. All of them are listed in sequence, starting with <host>:
  
-{{http://docs.cacti.net/system/files/images/dim-add04.preview.png|more-scripts_dim-add04}}+{{:manual:088:dim-add04.png|more-scripts_dim-add04}}
  
 <port> <port>
  
-{{http://docs.cacti.net/files/images/dim-add05.png|more-scripts_dim-add05}}+{{:manual:088:dim-add05.png|more-scripts_dim-add05}}
  
 <community> <community>
  
-{{http://docs.cacti.net/files/images/dim-add06.preview.png|more-scripts_dim-add06}}+{{:manual:088:dim-add06.preview.png|more-scripts_dim-add06}}
  
 <version> <version>
  
-{{http://docs.cacti.net/files/images/dim-add07.png|more-scripts_dim-add07}}+{{:manual:088:dim-add07.png|more-scripts_dim-add07}}
  
 We've used some of cacti builtin parameters. When applied to a host, those variables will be replaced by the hosts actual settings. Then, this command will be stored in the poller_command table. Now **Save** your work to see We've used some of cacti builtin parameters. When applied to a host, those variables will be replaced by the hosts actual settings. Then, this command will be stored in the poller_command table. Now **Save** your work to see
  
-{{http://docs.cacti.net/files/images/dim-add08.preview.png|more-scripts_dim-add08}}+{{:manual:088:dim-add08.preview.png|more-scripts_dim-add08}}
  
 After having entered all **Input Fields**, let's now turn to the **Output Fields**, respectively. Add the first one, udpInDatagrams: After having entered all **Input Fields**, let's now turn to the **Output Fields**, respectively. Add the first one, udpInDatagrams:
  
-{{http://docs.cacti.net/files/images/dim-add09.preview.png|more-scripts_dim-add09}}+{{:manual:088:dim-add09.preview.png|more-scripts_dim-add09}}
  
 Now udpOutDatagrams: Now udpOutDatagrams:
  
-{{http://docs.cacti.net/files/images/dim-add10.preview.png|more-scripts_dim-add10}}+{{:manual:088:dim-add10.preview.png|more-scripts_dim-add10}}
  
 Be careful to avoid typos. The strings entered here must **exactly** match those spitted out by the script. **Double check Output Fields!** Now, results should be like Be careful to avoid typos. The strings entered here must **exactly** match those spitted out by the script. **Double check Output Fields!** Now, results should be like
  
-{{http://docs.cacti.net/files/images/dim-add11.preview.png|more-scripts_dim-add11}}+{{:manual:088:dim-add11.preview.png|more-scripts_dim-add11}}
  
 Finally **Save** and be proud! Finally **Save** and be proud!
  
-{{http://docs.cacti.net/files/images/dim-add12.preview.png|more-scripts_dim-add12}}+{{:manual:088:dim-add12.preview.png|more-scripts_dim-add12}}
  
 === The Data Template === === The Data Template ===
Line 315: Line 335:
 Now, let's enter the first data source. Again, its like above. But we now provide the name of **udpInPackets**, enter a **Maximum value** of 100,000 and select the **Data Source Type** of COUNTER. Now, let's enter the first data source. Again, its like above. But we now provide the name of **udpInPackets**, enter a **Maximum value** of 100,000 and select the **Data Source Type** of COUNTER.
  
-{{http://docs.cacti.net/files/images/DataSource-udpInPackets.preview.png|Data Template - Two DS, Step1}}+{{:manual:088:DataSource-udpInPackets.preview.png|Data Template - Two DS, Step1}}
  
 Then save and find Then save and find
  
-{{http://docs.cacti.net/files/images/DataSource-udpInPackets2.preview.png|Data Template - Two DS, Step2}}+{{:manual:088:DataSource-udpInPackets2.preview.png|Data Template - Two DS, Step2}}
  
  
 Add the second data source by hitting **New** and provide data for **udpOutPackets**. Pay attention to select the correct **Output Field** defined by the Data Input Method. Add the second data source by hitting **New** and provide data for **udpOutPackets**. Pay attention to select the correct **Output Field** defined by the Data Input Method.
  
-{{http://docs.cacti.net/files/images/DataSource-udpOutPackets.preview.png|Data Template - Two DS, Step3}}+{{:manual:088:DataSource-udpOutPackets.preview.png|Data Template - Two DS, Step3}}
  
 Please pay attention, as **Maximum Value** for second and following data sources defaults to 100! In most cases, this value won't fit. To deactivate maximum checking, enter **0**, else the desired number. Do not forget to select the correct **Data Source Type** and the **Output Field**. Please pay attention, as **Maximum Value** for second and following data sources defaults to 100! In most cases, this value won't fit. To deactivate maximum checking, enter **0**, else the desired number. Do not forget to select the correct **Data Source Type** and the **Output Field**.





Personal Tools