Probes v9

A probe is a scheduled task that retrieves information about the database objects that are being monitored by the PEM agent. PEM uses the collected information to build the graphs displayed on each homepage. The Management > Manage Probes tab allows you to modify the data collection schedule and the length of time that PEM retains information returned by a specific probe.

System probes

Unless otherwise noted, Postgres Enterprise Manager enables the following probes at the server, database, schema, extension (starting with version 8.4), or agent levels:

EDB Postgres Distributed (PGD) probes

To monitor the EDB Postgres Distributed group using dashboards, you must enable the following probes. Configure these probes at extension level.

The user with pgd_superuser can view information from all the following probes. If you are using a version of EDB Postgres Distributed earlier than 4.0, all these probes work with EDB Postgres Distributed Enterprise Edition.

Customizing probes

A probe is a scheduled task that returns a set of performance metrics about a specific monitored object. A probe retrieves statistics from a monitored server, database, operating system, or agent. You can use the Manage Probes tab to override the default configuration and customize the behavior of each probe.

To open the Manage Probes tab, select Management > Manage Probes. The Manage Probes tab provides a set of icons that you can use to create and manage probes:

• Select Manage Custom Probes to open the Custom Probes tab and create or modify a custom probe.
• Select Copy Probes to open the Copy Probe dialog box and copy the probe configurations from the currently selected object to one or more monitored objects.

A probe monitors a unique set of metrics for each object type (server, database, database object, or agent). Select the name of an object in the tree to review the probes for that object.

To modify the properties associated with a probe, select the name of a probe and customize the settings that are displayed in the Probes table:

• Move the Default switch in the Execution Frequency columns to N to enable the Minutes and Seconds selectors, and specify a custom value for the length of time between executions of the probe.
• Move the Default switch in the Enabled? column to No to change the state of the probe and indicate if the probe is active or not.

• Move the Default switch in the Data Retention column to No to enable the Day(s) field and specify the number of days that information gathered by the probe is stored on the PEM server.

The Manage Probes tab might display information about probes that you can't modify from the current node. If you can't modify a probe from the current dialog box, the switches are disabled. Generally, you can modify a disabled probe from a node that's higher in the hierarchy of the PEM client tree control. Select another object in the tree control to modify the probes that are displayed or enabled in the Manage Probes tab.

Creating a custom probe

You can use the PEM Custom Probes tab to create a new probe or modify an existing custom probe. To open the Custom Probes tab, from the Manage Probes tab, select Manage Custom Probes.

Use the Show System Probes? switch to show or hide the system probes on the Custom Probes tab.

You can use the Custom Probes tab to create a probe or modify an existing one. To create a probe:

1. Select Add in the upper-right corner of the tab.
2. Provide a name for the new probe in the Probe Name column.
3. Select Edit (located to the left of the probe name) to review or add the probe definition.

Use 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. From the list, select:

  • SQL — The probe gathers information by way of a SQL statement.
  • WMI — The probe gathers information by way of a Windows Management Instrumentation extension.
  • Batch — The probe uses 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 to true. Then restart the PEM agent. The agent.cfg file is located in one of the following directories:

  • If you installed PEM using graphical installer: /opt/edb/pem/agent/etc/agent.cfg
  • If you installed PEM using RPM: /usr/edb/pem/agent/etc/agent.cfg

  On 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\EnterpriseDB\PEM\agent.

  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 the batch_script_user parameter of the agent.cfg file and specify the user to use to run the script. You can either specify a non-root user or root for this parameter. If you don't specify a user or the specified user doesn't exist, then the script doesn't run. Restart the agent after modifying the file.

  To invoke a script on a Windows system, set the registry entry for AllowBatchJobSteps to true and restart the PEM agent.

• Use the Target Type list to select the object type for the probe to monitor. Target Type is disabled if Collection method is WMI. Configure Target Type in probes to ensure that the collected metrics are relevant and accurate for the intended level of the system hierarchy. By setting the target type, you can effectively monitor various components, ranging from individual database objects like tables and indexes to server-wide monitoring.

  Target type configuration matrix

  The following table provides an overview of the target type configurations, their monitoring scope, and the mandatory fields for configuring them.

  In this table:

  • The Target type column determines the object you want to monitor with the probe.
  • The Execution level column determines if the monitoring probes execute once per database, per server, per agent, or per extension level.
  • The Mandatory columns column indicates the coloumns you must configure in the probe query to ensure the required data is collected.
  • The Probe examples column provides some existing probes you can explore to better understand how probes are used in practice.

  Target type	Execution level	Mandatory columns	Probe examples
  Agent	Agent	None	cpu_usage
  Server	Server	None	server_info
  Database	Database	None	database_size
  Schema	Database	schema_name	oc_extension
  Table	Database	schema_name, table_name	table_size
  Index	Database	schema_name, index_name	index_size
  Sequence	Database	schema_name, sequence_name	oc_sequence
  View	Database	schema_name, view_name	mview_size
  Function	Database	schema_name, arg_types, function_type, function_name	function_statistics
  Extension	Extension	None	bdr_node_summary

  Note

  • The custom probes set to a database or larger target type (including schema, table, index, view, sequence, and functions) collect the information at the database level.
  • The system probes set to a schema or larger target type collect the information up to the schema level.
  
  

  Proper configuration of the Target Type in probes ensures that the collected metrics are relevant and accurate for the intended level of the system hierarchy. By setting the appropriate target type, users can effectively monitor various components, from the server level down to individual database objects like tables and indexes.

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

• Use the Probe Enable? switch to specify if the probe in enabled by default. Specify Yes to enable the probe by default or No to disable the probe by default.

• Use the Data Retention field to specify the number of days that gathered information is retained in the probe's history table.
• Use the switch next to Discard from history to specify if the server creates 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 list to specify the type of platform that the probe monitors. This field is enabled only when the Collection method is Batch.

Use the Columns tab to define the columns in which to store the probe data. To define a new column:

1. Navigate to the Columns tab and select Add in the upper-right corner.
2. In the Name field, provide a column name.
3. Select Edit (to the left of the new column name) to provide information about the column:

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

• The Internal Name field isn't enabled for custom probes.

• Use the Column Type list 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 list to specify the type of data to store 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 can be graphed and to make the probe accessible from the Capacity Manager or Manage Charts dialog boxes.

• Use the Is PIT switch to specify whether to store the metric by point-in-time.

  Point-in-time metrics 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 aren't point-in-time (also referred to as cumulative metrics) are those 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 for the server to 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.

Use the Code tab to specify the default code for the propbe to execute:

• 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 Columns tab. The number of columns returned by the query, as well as the column name, data type, and so on, must match the information specified on the Columns tab.

• If the probe is a batch probe, you must specify the shell or .bat script to invoke when the probe runs. The output of the script is as follows:

  • The first line must contain the names of the columns provided on the Columns tab. Each column name must be separated by a tab (t) character. From the second line onwards, each line must contain the data for each column, separated by a tab character.

  • If a specified column is defined as a key column, make sure that the script doesn't produce duplicate data for that column across lines of output. The number of columns specified in the Columns tab and their names, data type, and so on must 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 must 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 Columns tab. The number of columns returned by the query, as well as the column name, data type, and so on, must match the information specified on the Columns tab.

Use the Alternate Code tab to provide code to invoke if the probe fires on a specific version of the server. To provide version-specific code, move the Applies to any server version? switch to No and select Add. Then, use the Database Version(s) list to select a version, and select Edit (to the left of the version name) to provide the code to execute when the probe fires.

If you select a database version and leave the Probe Code column blank, PEM invokes 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, select Save (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 or importing a probe

To export the probe, select any probes from the Manage Custom Probes tab, and then select Export in the upper-right corner of the table. To generate the JSON file, select Save File and then select OK.

To import the probe, on the Manage Custom Probes tab, select Import in the upper-right corner of the table. Select Browse to select the JSON file with the probe code to import, and then select Import.

After selecting the file to import, you can select the Skip existing check box. This option skips the probe if it already exists and displays a message letting you know that the import was skipped.

• If you don't select the check box and the probe already exists, then it doesn't import the probe and an error message is reported.

  !!! Note Import can't overwrite the existing probe as it might be configured to retain historical data as per the configured retention policy.

• If you don't select the check box and the probe doesn't exist but the corresponding table in the pem schema does, then it imports the probe successfully using the same table.

Deleting a probe

You can delete only custom probes. To delete a probe, select the probe name in the probes table, and select Delete (located to the upper-right corner of the table). The probe history persists for the length of time specified in 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 can only modify system probes. If you attempt to delete a system probe, PEM reports an error.

Copying a probe

You can use the Copy Probe Configuration dialog box to copy probe definitions from one monitored object to one or more monitored objects of the same type. To open the Copy Probe Configuration dialog box:

1. Un the PEM client tree, select the object from which you are copying probes.
2. Select Management > Manage Probes.
3. From the Manage Probes tab, select Copy Probe.

The dialog box copies the probe definitions from the object from which you opened the Copy Probe Configuration dialog box to the locations selected on the tree control.

If you specify a parent node in the Copy Probe Configuration tree, PEM copies the probe configurations to each object of the same type that resides under that node in the tree. For example, to copy the probe definitions from one schema to all schemas that reside in a database, select only the parent database of the target schemas. A red warning symbol is displayed to the left of the name of a listed target object if that object is the source of the probe that's being copied.

After you select the target object or objects, select Configure Probes to copy the probe definitions to the location selected in the dialog box.

Managing probes using pemworker

From version 9.6, you can enable and disable a probe using the pemworker utility using --probe-display-name, --probe-internal-name, or --probe-id option.

Examples

On Linux

This example shows how to disable a probe using the probe display name:

export PEM_SERVER_PASSWORD=edb
./pemworker --pem-user enterprisedb --disable-probe --probe-display-name "cpu usage"

Wed Mar 27 01:43:40 2024 INFO: Probe status updated for agent (id: 1)

This example shows how to enable a probe using the probe display name:

export PEM_SERVER_PASSWORD=edb
./pemworker  --pem-user enterprisedb --enable-probe --probe-display-name "database size"

Wed Mar 27 02:02:20 2024 INFO: Probe status updated for server (id: 1)

On Windows

This example shows how to disable a probe using the probe display name:

set PEM_SERVER_PASSWORD=edb
./pemworker.exe DISABLE-PROBE --pem-user postgres --probe-display-name "CPU usage"

INFO: Probe status updated for agent (id: 1)

This example shows how to enable a probe using the probe display name:

set PEM_SERVER_PASSWORD=edb
./pemworker.exe ENABLE-PROBE --pem-user postgres --probe-display-name "CPU usage"

INFO: Probe status updated for agent (id: 1)

PEM probes - reference

A probe is a scheduled task that retrieves information about the database objects that are being monitored by the PEM agent. PEM uses the collected information to build the graphs displayed on each dashboard. The Manage Probes tab (accessed from the Management menu) allows you to modify the data collection schedule and the length of time that PEM retains information returned by a specific probe.

• On this page
• System probes
• EDB Postgres Distributed (PGD) probes
• Customizing probes
• Managing probes using pemworker
• PEM probes - reference