Managing a PEM agent v9

Managing job notifications

In the PEM console, you can configure the settings for sending the SMTP trap on success or failure of a system-generated job listed under scheduled tasks or a custom agent job. You can configure these email notification settings at the following three levels to send email notifications to the specified user group. These levels are shown in order of precedence.

• Job level
• Agent level
• PEM server level (default)

Configuring job notifications at job level

You can configure email notification settings at job level only for a custom agent job in one of the following ways:

• For a new agent job, you can configure the email notification settings in the Notification tab of the Create Agent Job wizard while creating the job.
• For an existing custom job, you can edit the properties of the job and configure the notification settings.

Use the Notifications tab to configure the email notification settings on job level:

• Use the Send the notifications field to specify when you want to send the email notifications.
• Use the Email group field to specify the email group to send the email notification to.

Configuring job notifications at agent level

Select the agent in the tree view, right-click, and select Properties. In the Properties dialog box, select the Job Notifications tab.

Use the Job notifications tab to configure the email notification settings at agent level:

• Use the Override default configuration? switch to specify if you want the agent level job notification settings to override the default job notification settings. Select Yes to enable the rest of the settings on this dialog box to define when and to whom to send the job notifications.
• Use the Email on job completion? switch to specify whether to send the job notification when the job completes successfully.
• Use the Email on a job failure? switch to specify whether to send the job notification when the job fails.
• Use the Email group field to specify the email group to send the job notification to.

Configuring job notifications at server level

You can use the Server Configuration dialog box to provide information about your email notification configuration at PEM server level. To open the Server Configuration dialog box, select Management > Server Configuration.

Four server configuration parameters specify information about your job notification preferences at PEM server level:

• Use the job_failure_notification switch to specify if you want to send an email notification after each job failure.
• Use the job_notification_email_group parameter to specify the email group to send the email notification to.
• Use the job_retention_time parameter to specify the number of days to retain nonrecurring scheduled tasks in the system.
• Use the job_status_change_notification switch to specify if you want to send an email notification after each job status change, that is, failure, success, or interrupted.

Managing PEM scheduled jobs

You can create a PEM scheduled job to perform a set of steps you define in the specified sequence. These steps can contain SQL code or a batch/shell script that you can run on a server that's bound with the agent. You can schedule these jobs to suit your business requirements. For example, you can create a job for taking a backup of a particular database server and schedule it to run on a specific date and time of every month.

To create or manage a PEM scheduled job, use the PEM tree to browse to the PEM agent for which you want to create the job. The tree displays a Jobs node, under which currently defined jobs are listed. To add a job, right-click the Jobs node and select Create Job from the context menu.

Use the tabs on the Create - Agent Job dialog box to define the steps and schedule that make up a PEM scheduled job.

Use the General tab to provide general information about a job:

• Provide a name for the job in the Name field.
• Set the Enabled switch to Yes to enable a job. Set it to No to disable a job.
• Use the Comment field to store notes about the job.

Use the Steps tab to define and manage the steps that the job performs. Select Add (+) to add a step. Then, select the compose icon, located at the left side of the header, to open the Step Definition dialog box.

Use the Step Definition dialog box to define the step:

• Provide a name for the step in the Name field. Steps are performed in alphanumeric order by name.

• Use the Enabled switch to include the step when executing the job (True) or to disable the step (False).

• Use the Kind switch to indicate if the job step invokes SQL code (SQL) or a batch script (Batch).

  • If you select SQL, use the Code tab to provide SQL code for the step.
  • If you select Batch, use the Code tab to provide the batch script to execute during the step.

• Use the On error list to specify the behavior of pgAgent if it encounters an error while executing the step. Select from:

  • Fail — Stop the job if you encounter an error while processing this step.
  • Success — Mark the step as completing successfully and continue.
  • Ignore — Ignore the error and continue.

• If you selected SQL as your input for the Kind switch:

  • Use the Server field to specify the server that's bound with the agent for which you are creating the PEM scheduled job.
  • Use the Database field to specify the database that's associated with the server that you selected.

• Use the Comment field to provide a comment about the step.

• Use the context-sensitive field on the Step Definition dialog box Code tab to provide the SQL code or batch script to execute during the step:

  • If the step invokes SQL code, provide one or more SQL statements in the SQL query field.

  • If the step invokes a batch script, provide the script in the Code field. If you're running on a Windows server, use standard batch file syntax. On a Linux server, you can use any shell script, provided that you specify a suitable interpreter on the first line (such as #!/bin/sh). Along with the defined inline code, you can also provide the path of any batch script, shell script, or SQL file on the filesystem.

    • To invoke a script on a Linux system, you must modify the entry for the batch_script_user parameter in the agent.cfg file and specify the user who runs the script. You can specify either a nonroot 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 execute. 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. PEM registry entries are located in HKEY_LOCAL_MACHINE\Software\Wow6432Node\EnterpriseDB\PEM\agent.

After providing all the information required by the step, select Save.

Select Add (+) to add each step, or select the Schedules tab to define the job schedule.

On the Schedules tab, select Add (+) to add a schedule for the job. Then select the compose icon located at the left side of the header to open the Schedule Definition dialog box.

Use the Schedules definition tab to specify the days and times for the job to execute.

• Provide a name for the schedule in the Name field.
• Use the Enabled switch to indicate for pgAgent to use the schedule (Yes) or to disable the schedule (No).
• Use the calendar selector in the Start field to specify the starting date and time for the schedule.
• Use the calendar selector in the End field to specify the ending date and time for the schedule.
• Use the Comment field to provide a comment about the schedule.

Select the Repeat tab to define the days when the schedule executes in a cron-style format. The job executes on each date or time element selected on the Repeat tab.

In each field, select a value to add it to the list of selected values for the field. To clear the values from a field, select the X located at the right-side of the field.

• Use the fields in the Days box to specify the days when the job executes:
  • Use the Week Days field to select the days when the job executes.
  • Use the Month Days field to select the numeric days when the job executes. Select Last Day to perform the job on the last day of the month, regardless of the date.
  • Use the Months field to select the months when the job executes.
• Use the fields in the Times box to specify the times when the job executes in hours and minutes.

Select the Exceptions tab to specify any days when you don't want the schedule to execute. For example, you might not want to run jobs on holidays.

Select Add (+) to add a row to the exception table. Then:

• In the Date column, open a calendar selector and select a date when you don't want the job to execute. Specify **<Any>** to indicate that you don't want the job to execute on any day at the time selected.
• In the Time column, open a time selector and specify a time when you don't want the job to execute. Specify **<Any>** to indicate that you don't want the job to execute at any time on the day selected.

Select the Notifications tab to configure the email notification settings on job level:

• Use the Send the notifications field to specify when you want to send the email notifications.
• Use the Email group field to specify the email group to send the email notification to.

When you finish defining the schedule, you can use the SQL tab to review the code that creates or modifies your job.

Select Save to save the job definition.

After you save a job, the job is listed under the Jobs node of the PEM tree of the server on which it was defined. The Properties tab in the PEM console displays a high-level overview of the selected job, and the Statistics tab shows the details of each run of the job. To modify an existing job or to review detailed information about a job, right-click a job name, and select Properties from the context menu.

Agent privileges

By default, the PEM agent is installed with root privileges for the operating system host and superuser privileges for the database server. These privileges allow the PEM agent to invoke unrestricted probes on the monitored host and database server about system usage, retrieving and returning the information to the PEM server.

PEM functionality lessens as the privileges of the PEM agent decrease. For complete functionality, run the PEM agent as root. If the PEM agent is run under the database server's service account, PEM probes don't have complete access to the statistical information used to generate reports, and functionality is limited to the capabilities of that account. If the PEM agent is run under another lesser-privileged account, functionality is limited even further.

If you limit the operating system privileges of the PEM agent, some of the PEM probes don't return information, and the following functionality might be affected.

If you restrict the database privileges of the PEM agent, the following PEM functionality might be affected:

If the probe is querying the operating system without enough privileges, the probe might return a permission denied error. If the probe is querying the database without enough privileges, the probe might return a permission denied error or display the returned data in a PEM chart or graph as an empty value.

When a probe fails, an entry is written to the log file that contains the name of the probe, the reason the probe failed, and a hint that helps you resolve the problem.

You can view probe-related errors that occurred on the server in the Probe Log dashboard or review error messages in the PEM worker log files. On Linux, the default location of the log file is:

/var/log/pem/worker.log

On Windows, log information is available on the Event Viewer.

Agent configuration

A number of configurable parameters and registry entries control the behavior of the PEM agent. You might need to modify the PEM agent's parameter settings to enable some PEM functionality. After modifying values in the PEM agent configuration file, restart the PEM agent to apply any changes.

With the exception of the PEM_MAXCONN parameter, we strongly recommend against modifying any of these configuration parameters or registry entries without first consulting EDB support experts unless you need the modifications to enable PEM functionality.

On Linux systems, PEM configuration options are stored in the agent.cfg file, located in /usr/edb/pem/agent/etc. The agent.cfg file contains the following entries.

On 64-bit Windows systems, PEM registry entries are located in:

HKEY_LOCAL_MACHINE\Software\Wow6432Node\EnterpriseDB\PEM\agent

The registry contains the entries shown in the table.

About alert threads

The number of alert threads spawned by an agent is determined by the alert_threads or AlertThreads parameter. In general, we recommend setting this parameter to 1 on the agent that resides on the PEM server and 0 for all other agents. However, on PEM server instances with very large numbers of alerts (caused by many monitored servers, many enabled alerts, or high alert frequency), it may be necessary to increase this parameter if alerts are not being evaluated at the configured frequency. In this situation, we recommend setting this parameter to around 8 on the agent that resides on the PEM server and 0 for all other agents and tuning up or down accordingly.

When tuning this parameter, it is important to understand that any agent can process any alert, so in general it is unnecessary to have a non-zero number of alert threads on more than one agent. The capacity of the PEM instance to process alerts is determined by the total number of alert thread across all agents. Increasing the number of threads on a specific agent does not give any additional performance for alerts pertaining to servers monitored by that agent.

Each alert thread opens a connection to the PEM server backend, so allocating more threads than necessary does result in additional memory and CPU usage on the PEM server.

Agent properties

The PEM Agent Properties dialog box provides information about the PEM agent from which the dialog box was opened. To open the dialog box, right-click an agent name in the PEM client tree and select Properties from the context menu.

Use the PEM Agent Properties dialog box to review or modify information about the PEM agent:

• The Description field displays a modifiable description of the PEM agent. This description is displayed in the tree of the PEM client.

• You can use groups to organize your servers and agents in the PEM client tree. Use the Group list to select the group in which the agent is displayed.

• Use the Team field to specify the name of the group role that can access servers monitored by the agent. The servers monitored by this agent are visible in the PEM client tree to connected team members. This is a convenience feature. The Team field doesn't provide true isolation. Don't use it for security purposes.

• The Heartbeat interval fields display the length of time that elapses between reports from the PEM agent to the PEM server. Use the selectors next to the Minutes or Seconds fields to modify the interval.

  Use the Job Notifications tab to configure the email notification settings on agent level:

  • Use the Override default configuration? switch to specify if you want the agent level job notification settings to override the default job notification settings. Select Yes to enable the rest of the settings on this dialog box to define when and to whom to send the job notifications.
  • Use the Email on job completion? switch to specify whether to send the job notification when the job completes successfully.
  • Use the Email on a job failure? switch to specify whether to send the job notification when the job fails.
  • Use the Email group field to specify the email group to send the job notification to.

  The Agent Configurations tab displays all the current configurations and capabilities of an agent.

  • The Parameter column displays a list of parameters.
  • The Value column displays the current value of the corresponding parameter.
  • The Category column displays the category of the corresponding parameter. It can be either configuration or capability.

• On this page
• Managing job notifications
• Managing PEM scheduled jobs
• Agent privileges
• Agent configuration
• Agent properties