Setting Up Enterprise Manager Plug-In for Oracle GoldenGate

2 Setting Up Enterprise Manager Plug-In for Oracle GoldenGate

After deploying the Enterprise Manager plug-in, there are a number of tasks that you must complete before you begin to use the plug-in to monitor the Oracle GoldenGate instances.

This topic details the following:

Topics

2.1 Configuring Oracle GoldenGate Instances for Enabling Monitoring in the Oracle Enterprise Manager

To configure your Oracle GoldenGate instances:

Configure the Oracle GoldenGate monitoring agent to run with Oracle Enterprise Manager. See Installing and Configuring Oracle GoldenGate Monitor Agent in Installing and Configuring Oracle GoldenGate Monitor Agent to configure the agent for the Oracle Enterprise Manager.
You need to do this configuration only for Oracle GoldenGate classic instance and is not required for Oracle GoldenGate microservices architecture (MA).
Create the Oracle Wallet to store passwords using the steps listed in Creating the Oracle Wallet.

2.1.1 Creating the Oracle Wallet

You must perform the following steps to create the Oracle Wallet and to add the password that the Oracle Management agent uses to connect to the Oracle GoldenGate agent to receive metric values.

This is applicable for the Oracle GoldenGate classic instance only as the Oracle GoldenGate monitoring agent is used by classic instance.

To create the Oracle Wallet:

Navigate to the OGG_AGENT_ORA_HOME directory.

Note:

Oracle GoldenGate 12c (12.1.2.0.0) introduced the storing of passwords for extract and replicats in Oracle Wallets. However, both the Oracle GoldenGate core replication and Oracle GoldenGate monitoring agent wallets cannot reside in the same location. If both Oracle GoldenGate core and the Oracle GoldenGate monitoring agent are using the Oracle Wallet then Oracle GoldenGate core must use a non-default location. This configuration can be set by using the GLOBALS parameter WALLETLOCATION.
Run the appropriate pw_agent_util script using the runtime argument specifying that you’re using only the Java agent (and not Oracle GoldenGate Monitor Server):
- Windows: Go to the command line and enter Shell> pw_agent_util.bat -jagentonly
- UNIX: Enter the command Shell>./pw_agent_util.sh -jagentonly
If a wallet doesn't exist, then one is created.
Enter and confirm the Oracle Enterprise Manager agent password when you see this prompt:

Please create a password for Java Agent:

Please confirm password for Java Agent:

Attention:

If a wallet already exists in the dirwlt directory, a message is returned and the utility stops. If this happens go to the next step.
Optional: Run the utility to create the Oracle GoldenGate Monitoring Agent password by entering one of the following commands. (Note that the command options are not case sensitive):

Caution:
Only perform this step if the wallet already exists in the dirwlt directory.
- Windows: Go to the command line and enter: Shell> pw_agent_util.bat -updateAgentJMX
- UNIX: Enter the command Shell> ./pw_agent_util.sh -updateAgentJMX

2.2 Discovering an Oracle GoldenGate Enterprise Manager Plug-in Processes

Discovery is a process, where an agent identifies pre-defined target types, registers them in the Oracle GoldenGate Enterprise Manager Plug-in, and collects their target properties and initial configuration data. The agent then sends this data to the Oracle Management Service (OMS), which processes the data and loads it into the Management Repository. After the targets are discovered, Oracle GoldenGate Enterprise Manager Plug-in can access data about the targets on the UI to monitor and manage the instances under a single roof.

The Oracle GoldenGate Enterprise Manager supports the following target types for Classic and Microservices (MA) instances. For more information about monitoring these target types, see Monitoring Oracle GoldenGate Targets.

Table 2-1 Target Types Supported

Target Type	Description	Classic (Supported-Yes/No)	Microservices(Supported - Yes/No)
Oracle GoldenGate	Oracle GoldenGate target type represents an Oracle GoldenGate classic instance. It's the parent target of Manager, Extract, and Replicat targets. It shows the cumulative status of all the processes in the Oracle GoldenGate instance excluding the Initial Load processes.	Yes. See Oracle GoldenGate.	No
Extract	The Extract target type enables the static extraction of data records from one database and loads those records to a trail file.	Yes	Yes. See Extract and Replicat.
Replicat	The Replicat target type reads the data from trail and applies the data to the target database.	Yes	Yes. See Extract and Replicat.
Manager	The Manager target type instantiates the Oracle GoldenGate processes, allocates port numbers, and performs file maintenance. This target type is a controller process.	Yes. See Manager.	No
Service Manager	The Service Manager target type is the central hub from where you can start and stop deployments, Administration Server, Distribution Server, Performance MetricsServer, and Receiver Server.	No	Yes. See Service Manager.
Administration Server	The Administration Server target type supervises, administers, manages, and monitors processes within an Oracle GoldenGate deployment.	No	Yes. See Administration Server.
Deployment	The Deployment target type enables connection with the Service Manager that helps in controlling all other services in Microservices.	No	Yes. See Deployment.
Performance Metrics Server	The Performance Metrics Server target type uses the metrics service to collect and store instance deployment performance results. This metrics collection and repository is separate from the administration layer information collection.	No	Yes
Distribution Server	The Distribution Server target type is a service that functions as a networked data distribution agent in support of conveying and processing data and commands in a distributed deployment. It is a high performance application that is able to handle multiple commands and data streams from multiple source trail files, concurrently.	No	Yes. See Distribution Server
Receiver Server	The Receiver Server target type is the central control service that handles all incoming trail files. It interoperates with the Distribution Server and provides compatibility with the classic architecture pump for remote classic deployments.	No	Yes. See Receiver Server.

This topic describes the following:

2.2.1 Prerequisites to Discover Secure Oracle GoldenGate Microservices Instances

Ensure to upload the SSL certificate to the Oracle Enterprise Manager Agent:

Go to the EMAgent location and run the emctl command for uploading the certificate. For example:
```
./emctl secure add_trust_cert_to_jks -password welcome -trust_certs_loc
      /<certification location>/rootCA_Cert.pem -alias <alias name of the certification>
```
This command adds the certificate to the following: $EMAGENT_BASE_LOCATION/sysman/config/montrust/AgentTrust.jks.

2.2.2 Discovering an Oracle GoldenGate Enterprise Manager Plug-in Classic Instance

Ensure that the plug-in has already been imported to the Enterprise Manager Cloud Control and deployed to the management agent.

To discover a Classic Instance of the Oracle GoldenGate Enterprise Manager Plug-in:

After logging in to the Oracle GoldenGate Enterprise Manager Plug-in, on the main page, select Setup, click Add Target, and then select Configure Auto Discovery to display the Setup Discovery page.
In Setup Discovery page, on the Targets tab, select a target and then click Discovery Modules to configure the discovery modules.
In the Discovery Module page that is displayed, select the Oracle GoldenGate Classic check box.
Click Edit Parameters to display the Edit Parameters: Oracle GoldenGate dialog box.
Enter the following information required to connect to the Oracle GoldenGate agent:
- Monitor Agent Host Name: Enter the hostname of the Oracle GoldenGate instance or Cluster Virtual IP (VIP) of high availability cluster environment (HA/RAC). For example, <agenthost>.us.oracle.com. The Monitor agent is a secure tunnel way, and therefore, these agent details are required to connect the Enterprise Manager and Oracle GoldenGate.
  
  Note:
  To monitor multiple Oracle GoldenGate instances where individual Oracle Enterprise Manager agent is installed on each of the same host as Oracle GoldenGate, do not use LOCALHOST.
  
  Note:
  For HA/RAC environments, when the targets are promoted, the host property of the targets is updated with Virtual IP. When these targets are relocated or failed over to another node, they are still accessible using the same monitoring details. This is because the Enterprise Manager agent continues to monitor the Oracle GoldenGate instance irrespective of where the Oracle GoldenGate instance is actually running.
- Monitor Agent User Name: Enter the Monitor agent user name. Enter the user credential that you have used while configuring the Monitor agent.
- Monitor Agent Password: Enter the Monitor agent password.
- Monitor Agent Port: Enter the port number of the agent host. For example, 5559.
Click OK when finished in the Edit Parameters page.
Click OK to go back to the Setup Discovery page.
Select the target host, click Discovered Targets, and then click Discover Now to discover targets, and click Yes in the Discover Now confirmation dialog box.
After the discovery is successful, click Close in the Confirmation dialog box.
To view the discovery logs in case of an error occurrence, select the target, click Diagnostic Details, select Oracle GoldenGate Classic, and the click Log from Agent.

You need to promote these discovered targets now. See Promoting Oracle GoldenGate Targets.

2.2.3 Discovering an Oracle GoldenGate Enterprise Manager Plug-in Microservices Instance

Ensure that the plug-in has already been imported to the Enterprise Manager Cloud Control and deployed to the management agent.

You can discover Oracle GoldenGate Microservices target as well as secure Microservices targets. See Prerequisites to Discover Secure Oracle GoldenGate Microservices Instances.

To discover a Microservices Instance of the Oracle GoldenGate Enterprise Manager Plug-in:

After logging in to the Oracle GoldenGate Enterprise Manager Plug-in, on the main page, select Setup, click Add Target, and then select Configure Auto Discovery to display the Setup Discovery page.
In Setup Discovery page, on the Targets tab, select a target and then click Discovery Modules to configure the discovery modules.
In the Discovery Module page that is displayed, select the Oracle GoldenGate Microservices check box.
Click Edit Parameters to display the Edit Parameters: Oracle GoldenGate dialog box.
Enter the following information required to connect to the Oracle GoldenGate agent:
- Service Manager Host Name: Enter the host name of the machine on which the Service Manager Service is installed. For example: adsvrmgr.us.oracle.com.
- Service Manager User Name: Enter the User Name which you have entered while installing the service manager.
- Service Manager Password: Enter the Service Manager Password.
- Service Manager Port: Enter the port number of the host. For example, 8050.
Click OK when finished in the Edit Parameters page.
Click OK to go back to the Setup Discovery page.
Select the target host and then click Discover Now to discover targets, and click Yes in the Discover Now confirmation dialog box.
After the discovery is successful, click Close in the Confirmation dialog box.
To view the discovery logs in case of an error occurrence, select the target, click Diagnostic Details, select Oracle GoldenGate Microservices, and the click Log from Agent.

You need to promote these discovered targets now. See Promoting Oracle GoldenGate Targets.

2.3 Promoting Oracle GoldenGate Targets

Once the targets are discovered successfully, you need to promote them in order to view and monitor the targets. After the targets are promoted, they are displayed on the OGG Home page.

To promote Oracle GoldenGate targets:

In the Targets on Host page click Discovered Targets to view a list of discovered targets.
From this list, select a target that you want to promote, and then click Promote to display the Custom Promotion for GoldenGate Targets page. In this page, you can deselect the processes, which are not required for promotion.

Note:
When you select any target, its parent targets are auto selected.
Click Promote in the Custom Promotion for GoldenGate Targets page.
Click Yes in the Confirmation dialog box if you want to manage agents.
After the promotion is sucessfully completed, click Close to display the Manage EM Agents for OGG instance page.
Select the Target Name and then click Submit.
An Information box is displayed indicating that the changes are submitted successfully.
Click OGG Home to display all the targets that are promoted.

Once a target is successfully promoted, the target is displayed on the Home page, and the Management Agent installed on the target host begins collecting metric data on the target. See Target Metrics Available on OGG Home Page.

For more details, see Discovering, Promoting, and Adding Targets

2.4 Verifying and Validating the Plug-in Deployment

Before verifying and validating the Enterprise Manager Plug-In for Oracle GoldenGate, you must promote the Oracle GoldenGate target that is found during auto-discovery.

For more details, see Discovering, Promoting, and Adding Targets in the Enterprise Manager Cloud Control Administrator's Guide.

To verify and validate that Enterprise Manager is properly monitoring the plug-in target:

Click Oracle GoldenGate target from the All Target page to open the Oracle GoldenGate Home Page.
Select Target, Monitoring and then Metric Collection Errors to verify that no metric collection errors are reported.
Select Target, Information Publisher Reports to view reports for the Oracle GoldenGate target type, and ensure that no errors are reported.
Select Target, Configuration, Last Collected. Ensure that the configuration data can be seen. If configuration data doesn’t immediately appear, click Refresh on the Latest Configuration page.

2.5 Configuring Instance-Level Security

Enterprise Manager provides instance-level security flexibility to provide target-level privileges to administrators.

For example, if an Enterprise Manager Plug-In for Oracle GoldenGate is managing three Oracle GoldenGate (OGG) instances (for example, OGG1, OGG2, and OGG3), a user can be granted privileges to any of these instances and their sub-targets (that is, their OGG processes).

To grant target-level access:

Log in as a super admin (for example, sysman).
Select Setup, Security, Administrators to open the Administrators page.
Select the User for whom you need to modify the access.
Ensure that you have the target types Host, Agent, Oracle GoldenGate (in case of a classic instance), and Oracle GoldenGate Service Manager (in case of a Microservices instance)
Click Edit to modify access for an existing user.
Click Create/Create Like to create a new user and to assign the appropriate user roles to display the Properties tab.
Enter the required credentials for the new user, and click Next to open the Create Administrator userName: Roles page.

This page lets you to assign roles to the named user by moving the role from the Available Roles column to the Selected Roles column.

Select one or more roles from the Available Roles list and click Move to add them to the new user.

At a minimum, you must select the EM_BASIC_SUPPORT_REP role in addition to the preselected roles. This table shows the different roles.

RM Role Name	Edit/View Parameter	View Report	View Discard
EM_ALL_ADMINISTRATOR	Yes	No	No
EM_ALL_OPERATOR	Yes	No	No
EM_ALL_VIEWER	No	No	No
PUBLIC	No	No	No
EM_PLUGIN_USER	No	No	No

Do not select any ALL roles in this step, such as EM_ALL_ADMINISTRATOR, EM_ALL_OPERATOR, and so on, else the user role you’re creating will be entitled to all OGG instances.

Enterprise Manager (EM) supports object-level access control so administrators can be given roles for specific targets only. See Creating Roles for Systems Infrastructure Administration in the Enterprise Manager Cloud Control Administrator’s Guide.

Click Next to open the Target Privileges page.
Select the Target Privileges tab, scroll down to the Target Privileges section and select the Execute Command Anywhere and Monitor Enterprise Manager roles, and then click Add.

These two roles are required for full functionality and multi-version support.
Scroll below the Privileges Applicable to All Targets table to the Target Privileges section. This section gives the Administrator the right to perform particular actions on targets. Click Add to open the Search and Add: Targets page appears in a new browser window.
Ensure to add the targets Host (in case of classic) or Agent (MA) appropriately based on the the instnaces.
Select the instances you want the user to have access.

Remember:
You’re only assigning Oracle GoldenGate instances at this time. You’re not assigning Manager, Extract, or Replicat processes.

Here is an example of two Oracle GoldenGate instances ( port numbers 5559 and 5560). Access to only one of them (port number 5560) is being assigned to this user.

Description of the illustration inst_sec_select_target.gif
Click Select to save the changes.

You’re returned to the Add Targets page and the Target Privileges list is refreshed to show your selection.

Click the Edit Individual Privileges link under the Manage Target Privilege Grants Column, which is the third-last column from the right, to set the required privileges for the target.

Select from the following privileges:

Privilege Name	Description
Full	Perform all operations on the target, including delete the target.
View contents of OGG report file	View content of the report files for OGG targets.
View contents of OGG discard file	View content of the discard files for OGG targets.
Run OGG command	Run OGG commands (`Start`, `Stop`, `Kill`, and `Resume`) for OGG targets. You can also select these control operations from the Target drop-down list in the Oracle GoldenGate Home page. Select a control operation to display a confirmation dialog box. Once you click Yes in the confirmation dialog box, the action is sent to Oracle GoldenGate Core for execution. The dialog box refreshes automatically to check the progress of the command. An Error or Success of the command is displayed in the same dialog box. When you click OK, the Home page is refreshed with the latest status of the target.
Edit OGG parameter file	Edit parameter files for OGG targets.
Connect Target	Connect and manage target.

Don’t select both the Full and Connect Target privileges because Full includes Connect Target .

Click Continue.
Click Review to review your user's privileges, then click Finish.
The user now has access to the selected instance(s). The priviliges available for all targets are:
- Edit any OGG Parameter File
- Run any OGG command
- View contents of any OGG discard file
- View contents of any OGG report file
These privileges are automatically assigned from top to bottom in the hierarchy. For example, if the Run any OGG Command privilege is assigned to an OGG instance, it’s automatically assigned to all its child processes. However, you can also provide process specific privileges. Suppose the Edit any OGG parameter file privilege is assigned to a process, it’s specific to that process and is not assigned to other processes in the instance.
Test the instance-level security to confirm that all edited processes are operating with their assigned privileges:
1. Log in as the newly created or edited user.
2. Select Targets, GoldenGate to open the Oracle GoldenGate page.
3. Confirm that only the OGG instances that you have access to are visible.
4. Log out and log in again as root.
5. Select Targets, GoldenGate to open the Oracle GoldenGate page.
6. You should now see all the managed OGG instances.

For more details, see Security Overview in the Cloud Control Security Guide.

2.5.1 Authorizing Users with Permissions

As an administrator user, you can provide the following permissions to the users: Editing an Oracle GoldenGate parameter file, running an Oracle GoldenGate command, viewing the contents of any Oracle GoldenGate discard file, and viewing contents of any Oracle GoldenGate report file.

To provide permissions to the users:

Log in as a super admin (for example, sysman).
The super admin user can create Named Credentials for the Monitoring Agent (in case of classic instances) and Monitoring Credentials for Service Manager Agent (in case of MA instances). The super admin user grants permissions to the users. The user, after logging in to the Enterprise Manager Cloud Control with the new user credentials can then set the corresponding credentials based on the type of instances
Select Setup, Security, Administrators to open the Administrators page.
Click Edit to modify access for an existing user.
Click Next to display the Privileges applicable to all Targets page to view all the four permissions.
Select the required permission and click Submit.

Note:

The buttons are disabled for the users if they don't have the required permission. For example, if the user doesn't have Edit Parameters permission, then the Edit button in the Configuration tab for all the targets is disabled.
If the users are already logged-in and their permissions are changed by the super administrator, then new permissions are reflected in the user interface (UI) once the logged-in user refreshes the page.
If you happen to remove permissions for a logged-in user who has the command privileges, then when the user clicks any of the command buttons, such as Start, Stop, Kill, or Resume, then an error message is displayed that says that the user doesn't have sufficient permissions.

2.6 Monitoring the High Availability Features

This topic explains the monitoring of High Availability features for Oracle GoldenGate Management Pack. For the High Availability feature to properly function with Oracle GoldenGate plug-in, virtual IP (not the physical IP) of the Oracle GoldenGate host must be provided at the time of Oracle GoldenGate target discovery.

There can be two scenarios where High Availability is required:

Oracle GoldenGate instance is failed over from one node to another in the cluster: In this scenario, the existing Master Agent continues monitoring the Oracle GoldenGate instance in a seamless manner and the Host Name parameter in the Oracle GoldenGate Manager page displays the physical host name of the new node.
Current Master Agent stops functioning: In this scenario, the EM Agents that are currently running, must be marked as Slave for this Oracle GoldenGate instance. When the current Master Agent stops functioning, one of the Slave agents is assigned as Master for the Oracle GoldenGate instance, and monitoring continues.

This procedure uses both the Oracle Enterprise Manager Cloud Control portal and a console connection.

Start Oracle Enterprise Manager Cloud Control.
Login using the provided credentials.

The user must have sysman privilege.
Select Setup, Manage Cloud Control, Agents to open the Agents page.

All the agents are listed on this page.
Select Targets, GoldenGate.
Select Setup, Add target, Configure Auto Discovery.
Select the host and click Discovery Modules to provide credentials details by selecting Goldengate discovery.
See Discovering an Oracle GoldenGate Enterprise Manager Plug-in Processes.
Click Discovered Targets for a particular Agent Host Name.
The dialog lists all the targets on hosts, select a particular host.
1. Click Promote to promote the particular process to display a confirmation dialog box (that says Do You Want to Manage Agents now?) when the promotion process is completed.
2. In the confirmation dialog box, click Yes to Manage Agents.
  
  Note:
  You can bypass the Manage Agents page that displays a confirmation page. By bypassing this page, the promotion of the Oracle GoldenGate targets happens quickly.
Click Submit from the Manage Agents page to display a confirmation page. However, this is an optional step.

This page displays after successful completion of the promotion of the targets. It includes the recently promoted Oracle GoldenGate instance with a list of all EM agents where Oracle GoldenGate plug-in is deployed.

The agent through which these targets were discovered and promoted, is shown as Master for this Oracle GoldenGate instance. All other agents are marked as None, which means that they’re not associated with this Oracle GoldenGate instance. You can select any number of these agents as Slave, and click Submit to save the changes.

If you don't want to make any such changes, you can click Oracle GoldenGate Home and navigate back to the Oracle GoldenGate plug-in home page.

After the process promotion, you can see the promoted target in the Oracle GoldenGate Home page.
If you want to start, stop, or kill the process, then navigate to the corresponding process page and then select appropriate controls.
Click Targets, select GoldenGate, and then select the process, which you want to either start or stop.
You can select any of the processes, such as Extract, Replicat, or Data Pump to start or stop.

The status of the Oracle GoldenGate processes is reflected according to the option you selected (Start/Stop/Kill) and it gets reflected in both the OGG Home page as well as Process Details page. Click Refresh to view the updates.