Creating custom probes v10.3

You can use the Manage Probes tab to create a new custom probe or modify an existing custom probe.

From the Manage Probes tab, select plus icon on the top-right toolbar to create a custom probe:

1. Use the General tab to specify the properties of a new probe:

• Use the 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/Shell Script — 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 /usr/edb/pem/agent/etc/ directory.

  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 specify either 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 won'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 columns 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.
  
  

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

• Use the Enabled? toggle button to specify if the probe is enabled or disabled by default. If you enable the probe, it starts collecting data at the specified interval. If you disable the probe, it doesn't collect data until you enable it.

• Use the Data Retention field to specify the number of days that gathered information is retained in the probe's history table.

• Use the Discard from history toggle button 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.

2. 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 plus icon in the upper-right corner to add a column.

   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? toggle button 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? toggle button 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? toggle button 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.

3. Use the Code tab to specify the default code for the probe 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.

4. 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 all database server version? switch to No and select plus icon on the top-right corner to add a specific version. 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 executes on that version.

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.