Custom Probes

Use the Custom Probes tab to create a new probe or modify an existing probe. After creating or modifying a probe, you can incorporate the data gathered by custom probes into existing or new charts or graphs. To open the Custom Probes tab, select the Manage Custom Probes icon from the Quick Links section of the Manage Probes tab.

Custom Probes

Use the Show system probes? switch to display the system probes on the Custom Probes tab.

To modify an existing probe, click the Edit icon located to the left of a probe name.

Defining a New Probe

To create a new probe, click the Add icon in the upper-right corner of the tab.

Custom Probes - Add New Probe - General tab

Use the fields on the General tab to modify the definition of an existing probe or to specify the properties of a new probe.

• Use the Probe name field to provide a name for a new probe.

• Use the Collection method field to specify the probe type. Use the drop-down listbox to select from:

• SQL (the probe will gather information via a SQL statement)

• WMI (the probe will gather information via a Windows Management Instrumentation extension)

• Batch/Shell Script (the probe will use a command-script or shell-script to gather information).

  Before creating a batch probe on a Linux system, you must modify the agent.cfg file, setting the allow_batch_probes parameter equal to true and restart the PEM agent. The agent.cfg file is located in /opt/PEM/agent/etc.

  On 64-bit Windows systems, agent settings are stored in the registry. Before creating a batch probe, modify the registry entry for the AllowBatchProbes registry entry and restart the PEM agent. PEM registry entries are located in HKEY_LOCAL_MACHINE\\Software\\Wow6432Node\\EnterpriseDB\\PEM\\agent.

  Please note that batch probes are platform-specific. If you specify a collection method of Batch, you must specify a platform type in the Platform field.

  To invoke a script on a Linux system, you must modify the entry for batch_script_user parameter of agent.cfg file and specify the user that should be used to run the script. You can either specify a non-root user or root for this parameter. If you do not specify a user, or the specified user does not exist, then the script will not be executed. Restart the agent after modifying the file. If pemagent is being run by a non-root user then the value of batch_script_user will be ignored and the script will be executed by the same non-root user that is being used for running the pemagent.

• Use the Target type drop-down listbox to select the object type that the probe will monitor. Target type is disabled if Collection method is WMI.

• Use the Minutes and Seconds selectors to specify how often the probe will collect data.

• Use the Probe enable? switch to specify if the probe is enabled. Specify Yes to enable the probe, or No to specify that the probe is disabled.

• Set the Data retention switch to Yes to specify the number of days that gathered information will be retained in the probe’s history table.

• Use the switch next to Discard from history to specify if the server should create a history table for the probe. Select Yes to discard probe history, or No to retain the probe history in a table.

• Use the Platform drop-down listbox to specify the type of platform that the probe will monitor. This field is enabled only when the Collection method is Batch.

Custom Probes - Add New Probe - Columns tab

Use the Columns tab to define the columns in which the probe data will be stored. Navigate to the Columns tab, and click the Add button (in the upper-right corner) to define a new column.

• Provide a name for the column in the Name field.

• The Internal name field is not enabled for user-defined probes.

• Use the Column type drop-down listbox to specify if the column is a Key column (a primary key) or a Non key column. Non-key columns are generally metric items (values that can be graphed).

• Use the Data type drop-down listbox to specify the type of data that will be stored in the column.

• Use the Unit field to specify the unit of measure that applies to the metric stored in the column. This unit is displayed on the Y-Axis of a custom chart or a Capacity Manager chart. This is an optional field.

• Use the Graphable switch to specify if the defined metric may be graphed, and that the probe should be accessible from the Capacity Manager or Manage Charts dialogs.

• Use the Is PIT switch to specify if the metric is stored by point-in-time (by default).

  ‘Point-in-time’ metrics are those metrics that change (increase or decrease) at any given point of time. For example, database size is a point-in-time metric; at any given point-in-time, the size of the database is fluctuating. Metrics that are not point-in-time (also referred to as cumulative metrics) are metrics whose size always increases over time. For example, Blocks Read and Tuples Read are cumulative metrics; the value stays the same or increases.

• Use the Calculate PIT switch to specify that the server should calculate a point-in-time value for the metric data. Calculate PIT is disabled if Is PIT is Yes.

PEM allows you to store point-in time-values of cumulative metrics as well. PEM subtracts the last collected value of a cumulative metric from the current value, and stores the difference as a point-in-time value.

Custom Probes - Add New Probe - Code tab

Use the Code tab to specify the default code that will be executed by the probe.

• If the probe is a SQL probe, you must specify the SQL SELECT statement invoked by the probe on the Code tab. The column names returned by the query must match the Internal Name specified on the Column tab. The number of columns returned by the query, as well as the column name, datatype, etc. must match the information specified on the Columns tab.

• If the probe is a Batch probe, you must specify the shell or .bat script that will be invoked when the probe runs. The output of the script should be as follows:

• The first line must contain the names of the columns provided on the Columns tab. Each column name should be separated by a tab (t) character.

• From the second line onwards, each line should contain the data for each column, separated by a tab character.

• If a specified column is defined as key column, make sure the script does not produce duplicate data for that column across lines of output.

• The number of columns specified in the Columns tab and their names, data type, etc. should match with the output of the script output.

• If the probe is a WMI probe, you must specify the WMI query as a SELECT WMI query. The column name referenced in the SELECT statement should be same as the name of the corresponding column specified on the Column tab. The column names returned by the query must match the Internal Name specified on the Column tab. The number of columns returned by the query, as well as the column name, datatype, etc. must match the information specified on the Columns tab.

Custom Probes - Add New Probe - Alternate Code tab

Use the Alternate Code tab to provide code that will be invoked if the probe fires on a specific version of the server. To provide version-specific code, move the Applies to all database server versions? switch to No, and click the Add button. Then, use the Database version(s) drop-down listbox to select the version to which the code will apply. After selecting the version, click the Edit button (to the left of the version name) to provide the code that will execute when the probe fires.

If you select a database version, and leave the Probe code column blank, PEM will invoke the code specified on the Code tab when the probe executes on a server that matches that version.

When you’ve finished defining the probe, click the Save icon (in the corner of the Custom Probes tab) to save the definition, and make the probe data available for use on custom charts and graphs.

Exporting and Importing Probes

From PEM 8.2 onwards, you can export and import the probes to another PEM Server.

To Export the probe, select any probe/s from the Manage Custom Probes tab and then select the Export icon in the upper-right corner of the table. Select Save File option and then select ok, it will generate the JSON file.

Custom Probes - Export

To Import the probe, go to the Manage Custom Probes tab and then select the Import icon in the upper-right corner of the table.

Custom Probes - Import

Click on the Browse button to select the JSON file with the probe code to be imported and then click Import.

Custom Probes - Import Browse

After selecting the file to import you can select the skip existing checkbox. If selected then it will skip the probe if it already exists.

If the checkbox is selected and the probe already exists, then it skips importing the probe with the message as below:

Custom Probes - Import Skipped Message

If the checkbox is not selected and the probe already exists, then it does not import the probe and throws the below error:

Custom Probes - Import Error

Note

Import cannot overwrite the existing probe as it may be configured to retain historical data as per the configured retention policy.

If the checkbox is not selected and probe does not exist but the corresponding table in the pem schema exists, then it imports the probe successfully using the same table.

Custom Probes - Import Successful

Note

It is possible that probe is deleted and not listed on Manage Custom Probe tab, but still the table holding the data of that probe exists in the pem schema.

Deleting Probes

You may delete only user-defined probes. To delete a probe, select the probe name in the probes table, and select the Delete icon (located to the upper-right corner of the table). The probe history will persist for the length of time specified on the History Retention field in the probe definition. During the deletion the probe definition is deleted and any corresponding tables are dropped from the pemdata and pemhistory schemas.

System probes are the built-in probes provided by PEM, and are part of the PEM schema. You may only modify system probes; if you attempt to delete a system probe, you will receive an error from PEM.