Oracle® Cloud
Deploying and Managing Oracle Management Cloud Agents
E61067-24
July 2017
Documentation for adding and managing Oracle Management
Cloud entities.
Oracle Cloud Deploying and Managing Oracle Management Cloud Agents,
E61067-24
Copyright © 2015, 2017, Oracle and/or its affiliates. All rights reserved.
Primary Author: Oracle Corporation
Contributors: Oracle Corporation
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,
any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are
"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agencyspecific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the
programs, including any operating system, integrated software, any programs installed on the hardware,
and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.
No other rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron,
the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro
Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless
otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates
will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party
content, products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents
Preface ............................................................................................................................................................... vii
Audience ......................................................................................................................................................
vii
Related Resources .......................................................................................................................................
vii
Conventions................................................................................................................................................
viii
1 Introduction to Oracle Management Cloud Administration
Understanding Oracle Management Cloud Roles...............................................................................
1-1
Read This Before You Begin ....................................................................................................................
1-2
Roadmap for Agent Deployment Tasks ................................................................................................
1-2
2 Deploying Oracle Management Cloud Agents
Overview of the Deployment Process ...................................................................................................
2-1
Meeting the Prerequisites ........................................................................................................................
2-2
Common Prerequisites for Deploying Oracle Management Cloud Agents ............................
2-3
Prerequisites for Deploying a Gateway ...................................................................................... 2-11
Prerequisites for Deploying a Data Collector............................................................................. 2-12
Prerequisites for Deploying a Cloud Agent ............................................................................... 2-16
Deploying the Oracle Management Cloud Agents............................................................................ 2-17
Downloading the Master Installer ............................................................................................... 2-18
Deploying the Gateway................................................................................................................. 2-19
Deploying the Data Collector ....................................................................................................... 2-25
Deploying Cloud Agents............................................................................................................... 2-33
Verifying the Deployment of Gateways, Data Collectors, and Cloud Agents .............................. 2-40
Agent Install and Upgrade Logs .......................................................................................................... 2-41
Setting Up Debug Logs.................................................................................................................. 2-42
3 Setting Up Oracle Management Cloud
Setting Up Infrastructure Monitoring ...................................................................................................
3-1
Getting Started With the Oracle Infrastructure Monitoring Service.........................................
3-1
Adding Infrastructure Monitoring Entities ..................................................................................
3-2
Before You Begin Using Infrastructure Monitoring....................................................................
3-2
Setting Up Log Analytics.........................................................................................................................
3-3
iii
Getting Started With the Log Analytics Service ..........................................................................
3-3
Adding Log Analytics Entities .......................................................................................................
3-4
Creating Groups ...............................................................................................................................
3-4
Before You Begin Using Log Analytics .........................................................................................
3-4
Setting Up IT Analytics............................................................................................................................
3-5
Getting Started With the Oracle IT Analytics Service.................................................................
3-5
Adding IT Analytics Entities ..........................................................................................................
3-6
Setting Up Application Performance Monitoring................................................................................
3-6
Setting Up APM Java Agents..........................................................................................................
3-7
Setting Up APM .Net Agents........................................................................................................ 3-46
Setting Up APM Node.js Agents.................................................................................................. 3-55
Setting Up APM Ruby Agents...................................................................................................... 3-64
Setting up APM on Mobile Clients .............................................................................................. 3-69
Setting up APM on Mobile Containers ....................................................................................... 3-73
Troubleshooting the Deployment of Application Performance Monitoring......................... 3-75
Transferring Data through Reverse Proxy.................................................................................. 3-78
4 Upgrading and Deleting the Oracle Management Cloud Agents
Roadmap for Routine Administration Tasks........................................................................................
4-2
About Upgrading Oracle Management Cloud Agents .......................................................................
4-2
Upgrading Oracle Management Cloud Agents ...................................................................................
4-4
Removing Data Collectors.......................................................................................................................
4-5
Removing Cloud Agents and Gateways ...............................................................................................
4-6
Managing Registration Keys ...................................................................................................................
4-6
About Creating Registration Keys .................................................................................................
4-6
Creating a Registration Key ............................................................................................................
4-7
Downloading a Registration Key...................................................................................................
4-7
Revoking a Registration Key ..........................................................................................................
4-8
Managing APM Agents ...........................................................................................................................
4-8
Upgrading APM Java Agents .........................................................................................................
4-8
Removing APM Java Agents ..........................................................................................................
4-9
Removing APM .Net Agent.......................................................................................................... 4-10
Upgrading APM Node.js Agents ................................................................................................. 4-10
Removing APM Node.js Agents .................................................................................................. 4-12
Optional: Downloading the Master Installer on Demand ................................................................ 4-13
A Syntax for Using the APM Java Agent Installation Script
B Troubleshooting
C Modifying Proxy Server Settings
D Running the AgentInstall Script
iv
E omcli Command Options
v
vi
Preface
The Managing Oracle Management Cloud Entities guide provides information on
managing entities in the following Oracle Management Cloud services:
•
Application Performance Monitoring
•
Infrastructure Monitoring
•
IT Analytics
•
Log Analytics
This guide also provides information on performing administrative tasks.
Topics:
•
Audience
•
Related Resources
•
Conventions
Audience
This document is intended for the administrators of the following Oracle Management
Cloud services:
•
Application Performance Monitoring
•
Infrastructure Monitoring
•
IT Analytics
•
Log Analytics
Related Resources
For more information, see these Oracle resources:
•
http://cloud.oracle.com
•
About Application Performance Monitoring
•
Getting Started with Oracle Infrastructure Monitoring Cloud Service
•
About IT Analytics
vii
•
About Log Analytics
Conventions
This table describes the text conventions used in this document.
viii
Convention
Meaning
boldface
Boldface type indicates graphical user
interface elements associated with an action,
or terms defined in text or the glossary.
italic
Italic type indicates the book titles, emphasis,
or placeholder variables for which you
supply particular values.
monospace
Monospace type indicates commands within
a paragraph. URLs, code in examples, text
that appears on the screen, or text that you
enter.
1
Introduction to Oracle Management Cloud
Administration
As the administrator of an Oracle Management Cloud service, you subscribe to the
following services:
•
Application Performance Monitoring
•
Infrastructure Monitoring
•
IT Analytics
•
Log Analytics
•
Configuration and Compliance
•
Security Monitoring and Analytics
•
Orchestration
Topics:
•
Understanding Oracle Management Cloud Roles
•
Read This Before You Begin
•
Roadmap for Agent Deployment Tasks
Understanding Oracle Management Cloud Roles
The administration tasks described in this document can be performed only if you are
the administrator of your Oracle Management Cloud service. The following table lists
the Oracle Management Cloud services and their respective administrator roles.
Oracle Management
Cloud Service
Administrator Roles
Application
Performance
Monitoring
Application Performance Monitoring Administrator
Infrastructure
Monitoring
Infrastructure Monitoring Administrator
Log Analytics
Log Analytics Administrator
IT Analytics
IT Analytics Administrator
Introduction to Oracle Management Cloud Administration 1-1
Read This Before You Begin
Read This Before You Begin
Here are some of the common terms and basic concepts regarding agent deployment,
life cycle management, and onboarding.
Oracle Management Repository is a schema in an Oracle database where all of the
information collected by your on-premises Oracle Enterprise Manager Cloud Control
Management Agents is stored. It consists of objects such as database jobs, packages,
procedures, tables, views, tablespaces, and so on.
The master installer is a collection of files (typically a ZIP file) that contains software
installation scripts and other initial setup information documents.
An identity domain controls the authentication and authorization of the users who
can sign in to an Oracle Cloud service and what features they can access. An Oracle
Cloud service must belong to an identity domain. Multiple services can be associated
with a single identity domain to share user definitions and authentication. Users in an
identity domain can be granted different levels of access to each service associated
with the domain.
A registration key identifies the Oracle Cloud identity domain you have access to and
it is used to verify data sent by agents deployed on your on-premises hosts.
A gateway is an agent that acts as a proxy between Oracle Management Cloud and all
other cloud agents.
A data collector is an agent that reads data from the customer’s on-premises Oracle
Management Repository and uploads it to Oracle Management Cloud using a
gateway. A data collector also collects log information from targets.
A cloud agent collects Automatic Workload Repository (AWR) data from your
database hosts. A cloud agent also collects logs from your target hosts.
An APM Java Agent is a lightweight agent, which runs in the Java Virtual Machine
(JVM) of a web application and collects performance monitoring data for Java web
applications running in your data center or in the cloud.
Oracle Java Virtual Machine (JVM) is a standard, Java-compatible environment that
runs any pure Java application. It supports the standard Java binary format and the
standard Java APIs.
An HTTP proxy serves a client during a client-server communication, acts as the client
in order to prevent the end server from recording the location, or address, from which
the request originated.
On-premises Oracle Enterprise Management Agents are software components
deployed on monitored hosts. They are responsible for monitoring and managing all
of the targets running on those hosts, communicating that information to the middletier Oracle Management Service.
A Security Certificate, or a Digital Certificate, is an electronic document that proves
the ownership of a public key used for secure communication over a network.
An Oracle Wallet is a password-protected container used to store private keys,
certificates, and trusted certificates needed by secure communication between
software components.
Roadmap for Agent Deployment Tasks
This section is a roadmap of the agent deployment tasks that you can perform as the
administrator of your Oracle Management Cloud service.
1-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Roadmap for Agent Deployment Tasks
First-Time Deployment Task
More Information
Verify that all prerequisites for
agent deployment are satisfied.
This is a one-time activity.
Agents are service agnostic, so
once they have been deployed
(gateway, cloud, data collector),
they can be used for any
service.
Meeting the Prerequisites
Set up your Oracle
Management Cloud service.
This is a one-time activity.
•
•
•
•
Setting Up Application Performance Monitoring
Setting Up Infrastructure Monitoring
Setting Up Log Analytics
Setting Up IT Analytics
Introduction to Oracle Management Cloud Administration 1-3
Roadmap for Agent Deployment Tasks
1-4 Deploying and Managing Oracle Management Cloud Agents
2
Deploying Oracle Management Cloud
Agents
This section covers the following topics:
•
Meeting the Prerequisites
•
Deploying the Oracle Management Cloud Agents
•
Overview of the Deployment Process
Overview of the Deployment Process
This graphic shows all the Oracle Management Cloud (OMC) components and their
communication flow.
•
Software or hardware resources as well as business objects whose properties,
configuration, status and performance are tracked and analyzed are known to
OMC as entities. The cloud agents monitor and collect data (for example: metrics,
configuration information, logs) from entities that reside on hosts, or on virtual
hosts in a cloud. Typically, you deploy cloud agents on the same hosts as the
entities of interest. In some cases, cloud agents can also collect metrics for entities
on other hosts using various protocols that allow remote connections.
Deploying Oracle Management Cloud Agents 2-1
Meeting the Prerequisites
•
Even though cloud agents can directly transmit their data over the Internet to
OMC, for security reasons, many companies prefer to designate a specific type of
agent, called a gateway to serve as a proxy between OMC and all the cloud
agents. A gateway is an optional component and it is installed on a host that has
Internet access to Oracle Management Cloud and can be reached by all hosts
where cloud agents are deployed. All OMC services can use a common single
gateway.
•
A data collector reads data from an on-premises Oracle Enterprise Manager
Cloud Control Management Repository (OMR) and/or collects log information
from the Cloud Control managed targets. This repository data as well as logs are
then uploaded to Oracle Management Cloud. A data collector can communicate
directly with OMC or via a gateway and/or a proxy server. A data collector is
optional and it is deployed on a host with SSH and SQL access to the OMR. You
need to deploy a data collector only if you have an existing Oracle Enterprise
Manager setup and you wish to extract data/logs from it. Typically, a data
collector is installed on the OMR host since it adds only a small overhead. The
data collected can be used by the following the IT Analytics and Log Analytics
services.
•
Typical data centers will have a corporate proxy server or a firewall configured. In
this case, the OMC components mentioned above will need additional
configuration to take into account the communication through a proxy or a
firewall.
The various Oracle Management Cloud services use all, or a subset, of these
components as follows:
•
If deployed, a data collector collects different types of data from an Oracle
Management Repository, including target properties, configuration and
performance metrics, or events.
•
When cloud agents are installed on hosts, they automatically detect these hosts as
monitored entities. To enable monitoring, entities are added to cloud agents and
they become entities monitored by that particular cloud agent. Cloud agents then
collect status, performance, and configuration metrics for these entities.
Depending on their configuration, cloud agents also collect logs from their
entities.
•
The gateway authenticates the cloud agents in the client security service layer and,
if the cloud agents are found valid, receives the data and/or logs from the cloud
agents.
•
The gateway uploads the data and/or logs using a data pipeline, via a proxy/
firewall if configured, and stores them in the distributed file system of the Oracle
Management Cloud.
•
Individual Oracle Management Cloud services receive data from the common
distributed file system, and save it in their own service schema.
Meeting the Prerequisites
This section describes the prerequisites that must be met before the Oracle
Management Cloud agents are deployed.
It contains the following sections:
•
Common Prerequisites for Deploying Oracle Management Cloud Agents
2-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
•
Prerequisites for Deploying a Gateway
•
Prerequisites for Deploying a Data Collector
•
Prerequisites for Deploying a Cloud Agent
Common Prerequisites for Deploying Oracle Management Cloud Agents
Before deploying Oracle Management Cloud agents (gateways, data collectors, or
cloud agents) in your data center, ensuure that the following prerequisites are met:
•
General Prerequisites
•
Permissions Required for Installing Agent on Windows
•
Permissions Required On the Agent Base Directory
•
Supported Operating Systems and Software Packages
•
Network Prerequisites
•
Deploying the Oracle Management Cloud Agents Over a Proxy Server
•
Enabling Collection of Database Performance Data (IT Analytics)
General Prerequisites
•
If you have subscriptions to IT Analytics or Log Analytics, and if you want to
collect data from an existing on-premises Oracle Enterprise Manager setup, then
you need to have an existing deployment of any one of the following in your data
center.
–
Oracle Enterprise Manager Cloud Control 12.1.0.3
–
Oracle Enterprise Manager Cloud Control 12.1.0.4
–
Oracle Enterprise Manager Cloud Control 12.1.0.5
–
Oracle Enterprise Manager Cloud Control 13.1.0.x
–
Oracle Enterprise Manager Cloud Control 13.2.0.x
•
If you have subscriptions to all of the Oracle Management Cloud services, Oracle
recommends that you add them to the same identity domain.
•
When you’re deploying agents on UNIX-based hosts, root privileges are required,
or you have to log in as a user with root privileges to be able to run the root.sh
script (which is a part of the agent deployment process). Running root.sh as a
root user adds entries in the /etc/init.d file to restart the agent automatically
in case of server reboot. If you don’t wish to run root.sh post install or upgrade,
it will not hamper any functionality,and the script can also be run later. If you
have not run the script, when there is a server reboot, you must manually restart
the agent
•
For UNIX-based hosts, ensure that the cloud agent has the correct privileges to
read the log files from where data needs to be collected.
You can use either of the following ways (in order of best practice) to make the log
files readable to the cloud agent:
Deploying Oracle Management Cloud Agents 2-3
Meeting the Prerequisites
–
Use Access Control Lists (ACLs) to enable the cloud agent user to read the log
file path and log files. ACL provides a flexible permission mechanism for file
systems. Ensure that the full path to the log files is readable through ACL.
To set up an ACL in a UNIX-based host:
1.
Determine whether the system that contains the log files has the acl
package:
rpm -q acl
If the system contains the acl package, then the preceding command
should return:
acl-2.2.39-8.el5
If the system doesn’t have the acl package, then download and install
the package.
2.
Grant the cloud agent user read access to the required log file:
setfacl -m u:<agentuser>:r file <path to the log
file/log file name>
Grant the cloud agent user read access to the leading path or folders as
well by running the following command:
setfacl -d -m u:<agentuser>:r file <path to the parent
folder of the log file>
•
–
Place the cloud agent and the product that generates the logs in the same user
group, and make the files readable to the entire group.
–
Install the cloud agent as the user that also owns the logs. This is difficult to
achieve if there are a lot of different logs owned by different users on same
host.
–
Make log files readable to all users. For example, chmod o+r <file>
Ensure that you deploy the Oracle Management Cloud agents in the following
sequence
1.
Gateway
2.
Data Collector
3.
Cloud Agents
•
If you’ve already enrolled to an existing Oracle Management Cloud Service (such
as IT Analytics or Log Analytics), and if you enroll another service for the same
targets, then you can re-use the existing gateway, data collector, and cloud agents.
Additional cloud agents can be deployed only if you want to monitor new targets.
•
TLS 1.2 version is supported for OMC agents.
•
If you are installing the cloud agent for the first time, you need a CURL version
that supports the TLS 1.2 protocol. For steps on how to check the TLS protocol
version, see Troubleshooting.
Note: The TLS 1.2 protocol is not required if you are upgrading an agent.
2-4 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
•
While installing the agent, if the system hostname does not resolve to a fully
qualified domain name (FQDN), because you are not using DNS, then, add the
fully qualified domain name in the etc/hosts file and ensure that it maps to the
correct host name and IP address of the host. Ensure that the localhost is reachable
and resolves to 127.0.0.1. The recommended format is as follows:
<ip> <fully_qualified_host_name> <short_host_name>
For example:
If your hostname is "myhost" and your domain is example.com (IPv4):
172.16.0.0 myhost.example.com myhost
If your hostname is is "myhost" and your domain is example.com (IPv6):
aaaa::111:2222:3333:4444 myhost.example.com myhost
You can run the following commands to verify this. You should see the same
hostname and IP address displayed.
$getent hosts `hostname`
$host `hostname -f`
In the output, the fully qualified domain name must appear in the second field as
specified in the /etc/hosts file.
If you can ensure that short hostnames do not have the same value on different
hosts in your environment, you can ignore the FQDN requirement by pass the
following argument to the AgentInstall script:-ignorePrereqs with
ORACLE_HOSTNAME=<host_name>
•
Ensure that the noexec option has not been set on the agent home mount point. If
this parameter is set, the entire filesystem disallows execution. You can use the
$mount command or check the filesystem in the mount options (/etc/fstab) to
verify if the noexec option has been set.
•
Ensure that the agent install user has full control (read/write/delete permissions)
on the entire directory (including the base directory) in which the agent is being
installed. After installation, if you change the permissions in any of the directories,
agent life cycle operations such as update or delete will fail.
Permissions Required for Installing Agent on Windows
You must deploy agent on windows as administrator and ensure that necessary
permissions have been set as follows:
•
From the Start menu, click Settings, then click Control Panel. From the Control
Panel window, click Administrative Tools, and then click Local Security Policy.
Expand the Local Policies folder and open the User Rights Assignment folder
and set the following permissions:
–
Act as part of the operating system
–
Adjust memory quota for a process
–
Replace process level tokens
–
Log on as a batch job
Deploying Oracle Management Cloud Agents 2-5
Meeting the Prerequisites
Permissions Required On the Agent Base Directory
From the 1.19 release, when an agent is upgraded, you need not run the root.sh
script after the upgrade to restart the agent host machine. A symbolic link is defined in
the Agent Base directory that points to the latest version of the Agent Oracle Home
directory. Due to this, the Agent Base directory must have the following permissions:
•
The agent install user must be the owner of the directory.
•
Either the root user or the agent install user can be the owner of the agent base
parent directories.
•
Only the owners of the Agent Base directory and its parent directories should
have the write permissions on those directories.
Supported Operating Systems and Software Packages
This section covers the list of supported operating systems and software packages that
are required for deployment of gateways, data collectors, and cloud agents on the
target hot. requirements for deploying Oracle Management Cloud Agents.
The following table provides definitions for small, medium, and large deployments.
Size
Number of Oracle Enterprise
Manager Agents in Your Data
Center
Number of Targets
Small
<100
<100
Medium
100-1,000
100-1,000
Large
>1,000
>1,000
Software Package Requirements (for Target Host) for Deploying Gateways, Data
Collectors, and Cloud Agents
The following table lists the software packages that are required for the target host.
Note: Oracle recommends that you use a curl version that supports the TLS
1.2 protocol.
Operating System
Required Packages
•
Red Hat Enterprise Linux 5 or
higher (64 bit)
•
•
•
•
•
•
libaio-0.3.106-3.2
glibc-common-2.5-34
setarch-2.0-1.1
sysstat-7.0.2-3.el5
rng-utils-2.0-1.14.1.fc6
libstdc++-4.1.2-44.el5
•
Red Hat Enterprise Linux 6 or
higher (64 bit)
•
•
•
libaio-0.3.107
glibc-common-2.12-1.7
sysstat-9.0.4
2-6 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
Operating System
Required Packages
•
Red Hat Enterprise Linux 7 or
higher (64 bit)
•
•
•
•
libaio-0.3.109-12.el7.x86_64
glibc-common-2.17-78
libstdc++-4.8.3-9
sysstat-7.0.2-12
•
Oracle Enterprise Linux 5 or
higher (64 bit)
•
•
•
•
libaio-0.3.109-12.el7.x86_64
glibc-common-2.17-78
libstdc++-4.8.3-9
sysstat-7.0.2-12
•
Oracle Enterprise Linux 6 or
higher (64 bit)
•
•
•
libaio-0.3.107
glibc-common-2.12-1.7
sysstat-9.0.4
•
Oracle Enterprise Linux 7 or
higher (64 bit)
•
•
•
•
libaio-0.3.109-12.el7.x86_64
glibc-common-2.17-78
libstdc++-4.8.3-9
sysstat-7.0.2-12
•
SUSE Linux Enterprise Server
11 (x86_64)
•
Oracle recommends that you use a curl version
that supports the TLS 1.2 protocol.
•
AIX 6.1 or higher
•
•
•
•
•
•
•
•
•
•
•
bos.adt.base(0.0)
bos.adt.lib(0.0)
bos.adt.libm(0.0)
bos.perf.libperfstat(0.0)
bos.perf.perfstat(0.0)
bos.perf.proctools(0.0)
rsct.basic.rte(0.0)
rsct.compat.clients.rte(0.0)
xlC.aix61.rte.(9.0.0.0)
xlC.rte.(9.0.0.0)
unzip 5.52
•
AIX 7.1 or higher
•
•
•
•
•
•
•
•
•
•
•
bos.adt.base(0.0)
bos.adt.lib(0.0)
bos.adt.libm(0.0)
bos.perf.libperfstat(0.0)
bos.perf.perfstat(0.0)
bos.perf.proctools(0.0)
rsct.basic.rte(0.0)
rsct.compat.clients.rte(0.0)
xlC.aix61.rte.(10.1.0.0)
xlC.rte.(10.1.0.0)
unzip 5.52
•
Solaris 10 or higher
•
SUNWbtool
Deploying Oracle Management Cloud Agents 2-7
Meeting the Prerequisites
Operating System
Required Packages
•
Solaris 11 or higher
•
•
•
•
•
•
•
•
SUNWbtool
SunWhea or system/header
SUNWlibm
SUNWlibms
SUNWsprot
SUNWtoo
SUNWlibC
SUNWcsl
•
Microsoft Windows 2008
Enterprise R2 (Intel 64-bit,
Developer) and higher
Microsoft Windows Server
2012 Standard (64 bit)
Microsoft Windows 2012
Standard R2 (Intel 64-bit,
Developer) and higher
•
Oracle recommends that you use a curl version
that supports the TLS 1.2 protocol.
•
•
Network Prerequisites
•
If you are unable to access the Oracle Management Cloud service or deploy the
cloud agents due to a firewall, add *.oraclecloud.com to permit outbound
communication.
•
To test the agent connectivity to OMC, run the following command on the host on
which the agent is to be deployed and specify the <tenant_id> and the
<data_center> as follows:
curl -I https://<tenant id>.<data center>/registry
curl -insecure -I https://<tenant id>.<data center>/registry
For example:
$ curl -I --insecure https://abc.itom.management.us2.oraclecloud.com/registry
HTTP/1.0 200 Connection established
HTTP/1.1 403 Forbidden
Date: Thu, 30 Mar 2017 13:59:00 GMT
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
X-ORACLE-DMS-ECID: 005IzCOIQRUAxGj5p3WByY0003In0000z6
APIGW: true
Cache-Control: no-cache,no-store
Content-Language: en
$ curl -I https://abc.itom.management.us2.oraclecloud.com/registry
HTTP/1.0 200 Connection established
HTTP/1.1 403 Forbidden
Date: Thu, 30 Mar 2017 13:59:03 GMT
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
X-ORACLE-DMS-ECID: 005IzCOU5wsAxGj5p3_AiY00045b0000zP
APIGW: true
Cache_Control: no-cache,no-store
Content Language: en
2-8 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
•
You can also ping or telnet the data center.
For example:
For US data center: ping itom.management.us2.oraclecloud.com
For Europe data center: ping itom.management.europe.oraclecloud.com
Deploying the Oracle Management Cloud Agents Over a Proxy Server
If you are trying to deploy the Oracle Management Cloud agents (or you need any
host to connect to Oracle Management Cloud) over a proxy server, set the proxy
variables, http_proxy and https_proxy on the host where you’re deploying the agents.
•
To set the proxy variables on Linux using Bash shell, follow these steps:
If you are trying to deploy the Oracle Management Cloud agents (or you need any
host to connect to Oracle Management Cloud) over a proxy server, set the proxy
variables, http_proxy and https_proxy on the host where you’re deploying
the agents.
1.
2.
3.
Run the following commands:
–
export http_proxy=http://www-hostname.abc.com:<port>/
–
export https_proxy=http://wwwhostname.example.com:<port>/
Before running the AgentInstall.sh script, in the terminal window, run
the following command to test that the environment variables are set:
–
echo $http_proxy http://wwwhostname.example.com:<port>/
–
echo $https_proxy http://wwwhostname.example.com:<port>/
If your proxy server requires a password, set the proxy variables as follows:
–
export http_proxy=http://<username>:<password>@wwwhostname.abc.com:<port>/
–
export https_proxy=http://<username>:<password>@wwwhostname.example.com:<port>/
The password cannot contain any special characters such as @.
4.
Create a file for the proxy details, let us call it agent.properties and add
the following parameters:
cat agent.properties
OMC_PROXYHOST=<Your proxy server address>
OMC_PROXYPORT=<Your proxy server port>
OMC_PROXYREALM=<Your proxy realm>
OMC_PROXYUSER=<Your proxy user name>
OMC_PROXYPWD=<Your proxy user password>
Once this file has been created, it can be used to deploy all cloud agents.
•
To set the proxy variables on Windows:
1.
Follow these steps:
Deploying Oracle Management Cloud Agents 2-9
Meeting the Prerequisites
2.
3.
4.
a.
Right-click My Computer, and then click Properties.
b.
Click the Advanced tab and then click Environment variables.
c.
Click New to add a new variable name and value and add the following
variables.
–
http_proxy=http://www-hostname.abc.com:<port>/
–
https_proxy=http://www-hostname.example.com:<port>/
Before running the AgentInstall.bat script, in the command prompt, run
the following command to test that the environment variables are set:
–
echo %http_proxy% http://wwwhostname.example.com:<port>/
–
https_proxy: http://<username>:<password>@wwwhostname.example.com:<port>/
If the proxy server requires a password, set the proxy variables as follows:
–
http_proxy: http://<username>:<password>@wwwhostname.abc.com:<port>/
–
https_proxy: http://<username>:<password>@wwwhostname.example.com:<port>/
Create a file for the proxy details, let us call it agent.properties. Check
whether the values of the proxy variables are set to your proxy server and
port values:
type agent.properties
OMC_PROXYHOST=<Your proxy server address>
OMC_PROXYPORT=<Your proxy server port>
OMC_PROXYREALM=<Your proxy realm>
OMC_PROXYUSER=<Your proxy user name>
OMC_PROXYPWD=<Your proxy user password>
Ensure that you pass the agent.properties file as a parameter to the
AgentInstall.sh or AgentInstall.bat script when you are deploying
a gateway, a data collector, or cloud agents over a proxy server.
Enabling Collection of Database Performance Data (IT Analytics)
If you want to collect database performance data for IT Analytics, you need to set the
following permissions on the cloud agent.
•
While deploying the cloud agent, ensure that cloud agent host user and the
Enterprise Manager on-premises agent host user are the same. This will allow the
user to connect to the database target using the Enterprise Manager monitoring
credentials and collect database performance data.
•
If the cloud agent host user is different but belongs to the same group as the
Enterprise Manager on-premises host user, the cloud agent host user must have
read permissions on the sysman/emd/targets.xml and sysman/config/
private.properties files. To grant read access, log in as the on-premises host
user and grant the following permissions:
2-10 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
cd $AGENT_HOME/agent_inst
installation directory
chmod g+x sysman
chmod g+x sysman/emd
chmod g+x sysman/config
# AGENT_HOME is the On Premise agent
When execution permission is granted, all users in the group will have view and
read access on the directory by default. If the permissions are not available, you
can grant them as follows:
cd $AGENT_HOME/agent_inst
# AGENT_HOME is the On Premise agent
installation directory
chmod g+r sysman/emd/targets.xml
chmod g+r sysman/config/private.properties
Prerequisites for Deploying a Gateway
Note: Before reviewing this section, ensure that the common prerequisites
listed in Common Prerequisites for Deploying Oracle Management Cloud
Agents have been met.
This section lists the key considerations and prerequisites for deploying gateways and
covers the following:
•
General Guidelines
•
Software and Hardware Prerequisites
General Guidelines
This section lists the general prerequisites for deploying a gateway:
•
You cannot deploy the gateway as a root user.
•
Deploying the gateway is an optional task. In your data center, if the hosts on
which you want to deploy cloud agents have access to Internet, either directly or
through a proxy server, then you can skip the task of deploying a gateway.
Typically, in large organizations that have an enterprise setup, access to Internet is
controlled, and only a few hosts are configured as gateways through which other
hosts access the Internet. This helps in ensuring the security of the setup against
malicious cyber attacks.
Software and Hardware Prerequisites
This section covers the following:
•
Sizing Guidelines for Deploying Gateways
•
System and Port Requirements for Deploying Gateways
Sizing Guidelines for Deploying Gateways
While reviewing the sizing guidelines, consider the following:
•
One gateway can be deployed for every 2000 cloud agents.
Deploying Oracle Management Cloud Agents 2-11
Meeting the Prerequisites
•
Use the Small category as a starting point for the hardware requirements. When
you expand your topology and infrastructure, and move from small to medium to
large deployment scenarios, ensure that you meet the required hardware
requirements.
The following table provides definitions for small, medium, and large deployments.
Size
Number of Oracle Enterprise
Manager Agents in Your Data
Center
Number of Targets
Small
<100
<100
Medium
100-1,000
100-1,000
Large
>1,000
>1,000
The following table lists the sizing guidelines for different deployment scenarios:
Size
CPU Consumption
Free Disk Space
Heap Size
Small
2%
50 GB
1 GB
Medium
2-3%
100 GB
1 GB
Large
20%
100 GB
4 GB
System and Port Requirements for Deploying Gateways
A gateway can be deployed on a standalone machine and does not require any onpremises Oracle Enterprise Manager Agent and the gateway host should have Internet
connectivity.
The following table lists the system requirements for a typical gateway deployment.
Supported Operating Systems and
Software Packages for Target Host
RAM
Kernel Parameters
Port Number
Refer to the Supported Operating Systems
and Software Packages for details.
8 GB
hard nofile 65536;
Ulimit value for max
user processes >=4000
Any available port number
Prerequisites for Deploying a Data Collector
Note: Before reviewing this section, ensure that the common prerequisites
listed in Common Prerequisites for Deploying Oracle Management Cloud
Agents have been met.
This section lists the key considerations and prerequisites for deploying data collectors
and covers the following:
•
General Guidelines
•
Software and Hardware Prerequisites
2-12 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
•
Selecting Specific Targets for Data Collection
•
Creating a Dynamic Group in Your On-Premises Enterprise Manager
General Guidelines
Follow these guidelines for deploying data collectors:
•
You can deploy the data collector without a gateway.
•
You can deploy the data collector on a host on which the OMR is present or on
another host. You do not require an Enterprise Manager agent to deploy the data
collector. Even if the data collector is to be deployed on a host other than the host
on which the OMR is present, the Enterprise Manager agent need not be present
on that host .
•
You can deploy the data collector on the host on which the Oracle Management
Repository (OMR) is present or on a remote host which has SSH access to the
OMR host
•
Before you deploy data collectors to access Oracle Real Application Cluster (RAC)
databases running the Oracle Management Repository (OMR), ensure that
–
The staging directory location specified for each RAC database node should
be the same as the location specified at the time of deploying the data
collector.
–
The Oracle database user should have read and write privileges on the
staging directory.
–
The Oracle Management Repository host user (with SSH privileges to the
Oracle Management Repository host) should have read write privileges on
the staging directory.
Software and Hardware Prerequisites
Sizing Guidelines for Deploying Data Collectors
The following table provides definitions for small, medium, and large deployments.
Size
Number of Oracle Enterprise
Manager Agents in Your Data
Center
Number of Targets
Small
<100
<100
Medium
100-1,000
100-1,000
Large
>1,000
>1,000
The following table lists the sizing guidelines for different data collector deployment
scenarios:
Size
CPU Consumption
Free Disk Space
Small
4%
10 GB
Medium
4%
15 GB
Deploying Oracle Management Cloud Agents 2-13
Meeting the Prerequisites
Size
CPU Consumption
Free Disk Space
Large
9%
20 GB
Note:
You may observe a temporary spike in the CPU consumption when the data
collector initializes for the first time after deployment.
The following table lists the impact of data collector deployment on Oracle
Management Repository:
Size
CPU Consumption
Impact of I/O Operations
Small
1%
Negligible
Medium
2%
Negligible
Large
2.5%
0.8%
Note:
If you have a data collector and Oracle Management Repository on same host,
then to calculate the CPU consumption, you need to add the values of the
CPU computation column from the preceding two tables.
System and Port Requirements
The following table outlines the system requirements for a typical data collector
deployment.
Supported
Operating Systems
and Software
Packages for Target
Host
RAM
Heap
Size
Kernel
Parameters
Oracle
Manageme
nt
Repository
Free Space
(Datafiles)
Oracle
Port Number
Manageme
nt
Repository
Free
Space (File
system)
Refer to Supported
Operating Systems
and Software
Packages for details.
8 GB
1536
MB
hard nofile
65536; Ulimit
value for max
user
processes
>=4000
2.5 GB
3 GB
Any available port
number
Selecting Specific Targets for Data Collection
Oracle Management Cloud allows you to collect data from selected targets. This helps
you view data from only the targets that you want to monitor, which in turn will allow
2-14 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Meeting the Prerequisites
you to troubleshoot problems faster. However, the option of collecting data from all
the targets and uploading the data to Oracle Management Cloud is still available.
The process of performing selective data collection is as follows:
1.
To collect data from a specific set of targets, you must create a dynamic group (See
Creating a Dynamic Group in your On-Premises Enterprise Manager) called
omcgroup in your on-premise Enterprise Manager Cloud Control that will
contain only those member targets whose data you want to collect and upload.
The Enterprise Manager Agent must also be part of the omcgroup.
If you had not created the omcgroupbefore the data collector was deployed, you
can create it after deployment and the targets in the newly created omcgroupwill
be included in the next data collection. You do not have to restart the data
collector.
2.
Deploy the Oracle Management Cloud agents in the following sequence:
•
Gateway
•
Data collector
•
Cloud agents
Creating a Dynamic Group in Your On-Premises Enterprise Manager
The owner of a dynamic group specifies the membership criteria during dynamic
group creation (or modification) and membership in the group is determined solely by
the criteria specified. Membership in a dynamic group cannot be modified directly.
Enterprise Manager automatically adds targets that match membership criteria when a
dynamic group is created. It also updates group membership as new targets are added
or target properties are changed and the targets match the group's membership
criteria.
To create a dynamic group:
1.
In your on-premises Enterprise Manager Cloud Control, from the Groups page,
click Create and then select Dynamic Group from the drop-down list. Alternately,
you can choose Add Target from the Setup menu and then select Group.
2.
On the General tab of the Create Dynamic Group page, enter omcgroup as Name
of the dynamic group you want to create. To create a regular dynamic group, the
View any Target system wide privilege is required as the group owner must be
able to view any target that can potentially match the membership criteria.
3.
In the Define Membership Criteria section, define the criteria for the dynamic
group membership by clicking Define Membership Criteria.
The Define Membership Criteria page appears where you can Add or Remove
properties of targets to be included in the group. Group members must match one
value in each of the populated target properties. Use the Member Preview section
to review a list of targets that match the criteria. Click OK to return to the General
page.
At least one of the criteria on the Define Membership Criteria page must be
specified. You cannot create a dynamic group without at least one of the target
types, on hosts or target properties specified. Use the following criteria for
dynamic groups:
Deploying Oracle Management Cloud Agents 2-15
Meeting the Prerequisites
•
Target type(s)
•
Department
•
On Host
•
Target Version
•
Lifecycle Status
•
Operating System
•
Line of Business
•
Platform
•
Location
•
CSI
•
Cost Center
•
Contact
•
Comment
4.
You can add or remove properties using the Add or Remove Target Properties
button on the Define Membership Criteria page.
5.
Click OK to create the dynamic group.
Prerequisites for Deploying a Cloud Agent
Note: Before reviewing this section, ensure that the common prerequisites
listed in Common Prerequisites for Deploying Oracle Management Cloud
Agents have been met.
This section lists the key considerations and prerequisites for deploying cloud agents
and covers the following:
•
General Prerequisites
•
Software and Hardware Prerequisites
General Prerequisites
Follow these guidelines for deploying cloud agents:
•
You cannot deploy the cloud agent as a root user.
•
An Enterprise Manager agent is not mandatory for deploying the cloud agent. But
if there is an existing on-premises Enterprise Manager in the data center, the cloud
agent can be deployed either on the host on which the Enterprise Manager agent
has been deployed or on any other host without the Enterprise Manager agent.
•
The user for deploying the cloud agent can be the same as the user for installing
the on-premises Oracle Enterprise Manager agent.
2-16 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
If an Enterprise Manager agent has been deployed on the host on which the
Oracle Management Cloud agent is to be deployed, it is recommended that the
OMC agent is installed under the same user as the Enterprise Manager agent. This
will allow the OMC agent to access information about the managed entities such
as databases, hosts, and so on.
If the OMC agent needs to be deployed under a different user than the Enterprise
Manager agent user, then the OMC Cloud Agent must have read access to the files
and directories under the AGENT_HOME directory of the Enterprise Manager
agent. Otherwise, the OMC agent will not be able to access information related to
Enterprise Manager managed entities.
Software and Hardware Prerequisites
Sizing Guidelines for Deploying Cloud Agents
The following table provides definitions for small, medium, and large deployments.
Size
Number of Oracle Enterprise
Manager Agents in Your Data
Center
Number of Targets
Small
<100
<100
Medium
100-1,000
100-1,000
Large
>1,000
>1,000
The following table lists the sizing guidelines for deploying cloud agents:
CPU Consumption
Heap Size
Free Disk Space
1.7%
512 MB
10 GB
System and Port Requirements for Deploying Cloud Agents
The following table outlines the system requirements to deploy the cloud agent.
Supported Operating
System and Software
Packages for Target
Host
RAM
Heap
Size
Kernel Parameters
Free Disk
Space
Port Number
Refer to Supported
Operating Systems and
Software Packages
4 GB
512
MB
hard nofile 65536;
Ulimit value for
max user processes
>=4000
10 GB
Any port in the range of
1830-1849
Deploying the Oracle Management Cloud Agents
This section contains the following topics
•
Downloading the Master Installer
•
Deploying the Gateway
•
Deploying the Data Collector
Deploying Oracle Management Cloud Agents 2-17
Deploying the Oracle Management Cloud Agents
•
Deploying Cloud Agents
•
Verifying the Deployment of Gateways, Data Collectors, and Cloud Agents
Downloading the Master Installer
Downloading the master installer is the first step in setting up your service. This is a
one-time activity. Download the master installer to a shared directory that can be
accessed by all target hosts where OMC agents will be deployed.
To download the master installer
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
The <Service Name> is listed in this page.
2. Click Launch <Service Name>.
The Welcome page of the Set up <Service Name> wizard is displayed.
3. Click Next.
The Plan page is displayed.
4. Review the information in this page.
5. Click Next.
6. Click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh : The installation script used to deploy Oracle
Management Cloud agents on a UNIX-based platform.
•
AgentInstall.bat : The installation script used to deploy Oracle
Management Cloud agents on a Windows platform.
•
Read Me file: A file containing instructions about how to use the
AgentInstall script to install agents on your target hosts.
7. Create a registration key that will be used during the time of deploying a new
agent. For more information about creating a registration key, see Creating a
Registration Key.
8. Click Done after the ZIP file is downloaded successfully.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use AgentInstall(1).zip.
See the list of parameters used while running AgentInstall.zip, and their
definitions in Parameters in the AgentInstall Script.
2-18 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
Deploying the Gateway
A gateway is an agent that acts as a proxy between Oracle Management Cloud and all
other cloud agents. Before you deploy the gateway, do the following:
•
Review the information in Common Prerequisites for Deploying Oracle
Management Cloud Agents
•
Check if the hosts on which you want to deploy cloud agents have access to
Internet, either directly or through a proxy server. If so, you can skip the task of
deploying a gateway. Typically, in large organizations that have an enterprise
setup, access to Internet is controlled, and only a few hosts are configured as
gateways through which other hosts access the Internet. This helps in ensuring the
security of the setup against malicious cyber attacks.
The following use cases are covered:
•
Parameters for Deploying the Gateway
•
Deploying the Gateway
•
Deploying the Gateway Over a Proxy Server
•
Deploying a Gateway From a Staged Location
•
Deploying a Gateway With Custom Certificates
•
Gateway High Availability Use Cases
Parameters for Deploying the Gateway
The following table lists the details that you will require for the deployment process:
Parameter
Description
AGENT_REGISTRATION_KEY
The actual value of the registration key that
you’ve created for running the install script.
See Creating a Registration Key.
AGENT_BASE_DIR
The absolute path to the location where the
cloud agent needs to be installed.
AGENT_PORT
Optional. The port the cloud agent binds to.
If the port number is not specified, an
available port in the range 3872 and 1830–
1849 is used.
Deploying the Gateway
To deploy a gateway, follow these steps:
1.
Identify a host in your data center with Internet access to Oracle Management
Cloud.
2.
Copy the master installer ZIP file to the host where you’ll deploy the gateway,
and then extract the ZIP file. Refer to Downloading the Master Installer for details.
Deploying Oracle Management Cloud Agents 2-19
Deploying the Oracle Management Cloud Agents
You can download the master installer once, and use the same installer for
deploying gateway, data collector and cloud agent.
3.
Go to the directory (in the host where you’ll deploy the gateway) where you
extracted the master installer ZIP file to. For example, if you extracted the installer
ZIP file to a directory named scratch/gway_agent. After the zip file has been
extracted, Agentinstall.sh will be present in the in the /scratch/
gway_agent/Agentinstall.sh directory. Navigate to the /scratch/
gway_agent directory and run the installer script.
4.
Run the installer script to deploy the gateway, as shown in the following example:
•
If you’re deploying the gateway on a UNIX-based host:
./AgentInstall.sh AGENT_TYPE=gateway
AGENT_REGISTRATION_KEY= <value of the registration key>
AGENT_BASE_DIR=<the absolute path to the agent base
directory, such as /abc/agents/gway_agent>
AGENT_PORT=<enter the port>
•
If you’re deploying the gateway on a Windows host, right-click and select
Run as administrator to open a command prompt and run the following:
AgentInstall.bat AGENT_TYPE=gateway
AGENT_REGISTRATION_KEY= <value of the registration key>
AGENT_BASE_DIR=<the absolute path to the agent base
directory, such as /abc/agents/gway_agent>
AGENT_PORT=<enter the port>
Note:
–
The AGENT_PORT parameter is optional. If the port number is not
specified, an available port will be automatically used.
–
The user installing the agent must have permissions to act as part of the
operating system, adjust memory quota for a process, replace process
level tokens, and log on as a batch job. To verify the permissions, from the
Start menu, click Settings, then click Control Panel. From the Control
Panel window, click Administrative Tools, and then click Local Security
Policy. Expand the Local Policies folder and open the User Rights
Assignment folder.
In the preceding example:
•
AGENT_TYPE is gateway.
•
AGENT_BASE_DIR is the directory where you placed the AgentInstall.sh
installer script in the host where you’ll deploy the gateway.
•
AGENT_PORT is the port that the gateway binds to. The recommended port
and port range are 3872 and 1830–1849 respectively.
.
•
AGENT_REGISTRATION_KEY is the actual value of the registration key that
you’ve created for running the install script. See Creating a Registration Key.
2-20 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
5.
(Only on UNIX-based hosts) As a root user, run the root.sh command from
AGENT_BASE_DIR:
#AGENT_BASE_DIR/core/1.0.0/root.sh
Verify the deployment of the gateway. For more information, see Verifying the
Deployment of Gateways, Data Collectors, and Cloud Agents.
Note:
•
If you’ve deployed curl in a non-default location, pass the CURL_PATH
parameter when deploying the gateway as in the following:
–
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=gateway
AGENT_REGISTRATION_KEY= <value of the registration
key that you had created> AGENT_BASE_DIR=<the
absolute path to the agent base directory, such
as /abc/agents/gway_agent> AGENT_PORT=<enter the
port> CURL_PATH=<the_absolute_path_to_the
curl_location>
–
On Windows hosts, right-click and select Run as administrator to
open a command prompt and run the following:
AgentInstall.bat AGENT_TYPE=gateway
AGENT_REGISTRATION_KEY= <value of the registration
key that you had created> AGENT_BASE_DIR=<the
absolute path to the agent base directory, such
as /abc/agents/gway_agent> AGENT_PORT=<enter the
port> CURL_PATH=<the_absolute_path_to_the
curl_location>
The default location of curl is /usr/bin.
Deploying the Gateway Over a Proxy Server
If you’re deploying the gateway over a proxy server, ensure that you perform the
steps listed in Common Prerequisites for Deploying Oracle Management Cloud
Agents and then run AgentInstall.sh or AgentInstall.bat with the
AGENT_PROPERTIES parameter set to the path to the agent.properties file as in
the following:
•
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=gateway AGENT_REGISTRATION_KEY=
<<value of the registration key that you had created>>
AGENT_PROPERTIES=<path to the agent property file that you
created> AGENT_BASE_DIR=<the absolute path to the agent base
directory, such as /abc/agents/gway_agent> AGENT_PORT=<enter
the port>
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
AgentInstall.bat AGENT_TYPE=gateway AGENT_REGISTRATION_KEY=
<value of the registration key that you had created>
Deploying Oracle Management Cloud Agents 2-21
Deploying the Oracle Management Cloud Agents
AGENT_PROPERTIES=<path to the agent property file that you
created> AGENT_BASE_DIR=<the absolute path to the agent base
directory, such as /abc/agents/gway_agent> AGENT_PORT=<enter
the port>
Deploying a Gateway From a Staged Location
You can deploy a gateway from a staged location by downloading the gateway bits in
the “stage only” mode. This is particularly useful when after downloading the installer
bits, you want to deploy the agent at a later time.
To deploy a gateway from a staged location, follow these steps:
1.
Download the gateway agent bits in “stage only” mode.
The zip file that is downloaded should be used only for deploying the
gateway .
Note:
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=gateway STAGE_LOCATION= <path
to the stage location> AGENT_REGISTRATION_KEY=<registration
key value> -download_only
On Windows hosts:
AgentInstall.bat AGENT_TYPE=gateway STAGE_LOCATION= <path to
the stage location> AGENT_REGISTRATION_KEY=<registration key
value> -download_only
2.
Deploy the gateway using the staged image.
On UNIX-based hosts:
cd <path to the stage location>
./AgentInstall.sh AGENT_TYPE=gateway AGENT_BASE_DIR=the
absolute path to the agent base directory
AGENT_REGISTRATION_KEY=<registration key value> -staged
On Windows hosts:
cd <path to the stage location>
AgentInstall.bat AGENT_TYPE=gateway AGENT_BASE_DIR=the
absolute path to the agent base directory
AGENT_REGISTRATION_KEY=<registration key value> -staged
Deploying a Gateway With Custom Certificates
If you’re deploying the gateway over a proxy server and your proxy server has custom
certificates, then do the following:
•
On UNIX-based hosts:
1.
Download the gateway agent bits in “stage only” mode.
./AgentInstall.sh AGENT_TYPE=gateway STAGE_LOCATION=
<path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
2-22 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
2.
Update the certificate in the downloaded agent bits.
cd <path to the stage location>
unzip gateway.zip agentcoreimage.zip
mkdir -p core/1.16.0/stage/sysman/config/server/trustedcerts
cp <your proxy certificate> core/1.16.0/stage/sysman/config/server/
trustedcerts/trustCertProxy
zip -u agentcoreimage.zip core/1.16.0/stage/sysman/config/server/
trustedcerts/trustCertProxy
zip -u gateway.zip agentcoreimage.zip
Note: Ensure that the certificate is in DER format.
3.
Deploy the gateway using the staged image.
cd <path to the stage location>
./AgentInstall.sh AGENT_TYPE=gateway AGENT_BASE_DIR=the
absolute path to the agent base directory
AGENT_REGISTRATION_KEY=<registration key value>
AGENT_PORT=<enter the port> -staged
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
1.
Download the gateway agent bits in the “stage only” mode.
AgentInstall.bat AGENT_TYPE=gateway STAGE_LOCATION= <the
absolute path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
2.
Update the certificate in the downloaded agent bits.
cd <path to the stage location>
unzip gateway.zip agentcoreimage.zip
mkdir -p core\1.16.0\stage\sysman\config\server\trustedcerts
copy <your proxy certificate> core\1.16.0\stage\sysman\config\server
\trustedcerts\trustCertProxy
zip -u agentcoreimage.zip core\1.4.0\stage\sysman\config\server\trustedcerts
\trustCertProxy
zip -u gateway.zip agentcoreimage.zip
3.
Deploy the gateway using the staged image.
cd <path to the stage location>
AgentInstall.bat AGENT_TYPE=gateway AGENT_BASE_DIR=<the
absolute path to the agent base directory>
AGENT_REGISTRATION_KEY=<registration key value>
AGENT_PORT=<enter the port> -staged
Gateway High Availability Use Cases
High availability of gateways is supported by configuring cloud agents with two or
more gateway URLs. High availability ensures that the cloud agent can connect to the
Oracle Management Cloud through the second gateway if the first gateway fails.
The following use cases are supported:
•
Adding Additional Gateways while Deploying the Cloud Agent
Deploying Oracle Management Cloud Agents 2-23
Deploying the Oracle Management Cloud Agents
You can deploy additional gateways while installing the cloud agent by passing
the ADDITIONAL_GATEWAYS parameter. Run the following command:
./AgentInstall.sh AGENT_TYPE=cloud_agent AGENT_BASE_DIR=<the
absolute path to the agent base directory>
AGENT_REGISTRATION_KEY=<registration key value>
GATEWAY_HOST=<gateway_host_1> GATEWAY_PORT<gateway_port_1>
ADDITIONAL_GATEWAYS=<https://
<gateway_host_2>:<gateway_port_2>
where:
•
–
gateway_host_1 is the host on which the first gateway is deployed.
–
gateway_port_1 is the port number of the host on which the first gateway
is deployed.
–
gateway_host_2 is the host on which the second gateway is deployed.
–
gateway_port_2 is the port number of the host on which the second
gateway is deployed.
Adding Additional Gateways to an Existing Cloud Agent
To deploy a cloud agent with a gateway and then add additional gateways ,
follow these steps:
1.
Run the following command to deploy the cloud agent with gateway:
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_BASE_DIR=<the absolute path to the agent base
directory> AGENT_REGISTRATION_KEY=<registration key
value> GATEWAY_HOST=<gateway_host_1>
GATEWAY_PORT=<gateway_port_1>
2.
Run the following command on the host on which you want to deploy the
second gateway:
./AgentInstall.sh AGENT_TYPE=gateway AGENT_BASE_DIR=<the
absolute path to the agent base directory>
AGENT_REGISTRATION_KEY=<registration key value>
3.
Run the following command to get the gateway URL.
./omcli status agent
For example: https://my.example.com:1838/test/main/
4.
Create a plain text file (gateway.txt) as follows:
vi gateway.txt
Insert the URL for the second gateway in the below format and save.
gatewayUrls=https://<gateway_host>:<gateway_port>
5.
Navigate to the /bin directory of the cloud agent and run the following
command to add the gateway:
./<agent_inst_dir>/bin/omcli add_gateway agent <full path
to the gateway.txt file>
2-24 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
1. Go to below path under gateway added above /agent_inst/sysman/
config/server/ Copy "importCert" file in below path under cloud agent
with naming convention : "trustCertGateway_<gateway-host-added abovewith-periods-replaced-by-underscores>_<gateway-port>. /agent_inst/
sysman/config/server/trustedcerts/ Example /agent_inst/sysman/
config/server/trustedcerts/trustCertGateway_slc10zax_us_oracle_com_3476
6.
Navigate the following path on the gateway host:
cd /<agent_inst_dir>/sysman/config/server/trustedcerts/
7.
Copy the server certificate to the cloud agent host under /<agent_inst>/
sysman/config/server/certificates/ with the following format:
trustCertGateway_<gateway-host-with-periods-replaced-byunderscores>_<gateway_port>
For example: /agent_inst/sysman/config/server/trustedcerts/
trustCertGateway_my_example_com_3476
8.
Stop and start the cloud agent as follows:
./omcli stop agent
./omcli secure agent
./omcli start agent
Deploying the Data Collector
This section discusses how to deploy a data collector.
From an UNIX-based host, you can use the following command to access Oracle
Management Repository:
ssh -l <the_username_to_log_in_as_on_Oracle_Management_Repository>
<Oracle_Management_Repository_host_IP_address>
Before you deploy the data collector, review the information in Prerequisites for
Deploying a Data Collector.
The following sections are covered:
•
Parameters for Deploying the Data Collector
•
Deploying the Data Collector
•
Locked Account Use Case
•
Upgrading to Enterprise Manager 13.x After Deploying the Data Collector
•
Deploying the Data Collector Over a Proxy Server
•
Deploying a Data Collector From a Staged Location
•
Deploying the Data Collector On Oracle Real Application Clusters
•
Modifying the Data Collector Connect String or SSH Port After Deployment
•
Specifying a Custom SSH Port While Deploying the Data Collector
Parameters for Deploying the Data Collector
The following table lists the details that you will require for the deployment process:
Deploying Oracle Management Cloud Agents 2-25
Deploying the Oracle Management Cloud Agents
Parameter
Description
AGENT_REGISTRATION_KEY
The actual value of the registration key that
you’ve created for running the install script.
See Creating a Registration Key.
AGENT_BASE_DIR
The absolute path to the location where the
cloud agent needs to be installed.
GATEWAY_HOST
Optional. The data collector can be deployed
directly without the gateway.
The name of the host where the gateway is
deployed. You must specify the fully
qualified host name here. Do not specify the
IP address. The GATEWAY_HOST you specify
here must be the same host used while
installing the gateway.
GATEWAY_PORT
Optional. The port that the gateway is
configured to listen on.
EM_AGENT_NAME
Optional. The home directory of your onpremises Oracle Enterprise Manager home
agent on the host where the data collector
will be deployed.
OMR_USERNAME
The user name used to sign in to the Oracle
Management Repository in your data center.
This user must have the SYSDBA privileges
and is used to:
•
Create OMR collector schema.
•
Access SYSMAN objects and create
synonyms for read access of data.
•
Create DIRECTORY objects in the Oracle
database to collect perf/event data files.
•
Grant necessary package privileges to
the OMR collector schema.
OMR_USER_PASSWORD
The password used to sign in to the Oracle
Management Repository in your data center.
OMR_PORT
The port that Oracle Management Repository
in your data center is configured to listen on.
OMR_HOSTNAME
The name of the host where Oracle
Management Repository is running in your
data center.
Note: You must specify the fully qualified
host name here. Do not specify the IP
address.
2-26 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
Parameter
Description
OMR_SERVICE_NAME
The service name of the Oracle Management
Repository in your data center. This should
be the fully qualified domain name for the
service such as orcl.example.com.
HARVESTER_USERNAME
The user name to sign in to the data collector.
This is a new user.
HARVESTER_USER_PASSWORD
The password for the user to sign in to the
data collector. The password rules of the data
collector are the same as that of the Oracle
Management Repository database password
rules, because the data collector creates a
schema in the Oracle Management
Repository database. However, data collector
passwords can’t have a special character or
numeric as the first character.
OMR_HOST_USERNAME
The user name (of the install user of Oracle
Management Repository) for the host where
Oracle Management Repository is running in
your data center.
OMR_HOST_USER_PASSWORD
The password for the host where Oracle
Management Repository is running in your
data center.
OMR_STAGE_DIR
The directory where the data collector stores
the harvested data in an archived form.
Note: The user deploying the data collector
must have, at the minimum, read privileges
to the stage directory.
Deploying the Data Collector
To deploy the data collector, follow these steps:
1.
Copy the master installer ZIP file to the host where you’ll deploy the data
collector, and then extract the ZIP file. Refer to Downloading the Master Installer
for details. You can use this zip file for deploying the data collector and the cloud
agent but not for the gateway.
2.
Go to the directory (in the host where you’ll deploy the data collector) where you
extracted the master installer ZIP file to. For example, if you extracted the installer
ZIP file to a directory named datacollector_agent in the /scratch
directory on your host, then move from your present working directory to the /
scratch/datacollector_agent directory.
3.
Run the installer script to deploy the data collector, as shown in the following
example:
•
If you’re deploying the data collector on a UNIX-based host:
Deploying Oracle Management Cloud Agents 2-27
Deploying the Oracle Management Cloud Agents
./AgentInstall.sh AGENT_TYPE=data_collector
AGENT_REGISTRATION_KEY= <value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as DataCollector_Agent_1>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host
user password> OMR_PORT=1521
OMR_SERVICE_NAME=orcl.example.com OMR_HOST_USERNAME=emga
OMR_STAGE_DIR=<path to the OMR Stage directory>
•
If you’re deploying the data collector on a Windows host, right-click and
select Run as administrator to open a command prompt and run the
following:
AgentInstall.bat AGENT_TYPE=data_collector
AGENT_REGISTRATION_KEY= <value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as DataCollector_Agent_1>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host
user password> OMR_PORT=1521
OMR_SERVICE_NAME=orcl.example.com OMR_HOST_USERNAME=emga
OMR_STAGE_DIR=<path to the OMR Stage directory>
4.
(Only on UNIX-based hosts) As a root user, run the root.sh command from
AGENT_BASE_DIR:
#AGENT_BASE_DIR/core/1.0.0/root.sh
For information about verifying the deployment of the data collector, see Verifying the
Deployment of Gateways, Data Collectors, and Cloud Agents.
Note:
Locked Account Use Case
While deploying the data collector, if you don't have the password for the
OMR_HOST_USER (oracle), then at the time of deployment, you can pass an
operating system user in the place of the OMR_HOST_USERNAME that meets the
following requirements:
•
Ensure that an operating system user (say User_A has SSH access to Oracle
Management Repository) that has read/write permissions on OMR_STAGE_DIR
exists.
•
Ensure that the operating system user (oracle) who owns the Oracle
Management Repository database Oracle Home also has read/write permissions
on OMR_STAGE_DIR.
•
When running the AgentInstall.sh script, pass the
OMR_HOST_USERNAME=User_A and its password
2-28 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
•
In case of an RAC Oracle Management Repository database environment, ensure
that OMR_STAGE_DIR is accessible from all the instances and the data collector
host, and OMR_HOST_USERNAME and the operating system user who owns the
Oracle Home of the Oracle Management Repository database both have read/
write permissions to OMR_STAGE_DIR.
Upgrading to Enterprise Manager 13.x After Deploying the Data Collector
If you have deployed the data collector on Enterprise Manager 12c and you are
planning to upgrade to Enterprise Manager 13.x, follow the steps listed in the
Troubleshooting. If you have deployed the data collector on Enterprise Manager 13.x,
these steps can be ignored.
Deploying the Data Collector Over a Proxy Server
If you’re deploying the data collector over a proxy server, ensure that you perform the
steps listed in Common Prerequisites for Deploying Oracle Management Cloud
Agents and then run the following command:
•
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=data_collector <value of the
registration key that you had created> AGENT_BASE_DIR=<path
to the agent base directory, such as DataCollector_Agent_1>
AGENT_PROPERTIES=<path to the agent.properties file>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<enter
the host name:the port where the on-premises Oracle
Enterprise Manager agent is running.>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host user
password> OMR_PORT=1521 OMR_SERVICE_NAME=orcl.example.com
OMR_HOST_USERNAME=emga OMR_STAGE_DIR=<path to the OMR Stage
directory>
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
AgentInstall.bat AGENT_TYPE=data_collector <value of the
registration key that you had created> AGENT_BASE_DIR=<path
to the agent base directory, such as DataCollector_Agent_1>
AGENT_PROPERTIES=<path to the agent.properties file>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<enter
the host name:the port where the on-premises Oracle
Enterprise Manager agent is running>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host user
password> OMR_PORT=1521 OMR_SERVICE_NAME=orcl.example.com
OMR_HOST_USERNAME=emga OMR_STAGE_DIR=<path to the OMR Stage
directory>
Deploying Oracle Management Cloud Agents 2-29
Deploying the Oracle Management Cloud Agents
Deploying a Data Collector From a Staged Location
You can deploy a data collector from a staged location by downloading the data
collector bits in the “stage only” mode. This is particularly useful when after
downloading the installer bits, you want to deploy the agent at a later time.
To deploy a data collector from a staged location, follow these steps:
1.
Download the data collector agent bits in “stage only” mode.
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=data_collector STAGE_LOCATION=
<path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
AgentInstall.bat AGENT_TYPE=data_collector STAGE_LOCATION=
<path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
2.
Deploy the data collector using the staged image.
If you’ve previously downloaded the cloud agent install bits in the “stage only”
mode, you can use the same bits from the staged location to deploy the data
collector. However, you can’t use the bits that you've downloaded for the gateway
install for deploying a data collector or a cloud agent.
On UNIX-based hosts:
cd <path to the stage location>
./AgentInstall.sh AGENT_TYPE=data_collector
AGENT_REGISTRATION_KEY= <value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as DataCollector_Agent_1>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<enter
the host name:the port where the on-premises Oracle
Enterprise Manager agent is running.>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host user
password> OMR_PORT=1521 OMR_SERVICE_NAME=orcl.example.com
OMR_HOST_USERNAME=emga OMR_STAGE_DIR=<path to the OMR Stage
directory> -staged
On Windows hosts:
cd <path to the stage location>
AgentInstall.bat AGENT_TYPE=data_collector
AGENT_REGISTRATION_KEY= <value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as DataCollector_Agent_1>
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<enter
the host name:the port where the on-premises Oracle
2-30 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
Enterprise Manager agent is running.>
HARVESTER_USERNAME=SYSMAN_EMAAS_2 OMR_USERNAME=sys
OMR_HOSTNAME=<enter the name of the Oracle Management
Repository host> OMR_HOST_USER_PASSWORD=<your OMR host user
password> OMR_PORT=1521 OMR_SERVICE_NAME=orcl.example.com
OMR_HOST_USERNAME=emga OMR_STAGE_DIR=<path to the OMR Stage
directory> -staged
Deploying the Data Collector On Oracle Real Application Clusters
If you’re deploying a data collector on Oracle Real Application Clusters (RAC), deploy
the data collector on any one node and pass the scan host name instead of individual
RAC host names and OMR_SERVICE_NAME. Using the scan host name, you can
retrieve all the associated nodes for that scan host and also check the SSH connectivity
to all the nodes.
To deploy a data collector on RAC, run the following command:
•
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=data_collector
AGENT_BASE_DIR=<path to the agent base directory, such as
DataCollector_Agent_1> HARVESTER_USERNAME=sysman_emaas16
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<name of
the host running the on-premises EM agent:port>
HARVESTER_USER_PASSWORD=<your data collector user password>
OMR_USER_PASSWORD=<your OMR user password> OMR_USERNAME=sys
AGENT_PORT=1900 OMR_HOST_USERNAME=oracle
OMR_HOST_USER_PASSWORD=<your OMR host user password>
OMR_STAGE_DIR=<path to the OMR Stage directory>
OMR_HOSTNAME=<your OMR host name>
AGENT_REGISTRATION_KEY=<registration key for deploying the
data collector> OMR_PORT=1521
OMR_SERVICE_NAME=pemcld.example.com
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
AgentInstall.bat AGENT_TYPE=data_collector
AGENT_BASE_DIR=<path to the agent base directory, such as
DataCollector_Agent_1> HARVESTER_USERNAME=sysman_emaas16
GATEWAY_HOST=<enter the name of the Gateway host>
GATEWAY_PORT=<enter the Gateway port> EM_AGENT_NAME=<name of
the host running the on-premises EM agent:port>
HARVESTER_USER_PASSWORD=<your data collector user password>
OMR_USER_PASSWORD=<your OMR user password> OMR_USERNAME=sys
AGENT_PORT=1900 OMR_HOST_USERNAME=oracle
OMR_HOST_USER_PASSWORD=<your OMR host user password>
OMR_STAGE_DIR=<path to the OMR Stage directory>
OMR_HOSTNAME=<your OMR host name>
AGENT_REGISTRATION_KEY=<registration key for deploying the
data collector> OMR_PORT=1521
OMR_SERVICE_NAME=pemcld.example.com
Deploying Oracle Management Cloud Agents 2-31
Deploying the Oracle Management Cloud Agents
Modifying the Data Collector Connect String or SSH Port After Deployment
If you need to change the connect string or any other details in the connect string for a
data collector that has already been deployed to the same OMR, follow these steps:
Note: You cannot use these steps to redirect the data collector to a different
OMR.
•
Stop the data collector
<AGENT_BASE_DIR>/agent_inst/bin/omcli stop agent
•
Create a file with name FILENAME:
<AGENT_BASE_DIR>/agent_inst/bin/omcli config_datacollector
agent FILENAME
This file must contain the following details:
UserName: username of the datacollector user.
UserNamePriv: username of a privileged user.
UserRolePriv: userrole of a privileged user. Default SYSDBA.
HarvestHostUserName: username of an OS user for fetching datacollector files.
StageDir: absolute directory path for staging datacollector files on the OMR
host.
ConnectDescriptor: Connect descriptor for the OMR.
Host: host of the OMR. (Not required if ConnectDescriptor is specified)
Port: port of the OMR. (Not required if ConnectDescriptor is specified)
Service: service name of the OMR. (Not required if ConnectDescriptor is
specified)
Sid: SID of the OMR. (Not required if ConnectDescriptor or Service is specified)
Sample File
UserName
: omc_collector
UserNamePriv : sys
UserRolePriv : SYSDBA
HarvestHostUserName : oracle
StageDir : /u01/OMCStageDir
Host : host.domain.com
Port : 1521
Service : EMREP.domain.com
•
Start the data collector.
<AGENT_BASE_DIR>/agent_inst/bin/omcli start agent
To modify the SSH port after the data collector has been installed, follow these steps:
•
Stop the data collector
<AGENT_BASE_DIR>/agent_inst/bin/omcli stop agent
•
Create a file with name FILENAME:
<AGENT_BASE_DIR>/agent_inst/bin/omcli config_datacollector
agent FILENAME
This file must contain the following details:
UserName: username of the datacollector user.
StageDir: absolute directory path for staging datacollector files on the OMR
host.
2-32 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
HarvestHostUserName: username of an OS user for fetching datacollector files.
Sid: SID of the OMR. (Not required if ConnectDescriptor or Service is specified)
UserNamePriv: username of a privileged user.
Host: host of the OMR. (Not required if ConnectDescriptor is specified)
OMR_HOST_SSH_PORT: SSH Port Number (For any port change)
Port: port of the OMR. (Not required if ConnectDescriptor is specified)
Sample File
UserName
: omc_collector
StageDir : /u01/OMCStageDir
HarvestHostUserName : oracle
UserNamePriv : sys
SID: host
Host : host.domain.com
OMR_HOST_SSH_PORT: 42
Port : 1111
•
Start the data collector.
<AGENT_BASE_DIR>/agent_inst/bin/omcli start agent
Specifying a Custom SSH Port While Deploying the Data Collector
If you wish to use a custom SSH Port while deploying the data collector on a different
host than the OMR host, or on the same host as the OMR, you must specify the
following additional parameter during deployment:
ADDITIONAL_PARAMETERS="OMR_HOST_SSH_PORT=<SSH PORT Number>"
Deploying Cloud Agents
This section discusses how to deploy cloud agents.
It covers the following topics:
•
Required Parameters
•
Deploying the Cloud Agent
•
Deploying the Cloud Agent With / Without a Gateway
•
Deploying the Cloud Agent Over a Proxy Server
•
Deploying the Cloud Agent With / Without an On-Premises Enterprise
Manager Agent
•
Deploying the Cloud Agent From a Staged Location
•
Staging the Binaries on a Different Platform Host Without Internet Access
•
Data Buffering Limits and Disk Sizing
Required Parameters
Before you deploy the cloud agents, review the information in Prerequisites for
Deploying Oracle Management Cloud Agents.
Deploying Oracle Management Cloud Agents 2-33
Deploying the Oracle Management Cloud Agents
Note:
If you want to harvest data from existing on-premises Oracle Enterprise
Manager Cloud Control, ensure that the host on which you’re deploying the
cloud agents has an existing on-premises Oracle Enterprise Manager agent. In
addition, the host should be a part of omcgroup (if it exists) in the onpremises Enterprise Manager Cloud Control.
After you’ve deployed a data collector, and before you deploy cloud agents,
you should access the Oracle Management Cloud Agents page of Oracle
Management Cloud user interface, and check whether the Oracle Enterprise
Manager agent targets (that has been harvested by the data collector) have
been uploaded to Oracle Management Cloud.
The following table lists the details that you will require for the deployment process:
Parameter
Description
AGENT_REGISTRATION_KEY
The actual value of the registration key that
you’ve created for running the install script.
See Creating a Registration Key.
GATEWAY_HOST
The name of the host where the gateway is
deployed. You must specify the fully
qualified host name here. Do not specify the
IP address/
While deploying the cloud agent, you must
use the same gateway host name that was
used for installing the gateway. For example:
If the gateway was deployed with the
parameter
ORACLE_HOSTANME=abc.xyz.com but
while installing the cloud agent, you passed
the parameter GATEWAY_HOST=abc, this will
result in cloud agent registration failures.
GATEWAY_PORT
The port that was specified while deploying
the gateway.
EM_AGENT_HOME/EM_AGENT_NAME
Optional. This parameter is required only
when you want to harvest data from existing
on-premises Oracle Enterprise Manager
Cloud Control. It refers to the home directory
of your on-premises Oracle Enterprise
Manager home agent on the host where the
cloud agents will be deployed/The host
name and the port where the on-premises
Oracle Enterprise Manager agent is running.
AGENT_BASE_DIR
The absolute path to the location where the
cloud agent needs to be installed.
2-34 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
Parameter
Description
AGENT_PORT
The port the cloud agent binds to. If the port
number is not specified, an available port in
the range 3872 and 1830–1849 is used.
Deploying the Cloud Agent
To deploy the cloud agent, follow these steps:
1.
Copy the master installer ZIP file to the host where you’ll deploy the cloud agents,
and then extract the ZIP file. Refer to Downloading the Master Installer for more
details. You can use the same installer for deploying gateway, data collector and
cloud agent, or you can download and use separate master installers for each of
the agents.
2.
Go to the directory (in the host where you’ll deploy the cloud agents) where you
extracted the master installer ZIP file to.
For example, if you extracted the installer ZIP file to a directory named
cloud_agent in the /scratch directory on your host, then move from your
present working directory to the /scratch/cloud_agent directory.
3.
Depending on your use case, run the installer script to deploy the cloud agent as
follows:
•
With / Without Gateway
•
Over a Proxy Server
•
With / Without Enterprise Manager Agent
•
From a Staged Location
For information about verifying the deployment of the cloud agents, see Verifying the
Deployment of Gateways, Data Collectors, and Cloud Agents
Note: (Only on UNIX-based hosts) As a root user, run the root.sh
command from AGENT_BASE_DIR:
#AGENT_BASE_DIR/core/1.0.0/root.sh
Deploying the Cloud Agent With / Without a Gateway
If you are deploying the cloud agent with an associated gateway, enter the following
command:
•
On Unix-based hosts:
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent> AGENT_PORT=<enter the port>
GATEWAY_HOST=<enter the name of the gateway host>
GATEWAY_PORT=<enter the port>
Deploying Oracle Management Cloud Agents 2-35
Deploying the Oracle Management Cloud Agents
•
On Windows hosts, the user installing the agent must have permissions to act as
part of the operating system, adjust memory quota for a process, replace process
level tokens, and log on as a batch job. To verify the permissions, from the Start
menu, click Settings, then click Control Panel. From the Control Panel window,
click Administrative Tools, and then click Local Security Policy. Expand the
Local Policies folder and open the User Rights Assignment folder.
Right-click and select Run as administrator to open a command prompt and run
the following:
./AgentInstall.bat AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent> GATEWAY_HOST=<enter the name
of the Gateway host> GATEWAY_PORT=<enter the Gateway port>
AGENT_PORT=<enter the port>
Note: The gateway host name you specify here must be the same name that
was used to install the gateway. For example, if you have deployed the
gateway with ORACLE_HOSTNAME=abc.xyz.com, and you specify
ORACLE_HOSTNAME=my.host.com while installing the cloud agent, the
cloud agent registration will fail.
If are deploying the cloud agent without a gateway, deploy the cloud agent on a host
that has access to internet, either directly or through a proxy server. To deploy the
cloud agent without a gateway, enter the same commands as given above but without
the GATEWAY_HOST and GATEWAY_PORT parameters.
Note:
The AGENT_PORT parameter is optional. If the port number is not specified, an
available port will be automatically used.
Deploying the Cloud Agent Over a Proxy Server
If you are deploying the cloud agent over a proxy server and have not deployed a
gateway, enter the following command:
•
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY= <value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent> AGENT_PROPERTIES=<path to
the agent.properties file> AGENT_PORT=<enter the port>
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
./AgentInstall.bat AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY= <value of the registration key that
you had created> AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent> AGENT_PROPERTIES=<path to
the agent.properties file> AGENT_PORT=<enter the port>
2-36 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
If you are deploying the cloud agent over a proxy server on a Windows host, you
must pass the agent.properties file as a parameter to the
AgentInstall.bat script.
For more details on modifying the proxy server settings, see Modifying Proxy
Server Settings
Note:
•
Do not deploy the cloud agent as a root user.
•
When deploying the cloud agent on a host, if running the command
domainname does not return any value, then:
1.
Run the following command to obtain fully qualified domain name
(FQDN) of the host:
$ host `hostname`
2.
Make a note of the FQDN, and pass this value to the
ORACLE_HOSTNAME parameter in the agent install script as below:
–
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the
registration key that you had created>
AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent>
ORACLE_HOSTNAME=<fully qualified domain name of
the host>
–
On Windows hosts, right-click and select Run as administrator
to open a command prompt and run the following:
./AgentInstall.bat AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the
registration key that you had created>
AGENT_BASE_DIR=<path to the agent base
directory, such as cloud_agent>
ORACLE_HOSTNAME=<fully qualified domain name of
the host>
If you’re deploying the cloud agent over a proxy server and you have an existing onpremises Oracle Enterprise Manager agent, run the same commands as given above,
but additionally, include the EM_AGENT_HOME (path to the Oracle Enterprise Manager
Agent Home) parameter.
Deploying the Cloud Agent With / Without an On-Premises Enterprise Manager
Agent
•
With an On-Premises Enterprise Manager Agent: If you have an existing onpremises Oracle Enterprise Manager Agent, enter the following command:
–
On UNIX-based hosts, run the following command:
Deploying Oracle Management Cloud Agents 2-37
Deploying the Oracle Management Cloud Agents
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as cloud_agent> EM_AGENT_HOME=<enter
the path to the Oracle Enterprise Manager Agent Home>
–
On Windows hosts, the user installing the agent must have permissions to act
as part of the operating system, adjust memory quota for a process, replace
process level tokens, and log on as a batch job. To verify the permissions,
from the Start menu, click Settings, then click Control Panel. From the
Control Panel window, click Administrative Tools, and then click Local
Security Policy. Expand the Local Policies folder and open the User Rights
Assignment folder.
Right-click and select Run as administrator to open a command prompt and
run the following:
AgentInstall.bat AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as cloud_agent> EM_AGENT_HOME=<enter
the path to the Oracle Enterprise Manager Agent Home>
Note:
You can also use EM_AGENT_NAME instead of EM_AGENT_HOME. If you’re
using EM_AGENT_NAME, then enter the host name and port where the onpremise Oracle Enterprise Manager agent is running.
•
Without an On-Premises Enterprise Manager Agent: If you don’t have an
existing on-premises Oracle Enterprise Manager Agent, enter the same commands
as given above, but without the EM_AGENT_HOME parameter.
Deploying the Cloud Agent From a Staged Location
You can deploy a cloud agent from a staged location by downloading the cloud agent
bits in the “stage only” mode. This is particularly useful when after downloading the
installer bits, you want to deploy the agent at a later time.
To deploy a cloud agent from a staged location:
1.
Download the cloud agent bits in “stage only” mode.
•
On UNIX-based hosts:
./AgentInstall.sh AGENT_TYPE=cloud_agent STAGE_LOCATION=
<path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
AgentInstall.bat AGENT_TYPE=cloud_agent STAGE_LOCATION=
<path to the stage location>
AGENT_REGISTRATION_KEY=<registration key value> download_only
2-38 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Deploying the Oracle Management Cloud Agents
2.
Deploy the cloud agent using the staged image.
If you’ve previously downloaded the data collector install bits in the “stage only”
mode, you can use the same bits from the staged location to deploy the cloud
agent. However, you can’t use the bits that you've downloaded for the gateway
install for deploying a data collector or a cloud agent.
•
On Unix-based hosts
cd <path to the stage location>
./AgentInstall.sh AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as cloud_agent> EM_AGENT_HOME=<enter
the path to the Oracle Enterprise Manager Agent Home> staged
•
On Windows hosts, right-click and select Run as administrator to open a
command prompt and run the following:
cd <path to the stage location>
AgentInstall.bat AGENT_TYPE=cloud_agent
AGENT_REGISTRATION_KEY=<value of the registration key
that you had created> AGENT_BASE_DIR=<path to the agent
base directory, such as cloud_agent> EM_AGENT_HOME=<enter
the path to the Oracle Enterprise Manager Agent Home> staged
Staging the Binaries on a Different Platform Host Without Internet Access
If you want to deploy the cloud agent on a host (for example, Solaris Sparc) that has no
Internet access, but has a gateway configured on another platform host ( for example
Linux) with Internet access, follow these steps to download the agent binaries:
1.
To stage the binaries, run the following command on the Solaris Sparc host with
the gateway details:
./AgentInstall.sh AGENT_TYPE=cloud agent STAGE_LOCATION=
<path to the stage location> AGENT_REGISTRATION_KEY=
<registration key value> GATEWAY_HOST= <enter the name of
the gateway host> GATEWAY_PORT= <enter the gateway port> —
download_only
In this example, the Solaris Sparc binaries will be downloaded to the staged
directory through the gateway (on Linux)
2.
Install the cloud agent on the Solaris Sparc host using the staged bits:
./AgentInstall.sh AGENT_TYPE=cloud agent
AGENT_REGISTRATION_KEY=<registration key value>
AGENT_BASE_DIR=<path to the agent base directory, such as
cloud_agent> GATEWAY_HOST=<enter the name of the gateway
host> GATEWAY_PORT=<enter the name of the gateway port> —
staged
The agent zip files are platform specific.
If you are not deploying the cloud agent through the gateway, then the
GATEWAY_HOST and GATEWAY_PORT details need not be specified.
Deploying Oracle Management Cloud Agents 2-39
Verifying the Deployment of Gateways, Data Collectors, and Cloud Agents
Data Buffering Limits and Disk Sizing
If there are network connectivity issues, the cloud agent will not be able to send data
to the Oracle Management Cloud service. By default, the cloud agent can stored up to
100 MB of data (as specified by the parameter
senderManagerMaxDiskUsedTotal=100), and the gateway can store up to 100 GB
of data (as specified by the parameter
senderManagerMaxDiskUsedTotal=100000) locally. When connectivity is
restored, the stored or buffered data will automatically be uploaded to the Oracle
Management Service.
Note: These values can be changed modifying the parameters in the
emd.properties file located in the $installdir/agent_inst/sysman/
config/ directory.
Verifying the Deployment of Gateways, Data Collectors, and Cloud
Agents
After downloading the master installer and deploying the gateway, data collector, and
cloud agents, follow these steps to verify their successful deployment.
1. Verify gateway deployment by following these steps:
a. Sign in to My Services by accessing cloud.oracle.com/sign_in.
b. Launch the service that you want to access, such as IT Analytics or Log
Analytics.
This displays the Home page of the service.
c. Click the Application navigator icon on the top right corner, and click Agents
under Administration.
This displays the Oracle Management Cloud Agents page.
d. Click Gateways on the left navigation pane.
e. Check if the host name of your deployed gateway exists in the list of available
gateways.
You can click the gateway entry and match the specified registration key value
with the registration key that you had used when deploying the agent.
2. Verify data collector deployment by following these steps:
a. Open the Oracle Management Cloud Agents page.
b. Click Data Collectors on the left navigation pane.
c. Check if the host name of your deployed data collector exists in the list of
available data collectors.
You can click the data collector entry and match the specified registration key
value with the registration key that you had used when deploying the agent.
3. Verify cloud agent deployment by following these steps:
a. Open the Oracle Management Cloud Agents page.
2-40 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Agent Install and Upgrade Logs
b. Click Cloud Agents on the left navigation pane.
c. Check if the host name of your deployed cloud agent exists in the list of
available cloud agents.
You can click the required cloud agent entry and match the specified
registration key value with the registration key that you had used when
deploying the agent.
You can use the following omcli commands to verify whether the OMC agents have
been successfully deployed.
$ ./omcli status agent
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
--------------------------------------------------------------Version
: 1.12.0
State Home
: /OMC/CL_Base/agent_inst
Log Directory
: /OMC/CL_Base/agent_inst/sysman/log
Binaries Location
: /OMC/CL_Base/LAMA_LINUX.X64_161029.0801/core/1.12.0
Process ID
: 24807
Parent Process ID
: 24767
URL
: https://x2270m2-abc.xyz.com:1830/emd/main/
Started at
: 2016-12-12 04:23:51
Started by user
: oracle
Operating System
: Linux version 3.8.13-16.2.1.el6uek.x86_64 (amd64)
Data Collector enabled : false
Sender Status
: FUNCTIONAL
Gateway Upload Status : FUNCTIONAL
Last successful upload : 2017-01-30 11:27:38
Last attempted upload : 2017-01-30 11:27:38
Pending Files (MB)
: 0
Pending Files
: 6
Backoff Expiration
: (none)
--------------------------------------------------------------Agent is Running and Ready
$ ./omcli config agent listtargets
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
[x2270m2-xyz.abc.com:1830, Lama]
[x2270m2-xyz.abc.com, omc_host_linux]
[Tomcat, omc_tomcat]
[M_clusterware, omc_oracle_clusterware]
[MS_clusternode, omc_cluster_node]
]
Agent Install and Upgrade Logs
The agent install and upgrade logs can be used to troubleshoot issues during
deployment. Check the following log files for gateway, data collector, and cloud agent.
•
For agent install failures, check the log file under:
<Agent Base Directory>/logs/AgentInstall_logs/
AgentInstall_<time stamp>
/scratch/den00bvl/gateway/logs/AgentInstall_040416031012.log
Deploying Oracle Management Cloud Agents 2-41
Agent Install and Upgrade Logs
•
After deployment, check the log files under
<Agent Base Directory>/agent_inst/sysman/log/*.* and for
debugging purposes, zip up the entire folder to share the log files.
•
If your cloud agent and data collector are using a gateway, check the gateway log
file under:
<Agent Base Directory>/agent_inst/sysman/log/*.*
•
For all agents (gateway, data collector, and cloud agent), check the update log files
under:
<Agent Base Directory>/AgentUpdate/*.log
Setting Up Debug Logs
You can set up debug logs for Oracle Management Cloud agents.
Setting Up Debug Logs
To set up debug logs:
1.
Go to Agent_Home/agent_inst/bin/ directory on the host that is running the
agent.
2.
Run the following command to set up the debug logs:
omcli setproperty agent -name Logger.log.level -value DEBUG
The output of the command will be as follows:
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
EMD setproperty succeeded
3.
Verify if the debug log property has been set.
omcli getproperty agent -name Logger.log.level
The output of the command will be as follows:
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
Logger.log.level=DEBUG
Note:
If the debug property is not set, the output of the following command will
display Logger.log.level=INFO.
omcli getproperty agent -name Logger.log.level
2-42 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
3
Setting Up Oracle Management Cloud
This section provides information about the tasks that are involved in deploying
Oracle Management Cloud agents.
Topics:
•
Setting Up Infrastructure Monitoring
•
Setting Up Log Analytics
•
Setting Up IT Analytics
•
Setting Up Application Performance Monitoring
Setting Up Infrastructure Monitoring
Oracle Infrastructure Monitoring Cloud Service lets you perform status and health
monitoring across tiers and be alerted about issues, troubleshoot and resolve them
before they affect users.
Topics:
•
Getting Started With the Oracle Infrastructure Monitoring Service
•
Adding Infrastructure Monitoring Entities
•
Before You Begin Using Infrastructure Monitoring
Getting Started With the Oracle Infrastructure Monitoring Service
To get started with the Oracle Infrastructure Monitoring Service, follow these steps:
Task
Required (Yes /
No)
Topic
Downloading the Master
Installer
Yes
See Downloading the Master Installer
Deploying the Gateway
Optional
See Deploying the Gateway
Deploying the Cloud Agent
Yes
See Deploying Cloud Agents
Verifying the Deployment
Yes
See Verifying the Deployment of
Gateways, Data Collectors, and Cloud
Agents
Adding Infrastructure
Entities
Yes
See Adding Infrastructure Monitoring
Entities
Setting Up Oracle Management Cloud 3-1
Setting Up Infrastructure Monitoring
Task
Required (Yes /
No)
Topic
Before You Begin Using the
Oracle Infrastructure
Monitoring Service
Yes
See Before You Begin Using Infrastructure
Monitoring
Deployment Flow
This section illustrates the deployment flow for the Infrastructure Monitoring Cloud
Service.
Adding Infrastructure Monitoring Entities
You can use omcli commands to add entities to Infrastructure Monitoring.
See Managing Entities in Infrastructure Monitoring in Managing Oracle Management
Cloud Entities.
Before You Begin Using Infrastructure Monitoring
Before you start using Infrastructure Monitoring, complete the following steps:
3-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Log Analytics
1. Move to the Set Up Infrastructure Monitoring – Progress screen. The system detects
the Oracle Management Cloud agents as and when they are deployed in your data
center.
The Infrastructure Monitoring – Progress screen indicates how many Oracle
Management Cloud agents are detected.
2. When at least agent is detected, click Go to Dashboards.
You’re ready to start using Infrastructure Monitoring.
Setting Up Log Analytics
Oracle Log Analytics Cloud Service helps you analyze and monitor vast amounts of
log data across your entire enterprise through a single, unified, and customizable
display that's easy to read and navigate.
Topics:
•
Getting Started With the Log Analytics Service
•
Adding Log Analytics Entities
•
Creating Groups
•
Before You Begin Using Log Analytics
Getting Started With the Log Analytics Service
To get started with the Oracle Log Analytics Service, follow these steps:
Task
Required (Yes /
No)
Topic
Downloading the Master
Installer
Yes
See Downloading the Master Installer
Deploying the Gateway
Optional
See Deploying the Gateway
Deploying the Data Collector
Optional
See Deploying the Data Collector
Deploying the Cloud Agent
Yes
See Deploying Cloud Agents
Verifying the Deployment
Yes
See Verifying the Deployment of
Gateways, Data Collectors, and Cloud
Agents
Adding Log Entities
Yes
See Adding Log Analytics Entities
Creating Groups
Yes
See Creating Groups
Before You Begin Using the
Oracle Log Analytics Service
Yes
See Before You Begin Using Log Analytics
Deployment Flow
This section illustrates the deployment flow for the Log Analytics Service.
Setting Up Oracle Management Cloud 3-3
Setting Up Log Analytics
Adding Log Analytics Entities
You can use omcli commands to add entities to Log Analytics.
See Managing Entities in Log Analytics in Managing Oracle Management Cloud Entities.
Creating Groups
After you’ve added entities, you can create Groups to monitor and analyze log entries
of those entities.
A Group is a single logical unit that can include targets of the same type (for example,
all your production databases).
For more information about creating groups in Log Analytics, contact Oracle Support.
Before You Begin Using Log Analytics
Before you start using Log Analytics, complete the following steps:
1. Move to the Set Up Log Analytics – Progress screen. The system detects the Oracle
Management Cloud agents as and when they are deployed in your data center.
The Set Up Log Analytics – Progress screen indicates how many agents are
detected.
3-4 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up IT Analytics
2. When at least one agent is detected, click Go to Dashboards.
You’re ready to start using Log Analytics to search, view, and analyze logs.
Setting Up IT Analytics
Oracle IT Analytics Cloud Service gives you a 360-degree insight into the performance,
availability, and capacity of your applications and IT resources. It enables line of
business executives, analysts, and administrators to make critical decisions about their
IT operations, based on comprehensive system and data analysis. Using Oracle IT
Analytics Cloud Service, you can find systemic issues, analyze resource usage across
application tiers, and forecast future demand for IT services based on historical
performance trends.
Topics:
•
Getting Started With the Oracle IT Analytics Service
•
Adding IT Analytics Entities
Getting Started With the Oracle IT Analytics Service
To get started with the IT Analytics Service, follow these steps:
Task
Required (Yes /
No)
Topic
Downloading the Master
Installer
Yes
See Downloading the Master Installer
Deploying the Gateway
Optional
See Deploying the Gateway
Deploying the Data Collector
Yes
See Deploying the Data Collector
Deploying the Cloud Agent
Yes
See Deploying Cloud Agents
Verifying the Deployment
Yes
See Verifying the Deployment of
Gateways, Data Collectors, and Cloud
Agents
Enabling IT Analytics on
Entities
Yes
See Adding IT Analytics Entities
Deployment Flow
This section illustrates the deployment flow for the IT Analytics Service.
Setting Up Oracle Management Cloud 3-5
Setting Up Application Performance Monitoring
Adding IT Analytics Entities
You can enable IT Analytics to monitor non-Oracle Enterprise Manager entities.
See Managing Entities in IT Analytics in Managing Oracle Management Cloud Entities to
learn how to enable IT Analytics to monitor entities.
Setting Up Application Performance Monitoring
Oracle Application Performance Monitoring Cloud Service is a Platform as a Service
(PaaS) based solution that provides deep visibility into the performance of your
application, from end user to application logs. The service integrates user experience
information and application metrics along with log data analytics.
Topics:
•
Setting Up APM Java Agents
•
Setting Up APM .Net Agents
•
Setting Up APM Node.js Agents
3-6 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
•
Setting up APM on Mobile Clients
Setting Up APM Java Agents
APM Java Agent can be deployed on various application servers.
•
Oracle WebLogic Server
•
Apache Tomcat Server
•
JBoss Server
•
WebSphere Server
•
Jetty Server
Topics:
•
Setting up Application Performance Monitoring on Oracle WebLogic Server
•
Setting up Application Performance Monitoring on Apache Tomcat
•
Setting up Application Performance Monitoring on JBoss
•
Setting up Application Performance Monitoring on WebSphere
•
Verifying APM Java Agent Installation
•
Setting up Application Performance Monitoring on Jetty
Prerequisites for Deploying an APM Java Agent
The section covers the key considerations and prerequisites for deploying APM Java
Agents.
•
Prerequisites for Deploying APM Java Agent on a WebLogic Server
•
Prerequisites for Deploying APM Java Agent on an Apache Tomcat Server
•
Prerequisites for Deploying APM Java Agent on a JBoss Server
•
Prerequisites for Deploying APM Java Agent on a WebSphere Application Server
•
Prerequisites for Deploying APM Java Agent on a Jetty Server
CPU Usage Guidelines for Deploying APM Java Agents
The following tables lists the CPU usage guidelines for deploying APM Java agents on
different platforms:
Metrics
WebLogic Server
Tomcat
JBoss
-
Without
Agent
With
Agent
Without
Agent
With
Agent
Without
Agent
With
Agent
CPU
Usage
2.11%
2.73%
7.20%
8.40%
1.90%
3.23%
Setting Up Oracle Management Cloud 3-7
Setting Up Application Performance Monitoring
Prerequisites for Deploying APM Java Agent on a WebLogic Server
•
Supported versions of Oracle WebLogic Server:
–
Oracle WebLogic Server 12.1.3
–
Oracle WebLogic Server 12.1.2
–
Oracle WebLogic Server 10.3.6, also known as Oracle WebLogic Server 11g
Release 1
Note:
In the host running Oracle WebLogic Server, you can run the following
command from $WLS_HOME/server/lib to check the Oracle WebLogic
Server version:
java -cp weblogic.jar weblogic.version
•
cURL with SSL support
•
Unzip
•
Other considerations:
–
The machine hosting the Oracle WebLogic Server should be able to establish
an HTTPS connection (either over a proxy server or not) to Oracle
Management Cloud.
–
The install user of APM Java Agent should be the same as the WebLogic
Server user.
–
The WebLogic Server user should have read and write permissions to the
directories that host the APM Java Agent.
Prerequisites for Deploying APM Java Agent on an Apache Tomcat Server
•
Supported versions of Apache Tomcat Server:
–
7
–
8
–
TomEE
•
cURL with SSL support
•
Unzip
•
Other considerations:
–
The machine hosting the Apache Tomcat Server should be able to establish an
HTTPS connection (either over a proxy server or not) to Oracle Management
Cloud.
–
The install user of APM Java Agent should be the same as the Apache Tomcat
user.
3-8 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
–
The Apache Tomcat Server user should have read and write permissions to
the directories that host the APM Java Agent, as well as the CATALINA_BASE
APM Java Agent logging and config directories if different from
CATALINA_HOME.
Prerequisites for Deploying APM Java Agent on a JBoss Server
•
Supported versions:
–
JBoss EAP 6.1
–
Wildfly 9.0.2
•
cURL with SSL support
•
Unzip
•
Other considerations:
–
The machine hosting the JBoss Server should be able to establish an HTTPS
connection (either over a proxy server or not) to Oracle Management Cloud.
–
The install user of APM Java Agent should be the same as the JBoss user.
–
The JBoss Server user should have read and write permissions to the
directories that host the APM Java Agent, as well as the JBOSS Home.
Prerequisites for Deploying APM Java Agent on a WebSphere Application Server
•
Supported versions:
–
WebSphere Application Server 8.5
•
cURL with SSL support
•
Unzip
•
Other considerations:
–
The machine hosting the WebSphere Application Server should be able to
establish an HTTPS connection (either over a proxy server or not) to Oracle
Management Cloud.
–
The install user of APM Java Agent should be the same as the WebSphere
Application Server user.
–
The WebSphere Application Server user should have read and write
permissions to the directories that host the APM Java Agent, as well as the
WebSphere Application Server Home.
Prerequisites for Deploying APM Java Agent on a Jetty Server
•
Supported versions:
–
Jetty Server 7, 8, and 9
•
cURL with SSL support
•
Unzip
Setting Up Oracle Management Cloud 3-9
Setting Up Application Performance Monitoring
•
You can install one APM Agent in one instance of Jetty.
•
Other considerations:
–
The machine hosting the Jetty Server should be able to establish an HTTPS
connection (either over a proxy server or not) to Oracle Management Cloud.
–
The install user of APM Java Agent should be the same as the Jetty Server
user.
–
The Jetty Server user should have read and write permissions to the
directories that host the APM Java Agent, as well as the Jetty Server Home.
Setting up Application Performance Monitoring on Oracle WebLogic Server
Complete the following tasks sequentially, to set up the APM Java Agent on WebLogic
•
Overview of Deploying APM Java Agent on a WebLogic Server
•
Preparing to Deploy APM Java Agent on WebLogic
•
Downloading the Master Installer for APM Java Agent
•
Installing and Provisioning APM Java Agent on WebLogic
•
Adding the APM Java Agent to your WebLogic Server
Overview of Deploying APM Java Agent on a WebLogic Server
An APM Java Agent is deployed on the WebLogic Managed Server where the
application to be monitored is installed.
The APM Java Agent collects and shares data about the performance of the application
to the Application Performance Monitoring web user interface, from where you can
closely monitor your application’s performance.
This image depicts how an APM Java Agent is deployed on the WebLogic Managed
Server.
3-10 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Here are some details about the inbound and outbound traffic of the APM Java Agent.
Inbound Traffic: The APM Java Agent doesn't open any ports to listen on.
Outbound Traffic: The only outbound traffic the APM Java Agent initiates is sent to
Oracle Management Cloud over HTTPS protocol.
For information about how to deploy Application Performance Monitoring, see Setting
Up Application Performance Monitoring.
Preparing to Deploy APM Java Agent on WebLogic
Before you can download and install an APM Java Agent, ensure that you set the
staging directory in the target host running the application server. The application you
want to monitor is installed on this application server.
Setting Up Oracle Management Cloud 3-11
Setting Up Application Performance Monitoring
Setting the Staging Directory
Note:
If you are trying to deploy the APM Java Agent agents over a proxy server,
then you need to set the proxy variables, http_proxy and https_proxy on
the host where you’re deploying the agents.
If you’re using a Bash shell:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, ${STAGE_DIR} is the path to a directory that is created by the
download script, where the software is downloaded, and from where you run the
provisioning script that comes with the bundle.
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
export STAGE_DIR=/scratch/apm_staging
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the DOMAIN_HOME Variable
Set the DOMAIN_HOME variable to point to the WebLogic Server domain.
•
If you're using a Bash shell:
export DOMAIN_HOME=<WebLogic Server Domain>
•
If you're using a C shell:
setenv DOMAIN_HOME "<WebLogic Server Domain>"
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
3-12 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
Downloading the Master Installer for APM Java Agent
Download the master installer to a shared directory that can be accessed by all the
managed servers in the application server domain where APM Java Agents will be
deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Java Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to install and deploy the APM
Java agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
Setting Up Oracle Management Cloud 3-13
Setting Up Application Performance Monitoring
accepting any data sent by APM Java Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
Note:
a.
If you’re deploying the APM Java Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Java Agent and
then run AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
b.
If you’re deploying the APM Java Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Java Agent on WebLogic
After you have downloaded and extracted the installer, install and provision the APM
Java Agent in your application server domain.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
Installing APM Java Agent
To install and provision the APM Java Agent:
1. From your staging directory, run the provisioning script:
3-14 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME}
-d is the absolute path of the home directory of the WebLogic Server domain. The
APM Java Agent will be installed under this directory.
The command line displays your tenant name and the value you specified.
2. Review the values and confirm. To change the values, enter n and run the script
again with new values.
3. To proceed with the installation, enter y.
The APM Java Agent is installed.
For syntax and more options that can be used with the
ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Installing APM Java Agent without Oracle Wallet
1. From your staging directory, run the provisioning script:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -no-wallet
-d is the absolute path of the home directory of the WebLogic Server domain. The
APM Java Agent will be installed under this directory.
The command line displays your tenant name and the value you specified.
2. Review the values and confirm. To change the values, enter n and run the script
again with new values.
3. To proceed with the installation, enter y.
The APM Java Agent is installed.
Installing APM Java Agent in a Proxy Environment
If you are installing and provisioning the APM Java Agent in environments that
require the use of proxy servers, some additional options have to be used. Contact
your network administrator for the values of these options.
1. From your staging directory, run the provisioning script:
a.
With Oracle Wallet:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d $
{DOMAIN_HOME}
-ph {http_proxy_host}
-pp {http_proxy_port} \
-pt {http_proxy_auth_token}
Setting Up Oracle Management Cloud 3-15
Setting Up Application Performance Monitoring
b.
Without Oracle Wallet:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -nowallet
-ph {http_proxy_host}
-pp {http_proxy_port} \
-pt {http_proxy_auth_token}
-d is the absolute path of the home directory of the WebLogic Server domain. The
APM Java Agent will be installed under this directory.
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
If you are using HTTP Basic authentication,
it is recommended that you omit this
parameter. For details on HTTP Basic
authentication, see Generating Proxy
Token. You can also specify the proxy
wallet entry or NTLM credentials token in
the following format: domain/
username:password. For example:
exampledomain/sampleuser:welcome
Here’s an example of provisioning the APM Java Agent without Oracle Wallet,
while using a proxy server with HTTP Basic authentication:
./ProvisionApmJavaAsAgent.sh -d ${DOMAIN_HOME} -no-wallet \
-ph "www-proxy.example.com"
-pp 80 \
-pt "Basic am9lOmNvb2w="
The command line displays your tenant name and the value you specified.
2. Review the values and confirm. To change the values, enter n and run the script
again with new values.
3. To proceed with the installation, enter y.
The APM Java Agent is installed.
Generating Proxy Token
The APM Java agent can generate a token for HTTP Basic authentication using a
username and password instead of a token that is user-generated.
Once the user provides a user name and password as property file entries, the APM
Java agent will automatically generate a HTTP Basic authentication token. To get
HTTP Basic authentication token generated by the APM Java Agent:
3-16 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
1. In the <agent>/config/AgentHttpBasic.properties file, specify the
following properties:
oracle.apmaas.agent.http.proxy.basic.username = myHttpBasicProxyUser
oracle.apmaas.agent.http.proxy.basic.password = myHttpBasicProxyPass
If along with the above properties, an authentication is also specified
with the property oracle.apmaas.agent.http.proxy.token, it will
take precedence over the username and password properties.
Note:
APM Java agent uses the user name and password to generate a HTTP Basic
authentication token, and authenticate the user.
Setting the NTLM Workstation
Administrators can set the Microsoft Windows NT LAN Manager (NTLM)
workstation in case your proxy has this requirement. To set the NTLM workstation:
•
Add the following property to the AgentStartup properties file:
oracle.apmaas.agent.transport.proxy.ntlm.workstation
Configuring NTLM Proxy Authentication in the APM Java Agent
You can configure NTLM proxy authentication in the APM Java agent to support
NTLM authentication.
To configure NTLM proxy authentication:
1. In the AgentHttpBasic.properties file, specify the
oracle.apmaas.agent.http.proxy.token property with a value in this
format:
domain/username:password
Example: oracle.apmaas.agent.http.proxy.token = testdomain/
user1:hello
Adding the APM Java Agent to your WebLogic Server
There are three ways to add the APM Java agent to your WebLogic server.
•
Modifying startWebLogic.sh: This will deploy APM Agent on the domain’s
WebLogic administration server and on all the managed servers.
•
Modifying startManagedWebLogic.sh: This will deploy APM Agent on the
managed servers on the domain.
•
Using the administration console: If you are using Node Manager, use the
WebLogic Server administration console to configure the servers you want to add
the APM Agent to.
To deploy APM Agent on the domain’s WebLogic administration server and on all
the managed servers by modifying the startWebLogic.sh script of your
WebLogic Server domain:
1. Make a copy of your startWebLogic.sh file:
% cd $DOMAIN_HOME/bin
% cp startWebLogic.sh startWebLogic.sh.orig
Setting Up Oracle Management Cloud 3-17
Setting Up Application Performance Monitoring
2. Using a text editor, edit the original script to add the -javaagent option to the set
of Java options:
a. Add the following line after the setDomainEnv.sh call:
JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:${DOMAIN_HOME}/
apmagent/lib/system/ApmAgentInstrumentation.jar"
Here is an example of the startWebLogic.sh file with the above javaagent option added.
DOMAIN_HOME=<path to your domain home>
. ${DOMAIN_HOME}/bin/setDomainEnv.sh $*
JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:${DOMAIN_HOME}/apmagent/lib/system/
ApmAgentInstrumentation.jar"
JAVA_OPTIONS="${JAVA_OPTIONS} Djava.util.logging.manager=oracle.core.ojdl.logging.ODLLogManager"
SAVE_JAVA_OPTIONS="${JAVA_OPTIONS}"
SAVE_CLASSPATH="${CLASSPATH}"
3. Stop and restart the WebLogic Server:
%
%
%
%
cd $DOMAIN_HOME/bin
./stopWebLogic.sh
cd ..
nohup ./startWebLogic.sh >& startup.log &
You can check the entries present in the $DOMAIN_HOME/startup.log file to
verify that the WebLogic Server has started.
Note:
Notice that the $DOMAIN_HOME version of the startWebLogic.sh is used,
even though you edited the $DOMAIN_HOME/bin version. Invoking the
startWebLogic.sh script from one level higher (from $DOMAIN_HOME)
invokes the script from a lower level (from $DOMAIN_HOME/bin).
However, the stopWebLogic.sh script will be called from the
$DOMAIN_HOME/bin directory.
4. If you have any managed WebLogic application servers, stop and restart them.
To deploy APM Agent on the managed servers by modifying the
startManagedWebLogic.sh script of your WebLogic Server domain:
You can choose to monitor only the managed servers through Application
Performance Monitoring, without monitoring the administration server. In such a
case, make the modifications listed above in the bin/startManagedWebLogic.sh
file instead of bin/startWebLogic.sh file.
1.
Make a copy of your startManagedWebLogic.sh file:
% cd $DOMAIN_HOME/bin
% cp startManagedWebLogic.sh startManagedWebLogic.sh.orig
2.
Using a text editor, edit the file startManagedWebLogic.sh, and locate the
DOMAIN_HOME definition in the file:
DOMAIN_HOME=<path_to_domain_home>
3-18 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
3.
Add the below JAVA_OPTIONS line right after the DOMAIN_HOME definition:
DOMAIN_HOME=<path to your domain home>
JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:${DOMAIN_HOME}/apmagent/lib/system/
ApmAgentInstrumentation.jar"
4.
Stop and restart the WebLogic Server.
To deploy APM Agent using the administration console:
If your servers are started using the Node Manager, specify the -javaagent
parameter in the management console: Environment/Servers/Configuration/
Server Start, in the Argument field.
Installing and Provisioning APM Java Agent on WebLogic on Windows
You can install and provision the APM Java Agent on your WebLogic domain
installed on a Windows machine.
•
Download SSL enabled cURL executables for Windows.
•
Download and place Unzip.exe in STAGE_LOC.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
To install and provision APM Java Agent on WebLogic on Windows:
1.
Download the APM Java Agent bits in the staging location by running the
following commands:
set REG_KEY=<Registration key>
set STAGE_LOC=<staging location>
AgentInstall.bat AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=%STAGE_LOC%
AGENT_REGISTRATION_KEY=%REG_KEY%
cd %STAGE_LOC%
2.
Run the following command to provision the APM Java agent:
set the DOMAIN HOME : set DOMAIN_HOME=<path to domain home>
ProvisionApmJavaAsAgent.cmd /d %DOMAIN_HOME% /no-wallet
3.
Provision the APM Java agent:
a.
Make a backup copy of your startWebLogic.cmd file:
cd %DOMAIN_HOME%\bin
cp startWebLogic.cmd startWebLogic.cmd.orig
b.
Using a text editor, edit the startWebLogic.cmd file and add the javaagent option to the set of JAVA_OPTIONS. Add the following line after
the setDomainEnv.cmd call:
set JAVA_OPTIONS=%JAVA_OPTIONS% -javaagent:%DOMAIN_HOME%\apmagent\lib\system
\ApmAgentInstrumentation.jar
4.
Stop and restart your WebLogic Application Server:
Setting Up Oracle Management Cloud 3-19
Setting Up Application Performance Monitoring
%
%
%
%
cd %DOMAIN_HOME%\bin
stopWebLogic.cmd
cd ..
startWebLogic.cmd > startup.log
Note: Notice that the %DESTINATION% version of startWebLogic.cmd is
used, even though you edited the %DESTINATION%/bin version. Invoking
the command from one level higher (from %DESTINATION%) invokes the
command from a lower level (from %DESTINATION%/bin). However, the
stopWebLogic.cmd command will be called from the %DESTINATION
%/bin directory.
5.
If you have any managed WebLogic application servers, stop and restart them:
% cd %DOMAIN_HOME%\bin
% stopManagedWebLogic.cmd {SERVER_NAME} {ADMIN_URL} {USER_NAME}
{PASSWORD}
% startManagedWebLogic.cmd {SERVER_NAME} {ADMIN_URL} > {SERVER_NAME}.log
Note: If you are running WebLogic as a Windows Service, add the -
javaagent flag to the JAVA_OPTIONS of your custom registration script, and
register your WebLogic Windows Service again.
Installing and Provisioning APM Java Agent on PeopleSoft
You can install and provision APM Java Agent on your PeopleSoft environment.
Prerequisites:
•
PeopleSoft running on PeopleTools 8.55 with WebLogic container for PeopleSoft
UI — PeopleSoft Internet Architecture (PIA)
To install and provision the APM Java Agent on PeopleSoft:
1.
Navigate to the PIA Domain Administration Menu:
a.
From the shell prompt, start the psadmin utility with the following
command:
psadmin
2.
b.
Select 4 for Web (PIA) Server.
c.
Select 1 to administer a domain.
d.
Select the PIA domain where to install the APM agent.
Edit the configuration files:
a.
View the list of configuration files to edit, by executing command 5.
b.
Select 1 to edit the setEnv file. The setEnv file will open in a Vi editor.
c.
Search for the corresponding JAVA_OPTIONS_<Operating System>
variable and add the following option:
JAVA_OPTIONS_<Operating System>="${JAVA_OPTIONS_<Operating System} javaagent:${DOMAIN_HOME}/apmagent/lib/system/ApmAgentInstrumentation.jar"
3-20 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
where <Operating System> is the operating system that PeopleSoft PIA runs
on.
3.
d.
Save the changes made to the setEnv file and exit the Vi editor, to see the list
of configuration files.
e.
Type q to exit this menu, and to see the PIA Administration menu.
Reboot the PIA domain:
a.
Navigate to the PIA Domain Administration menu. Refer step 1.
b.
Select 2 to shut down the domain.
c.
Select 3 to get the status of the domain to check if it is still running.
d.
Select 1 to boot this domain to complete the restart of the PIA domain.
Setting up Application Performance Monitoring on Apache Tomcat
Complete the following tasks sequentially to set up the APM Java Agent on Apache
Tomcat.
•
Preparing to Deploy APM Java Agent on Apache Tomcat
•
Downloading the Master Installer for APM Java Agent
•
Installing and Provisioning APM Java Agent on Apache Tomcat
•
Modifying the Startup Script of Your Apache Tomcat Server
Preparing to Deploy APM Java Agent on Apache Tomcat
Before you can download and install an APM Java Agent, ensure that you set the
staging directory in the target host running the application server. The application you
want to monitor is installed on this application server.
Setting the Staging Directory
Note:
If you are trying to deploy the APM Java Agent agents over a proxy server,
then you need to set the proxy variables, http_proxy and https_proxy on
the host where you’re deploying the agents.
If you’re using a Bash shell:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, ${STAGE_DIR} is the path to a directory that is created by the
download script, where the software is downloaded, and from where you run the
provisioning script that comes with the bundle.
Setting Up Oracle Management Cloud 3-21
Setting Up Application Performance Monitoring
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
export STAGE_DIR=/scratch/apm_staging
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the DESTINATION Variable
Set the DESTINATION variable to point to the Tomcat destination directory.
•
If you're using a Bash shell:
export DESTINATION=<Tomcat destination directory>
•
If you're using a C shell:
setenv DESTINATION "<Tomcat destination directory>"
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
3-22 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
Downloading the Master Installer for APM Java Agent on Tomcat
Download the master installer to a shared directory that can be accessed by all the
managed servers in the application server domain where APM Java Agents will be
deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Java Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to install and deploy the APM
Java agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Java Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
Setting Up Oracle Management Cloud 3-23
Setting Up Application Performance Monitoring
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
Note:
a.
If you’re deploying the APM Java Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Java Agent and
then run AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
b.
If you’re deploying the APM Java Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Java Agent on Apache Tomcat
After you have downloaded and extracted the installer, install and provision the APM
Java Agent in your application server domain.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
To install and provision the APM Java Agent:
1. From your staging directory, run the provisioning script:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME}
The command line displays your tenant name and the value you specified.
2. If you are not using Oracle Wallet, use the -no-wallet option:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME} -no-wallet
3. Review the values and confirm. To change the values, enter n and run the script
again with new values.
4. If you are installing and provisioning the APM Java Agent in environments that
require the use of proxy servers, use these additional options. Contact your
network administrator for these values.
3-24 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
If you are using HTTP Basic authentication,
it is recommended that you omit this
parameter. For details on HTTP Basic
authentication, see Generating Proxy
Token. You can also specify the proxy
wallet entry or NTLM credentials token in
the following format: domain/
username:password. For example:
exampledomain/sampleuser:welcome
Here’s an example of provisioning the APM Java Agent while using a proxy server
with HTTP Basic authentication:
./ProvisionApmJavaAsAgent.sh -d ${CATALINA_HOME} -no-wallet \
-ph "www-proxy.example.com" -pp 80 \
-pt "Basic am9lOmNvb2w="
5. To proceed with the installation, enter y.
The APM Java Agent is installed.
For syntax and more options that can be used with the
ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Modifying the Startup Script of Your Apache Tomcat Server
Modify the startup script of your application server to invoke the Oracle Application
Performance Monitoring Cloud Service configuration settings, when you start your
application server.
To modify the catalina.sh script of your Tomcat server home:
1. Make a copy of your catalina.sh file:
% cd $CATALINA_HOME/bin
% cp catalina.sh catalina.sh.orig
2. Using a text editor, edit the original script to add the -javaagent option to the set
of CATALINA_OPTS. To send the Tomcat server data to APM Agent, append the
following class path, along with ApmAgentInstrumentation.jar to
CATALINA_OPTS:
CATALINA_OPTS="$CATALINA_OPTS -javaagent:${CATALINA_HOME}/apmagent/lib/system/
ApmAgentInstrumentation.jar Datlassian.org.osgi.framework.bootdelegation=oracle.apmaas.*,sun.*,org.apache.xerc
es,org.apache.xerces.*,org.apache.naming,org.apache.naming.*,org.apache.catalina,o
rg.apache.catalina.*,org.apache.tomcat.util.*"
Setting Up Oracle Management Cloud 3-25
Setting Up Application Performance Monitoring
The -Datlassian.org.osgi.framework.bootdelgation option is required
if you are running an Atlassian Jira application.
3. Stop and restart the Tomcat Servers:
% cd $CATALINA_HOME/bin
% ./shutdown.sh
% ./startup.sh
Setting up Application Performance Monitoring on JBoss
Complete the following tasks sequentially, to set up APM Java Agent on JBoss/
WildFly.
•
Preparing to Deploy APM Java Agent on JBoss
•
Downloading the Master Installer for APM Java Agent
•
Installing and Provisioning APM Java Agent on JBoss
•
Modifying the Startup Script of Your JBoss Server
Preparing to Deploy APM Java Agent on JBoss
Before you can download and install an APM Java Agent, ensure that you set the
staging directory in the target host running the application server. The application you
want to monitor is installed on this application server.
Setting the Staging Directory
Note:
If you are trying to deploy the APM Java Agent agents over a proxy server,
then you need to set the proxy variables, http_proxy and https_proxy on
the host where you’re deploying the agents.
If you’re using a Bash shell:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, ${STAGE_DIR} is the path to a directory that is created by the
download script, where the software is downloaded, and from where you run the
provisioning script that comes with the bundle.
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
export STAGE_DIR=/scratch/apm_staging
3-26 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the JBOSS_HOME Variable
Set the JBOSS_HOME variable to point to the JBoss home directory.
•
If you're using a Bash shell:
export JBOSS_HOME=<JBoss home directory>
•
If you're using a C shell:
setenv JBOSS_HOME "<JBoss home directory>"
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
Downloading the Master Installer for APM Java Agent on JBoss
Download the master installer to a shared directory that can be accessed by all the
managed servers in the application server domain where APM Java Agents will be
deployed.
Setting Up Oracle Management Cloud 3-27
Setting Up Application Performance Monitoring
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Java Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to install and deploy the APM
Java agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Java Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
3-28 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM Java Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Java Agent and
then run AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
b.
If you’re deploying the APM Java Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Java Agent on JBoss
After you have downloaded and extracted the installer, install and provision the APM
Java Agent in your JBoss/WildFly server domain.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
To install and provision the APM Java Agent:
1. From your staging directory, run the provisioning script with the no wallet option:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-wallet
The command line displays your tenant name and the value you specified.
2. Review the values and confirm. To change the values, enter n and run the script
again with new values.
3. If you are installing and provisioning the APM Java Agent in environments that
require the use of proxy servers, use these additional options. Contact your
network administrator for these values.
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
Setting Up Oracle Management Cloud 3-29
Setting Up Application Performance Monitoring
Option
Description
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
If you are using HTTP Basic authentication,
it is recommended that you omit this
parameter. For details on HTTP Basic
authentication, see Generating Proxy
Token. You can also specify the proxy
wallet entry or NTLM credentials token in
the following format: domain/
username:password. For example:
exampledomain/sampleuser:welcome
Here’s an example of provisioning the APM Java Agent while using a proxy server
with HTTP Basic authentication:
./ProvisionApmJavaAsAgent.sh -d ${JBOSS_HOME} -no-wallet \
-ph "www-proxy.example.com" -pp 80 \
-pt "Basic am9lOmNvb2w="
4. To proceed with the installation, enter y.
The APM Java Agent is installed.
For syntax and more options that can be used with the
ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Modifying the Startup Script of Your JBoss Server
Modify the startup script of your application server to invoke the Oracle Application
Performance Monitoring Cloud Service configuration settings, when you start your
JBoss/WildFly server.
To modify the standalone.conf script of your JBoss/WildFly server:
1. Make a copy of your standalone.conf file:
% cd \$JBOSS_HOME/bin
% cp standalone.conf standalone.conf.orig
2. Using a text editor, edit the original standalone.conf file:
a.
Search for the text JBOSS_MODULES_SYSTEM_PKGS
b.
Add the following at the end of its value:
oracle.apmaas.agent,oracle.apmaas.repackaged,org.jboss.log
manager
c.
Example: If your standalone.conf file originally contained
JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman", it should look
like the following after adding to the value:
JBOSS_MODULES_SYSTEM_PKGS="org.jboss.byteman,oracle.apmaas
.agent,oracle.apmaas.repackaged,org.jboss.logmanager"
3. Move to the end of the standalone.conf file, and add the following Java
options.
3-30 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
a. JAVA_OPTS="$JAVA_OPTS -
Djava.util.logging.manager=org.jboss.logmanager.LogManager"
b. JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:<JBOSS_HOME>/
modules/org/jboss/logmanager/main/jbosslogmanager-1.2.2.GA.jar:<JBOSS_HOME>/modules/org/jboss/
logmanager/log4j/main/jboss-logmanagerlog4j-1.0.0.GA.jar:<JBOSS_HOME>/modules/org/apache/log4j/
main/log4j-1.2.16.jar"
c. JAVA_OPTS="$JAVA_OPTS -javaagent:<JBOSS_HOME>/apmagent/lib/
system/ApmAgentInstrumentation.jar"
Note:
a.
For the jar files, the location and the version number would be different for
different JBoss versions, provide the correct values while adding the Java
options.
b.
In the above option, <JBOSS_HOME> is the path for the directory where you
have installed JBoss. If you have set the JBOSS_HOME environment variable,
you can use $JBOSS_HOME too.
4. Stop and restart the JBoss Server:
% cd $JBOSS_HOME/bin
% ./jboss-cli.sh -c :shutdown
% nohup ./standalone.sh -b 0.0.0.0&> startup.log &
You can check the entries present in the $JBOSS_HOME/startup.log file to
verify that the JBoss Server has started.
5. If you have any managed JBoss application servers, stop and restart them.
Application Performance Monitoring on JBoss 6.10 EAP
If you are using JBoss 6.10 EAP, you will need to modify the values of the options as
below, for continued functioning of Application Performance Monitoring.
1.
For the option -Djboss.modules.system.pkgs, continue using the same
value, that is:
-Djboss.modules.system.pkgs option, same value as before:JAVA_OPTS=%JAVA_OPTS% Djboss.modules.system.pkgs=org.jboss.byteman,oracle.apmaas.agent,oracle.apmaas.re
packaged,org.jboss.logmanager
2.
For the option -Djava.util.logging.manager, add a new property:
JAVA_OPTS=%JAVA_OPTS% Djava.util.logging.manager=org.jboss.logmanager.LogManager Dorg.jboss.logmanager.configurator=org.jboss.as.logging.logmanager.ConfigurationP
ersistence
3.
For the -Xbootclasspath option, do not specify the jboss-as-logging jar:
JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:<JBOSS_HOME>\modules\system\layers\base
\org\jboss\logmanager\main\jboss-logmanager-1.4.0.Final-redhat-1.jar
4.
The configuration for the instrumentation option remains the same:
JAVA_OPTS=%JAVA_OPTS% -javaagent:<JBOSS_HOME>\apmagent\lib\system
\ApmAgentInstrumentation.jar
Setting Up Oracle Management Cloud 3-31
Setting Up Application Performance Monitoring
Installing and Provisioning APM Java Agent on JBoss on Windows
You can install and provision the APM Java Agent on your JBoss domain installed on
a Windows machine.
•
Download SSL enabled cURL executables for Windows.
•
Download and place Unzip.exe in STAGE_LOC.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
Downloading, installing and provisioning APM Java Agent on JBoss on Windows:
1.
Download the APM Java Agent bits in the staging location by running the
following commands:
set REG_KEY=<Registration key>
set STAGE_LOC=<staging location>
AgentInstall.bat AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=%STAGE_LOC%
AGENT_REGISTRATION_KEY=%REG_KEY%
cd %STAGE_LOC%
2.
Run the following command to provision the APM Java agent:
set the DOMAIN HOME : set JBOSS_HOME=<JBoss_Home Path>
ProvisionApmJavaAsAgent.cmd /d %JBOSS_HOME% /no-wallet
3.
Provision the APM Java agent:
a.
Make a backup copy of your standalone.conf.bat file:
%cd %JBOSS_HOME%\bin
%cp standalone.conf.bat standalone.conf.bat.orig
b.
Using a text editor, edit the standalone.conf.bat file. Search for the text
Djboss.modules.system.pkgs=, and add
oracle.apmaas,org.jboss.logmanager to it.
For example, if the original text is,
-Djboss.modules.system.pkgs=org.jboss.byteman
the new text will be
Djboss.modules.system.pkgs=org.jboss.byteman,oracle.apmaas,org.jboss.logmana
ger
4.
At the end of the file, add these statements, after modifying the location and
versions of these .jar files specific to your installation. If needed, you can
download the .jar files and modify the paths in the below statements:
set "JAVA_OPTS=%JAVA_OPTS% Djava.util.logging.manager=org.jboss.logmanager.LogManager"
set "JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:<JBOSS_HOME>\modules\system\layers
\base\org\jboss\logmanager\main\jboss-logmanager-1.5.4.Final-
3-32 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
redhat-1.jar;<JBOSS_HOME>\modules\system\layers\base\org\jboss\log4j\logmanager
\main\log4j-jboss-logmanager-1.1.1.Final-redhat-1.jar"
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:<JBOSS_HOME>\apmagent\lib\system
\ApmAgentInstrumentation.jar"
5.
Stop and restart the JBoss Server:
% cd <JBOSS_HOME>\bin
% ./standalone.bat -b 0.0.0.0
You can check the entries present in the <JBOSS_HOME>\startup.log file to
verify that the JBoss Server has started.
6.
If you have any managed JBoss application servers, stop and restart them.
Setting up Application Performance Monitoring on WebSphere
Complete the following tasks sequentially, to set up APM Java Agent on WebSphere.
•
Preparing to Deploy APM Java Agent on WebSphere
•
Downloading the Master Installer for APM Java Agent
•
Installing and Provisioning APM Java Agent on WebSphere
•
Modifying the Startup Script of Your WebSphere Server
Preparing to Deploy APM Java Agent on WebSphere
Before you can download and install an APM Java Agent, ensure that you set the
staging directory in the target host running the application server. The application you
want to monitor is installed on this application server.
Setting the Staging Directory
Note:
If you are trying to deploy the APM Java Agent agents over a proxy server,
then you need to set the proxy variables, http_proxy and https_proxy on
the host where you’re deploying the agents.
If you’re using a Bash shell:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, ${STAGE_DIR} is the path to a directory that is created by the
download script, where the software is downloaded, and from where you run the
provisioning script that comes with the bundle. Ensure that ${STAGE_DIR} has write
permissions as scripts will be copied to this directory.
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Setting Up Oracle Management Cloud 3-33
Setting Up Application Performance Monitoring
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
export STAGE_DIR=/scratch/apm_staging
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the WAS_HOME Variable
Set the WAS_HOME variable to point to the WebSphere Server domain directory.
•
If you're using a Bash shell:
export WAS_HOME=<WebSphere Server Domain>
•
If you're using a C shell:
setenv WAS_HOME "<WebSphere Server Domain>"
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
3-34 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Downloading the Master Installer for APM Java Agent on WebSphere
Download the master installer to a shared directory that can be accessed by all the
managed servers in the application server domain where APM Java Agents will be
deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Java Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to install and deploy the APM
Java agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Java Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
Setting Up Oracle Management Cloud 3-35
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM Java Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Java Agent and
then run AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
b.
If you’re deploying the APM Java Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Java Agent on WebSphere
After you have downloaded and extracted the installer, install and provision the APM
Java Agent in your WebSphere server domain.
•
Before you install the APM Java Agent, log in to the machine running the
application server as the user identity your WebSphere runs as.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
To install and provision the APM Java Agent:
1. From your staging directory, run the provisioning script with the no wallet option:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${WAS_HOME} -no-wallet
The command line displays your tenant name and the value you specified.
2. Review the values and confirm. To change the values, enter n and run the script
again with new values.
3. If you are installing and provisioning the APM Java Agent in environments that
require the use of proxy servers, use these additional options. Contact your
network administrator for these values.
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
3-36 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Option
Description
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
If you are using HTTP Basic authentication,
it is recommended that you omit this
parameter. For details on HTTP Basic
authentication, see Generating Proxy
Token. You can also specify the proxy
wallet entry or NTLM credentials token in
the following format: domain/
username:password. For example:
exampledomain/sampleuser:welcome
Here’s an example of provisioning the APM Java Agent while using a proxy server
with HTTP Basic authentication:
./ProvisionApmJavaAsAgent.sh -d ${WAS_HOME} -no-wallet \
-ph "www-proxy.example.com" -pp 80 \
-pt "Basic am9lOmNvb2w="
4. To proceed with the installation, enter y.
The APM Java Agent is installed.
For syntax and more options that can be used with the
ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Modifying the Startup Script of Your WebSphere Server
Modify the startup script of your WebSphere application server to invoke the Oracle
Application Performance Monitoring Cloud Service configuration settings, when you
start your WebSphere server.
To modify the server.policy startup script of your WebSphere server:
1. From your WebSphere Admin console, click the Servers tab and select the server
on which you want to provision the APM Java Agent.
2. Expand Java and Process Management tab and select Process Definition.
3. Under Additional Properties tab, select Java Virtual Machine.
4. In the Generic JVM arguments field, add the following line to —javaagent and -
Dws.ext.dirs flags:
-javaagent:\$WAS_HOME/apmagent/lib/system/
ApmAgentInstrumentation.jar -Dws.ext.dirs=\$WAS_HOME/
apmagent/lib/agent/ApmEumFilter.jar
5. Make a copy of your server.policy file:
% cd $WAS_HOME/properties
% cp server.policy server.policy.orig
6. Using a text editor, edit the original server.policy file:
Setting Up Oracle Management Cloud 3-37
Setting Up Application Performance Monitoring
grant codeBase "file:$WAS_HOME/apmagent/-"
{
permission java.security.AllPermission;
};
7. From your WebSphere administration console, stop and start the WebSphere
server. You can also use the command line:
cd $WAS_HOME/bin
./stopServer.sh <servername>
./startServer.sh <servername>
Setting up Application Performance Monitoring on Jetty
Complete the following tasks sequentially to set up the APM Java Agent on Jetty.
•
Preparing to Deploy APM Java Agent on Jetty
•
Downloading the Master Installer for APM Java Agent on Jetty
•
Installing and Provisioning APM Java Agent on Jetty
•
Modifying the Startup Script of Your Jetty Server
Preparing to Deploy APM Java Agent on Jetty
Before you can download and install an APM Java Agent, ensure that you set the
staging directory in the target host running the application server. The application you
want to monitor is installed on this application server.
Setting the Staging Directory
Note:
If you are trying to deploy the APM Java Agent agents over a proxy server,
then you need to set the proxy variables, http_proxy and https_proxy on
the host where you’re deploying the agents.
If you’re using a Bash shell:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, ${STAGE_DIR} is the path to a directory that is created by the
download script, where the software is downloaded, and from where you run the
provisioning script that comes with the bundle.
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
3-38 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
export STAGE_DIR=/scratch/apm_staging
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the JETTY_HOME Variable
Set the JETTY_HOME variable to point to the Jetty destination directory.
•
If you're using a Bash shell:
export JETTY_HOME=<Jetty destination directory>
•
If you're using a C shell:
setenv JETTY_HOME"<Jetty destination directory>"
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
Setting Up Oracle Management Cloud 3-39
Setting Up Application Performance Monitoring
Downloading the Master Installer for APM Java Agent on Jetty
Download the master installer to a shared directory that can be accessed by all the
managed servers in the web server domain where APM Java Agents will be deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Java Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to install and deploy the APM
Java agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Java Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
3-40 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM Java Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Java Agent and
then run AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
b.
If you’re deploying the APM Java Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_java_as_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Java Agent on Jetty
After you have downloaded and extracted the installer, install and provision the APM
Java Agent in your application server domain.
•
Before you install the APM Java Agent, log in to the machine running the
application server as a user who installed the application server.
•
The application server user should have Read-Write access to the APM Java Agent
directories.
To install and provision the APM Java Agent:
1. From your staging directory, run the provisioning script:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JETTY_HOME}
The command line displays your tenant name and the value you specified.
2. If you are not using Oracle Wallet, use the -no-wallet option:
cd ${STAGE_DIR}
chmod +x ProvisionApmJavaAsAgent.sh
./ProvisionApmJavaAsAgent.sh -d ${JETTY_HOME} -no-wallet
3. Review the values and confirm. To change the values, enter n and run the script
again with new values.
4. If you are installing and provisioning the APM Java Agent in environments that
require the use of proxy servers, use these additional options. Contact your
network administrator for these values.
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
Setting Up Oracle Management Cloud 3-41
Setting Up Application Performance Monitoring
Option
Description
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
If you are using HTTP Basic authentication,
it is recommended that you omit this
parameter. For details on HTTP Basic
authentication, see Generating Proxy
Token. You can also specify the proxy
wallet entry or NTLM credentials token in
the following format: domain/
username:password. For example:
exampledomain/sampleuser:welcome
Here’s an example of provisioning the APM Java Agent while using a proxy server
with HTTP Basic authentication:
./ProvisionApmJavaAsAgent.sh -d ${JETTY_HOME} -no-wallet \
-ph "www-proxy.example.com" -pp 80 \
-pt "Basic am9lOmNvb2w="
5. To proceed with the installation, enter y.
The APM Java Agent is installed.
For syntax and more options that can be used with the
ProvisionApmJavaAsAgent.sh script, see Syntax for Using the Installation Script.
Modifying the Startup Script of Your Jetty Server
Modify the startup script of your application server to invoke the Oracle Application
Performance Monitoring Cloud Service configuration settings, when you start your
application server.
To modify the java -jar start.jar script of your Jetty server home:
1. Make a copy of your java -jar start.jar file:
% cd $JETTY_HOME/bin
% cp java -jar start.jar java -jar start.jar.orig
2. Using a text editor, edit the original script to add the -javaagent option. To send
the Jetty server data to APM Agent, append the following class path, along with
ApmAgentInstrumentation.jar
java -javaagent:/scratch/apmagent/lib/system/ApmAgentInstrumentation.jar -jar
start.jar
3. Stop and restart the Jetty server.
Verifying APM Java Agent Installation
You can verify that the installation of Oracle Application Performance Monitoring
Cloud Service is successful by examining the logs and verifying that the user interface
3-42 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
displays the Application Server. You can also verify the structure of the installation
directory.
Verify that the installation of Application Performance Monitoring is successful by:
1. Examining the APM Java Agent Logs
2. Using the Application Performance Monitoring Web UI
3. Verifying the APM Java Agent Directory Structure
Examining the APM Java Agent Logs
Examine the log files after installing Application Performance Monitoring:
1. Verify that the Application Performance Monitoring log directories and files were
created.
a. After restarting the application server, verify that the APM Java Agent created a
log directory for each server it is now monitoring:
% cd $DESTINATION/apmagent/logs
% ls -lF
Verify that the following log directory was created:
$DESTINATION/apmagent/logs/<application server name>
b. If there are multiple servers in the domain, as each server is restarted, it will be
represented by a separate directory under $DESTINATION/apmagent/logs.
For example, if you are monitoring the Application Server, AdminServer1, you
should see the following entry:
$DESTINATION/apmagent/logs/AdminServer1
c. Verify that the correct set of log files were created inside each server log
directory:
% cd $DESTINATION/apmagent/logs/AdminServer
% ls -lF *.log
Verify that the following set of log files were added to the directory along with
other files:
•
AgentErrors.log
•
Agent.log
•
AgentStartup.log
•
AgentStatus.log
If all the expected log directories and the log files were not created, then the
Application Performance Monitoring installation was not successful.
2. Check for errors in the AgentErrors.log file. The AgentErrors.log file
should have a line similar to the following:
% more AgentErrors.log
<2015-01-16T12:36:27.27-0800> INFO Exception log is initialized
Setting Up Oracle Management Cloud 3-43
Setting Up Application Performance Monitoring
3. In the AgentStartup.log file, the message Agent startup successfully completed
should be seen.
4. Look for agent activity in the AgentStatus.log file.
As the APM Java Agent starts monitoring traffic, it logs short status information in
the AgentStatus.log file.
If the traffic and transport counts are more than zero, then that indicates that the
APM Java Agent is active, and it is monitoring and reporting data successfully.
Verifying the Installation Using the Application Performance Monitoring Web User Interface
Access the Application Performance Monitoring web user interface from the Oracle
Management Cloud home page and verify that the Application Performance
Monitoring installation was successful.
To check for successful Application Performance Monitoring installation from the web
user interface:
1. Log in to the Oracle Management Cloud home page.
2. In the Oracle Management Cloud Home page, click the Application Performance
Monitoring tile.
The Application Performance Monitoring home page is displayed.
3. Ensure that your user name is displayed in the upper right corner of the home
page.
4. To verify that your Application Server was discovered, in the Application
Performance Monitoring home page, click AppServers.
Your application server should be displayed in the AppServers view.
5. Use your applications, and then check for data in the Application Performance
Monitoring UI.
a. Use the application that you want to monitor, and make multiple transactions.
b. In the Application Performance Monitoring home page, click the Time Selector
drop-down list and select Last Hour.
c. See the Top 5 Server Requests or click the number above Server Requests to see
the Server Requests view.
d. If you are on the Enterprise Edition, click Pages to see the Pages view.
Ensure that the operations you performed on the application are reflected in the
Server Requests or the Pages view.
Verifying the APM Java Agent Directory Structure
After installing and provisioning APM Java Agent, you can find the following
directory structure on your WebLogic Managed Server.
3-44 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Directory
Sub-directory
Description
${DOMAIN_HOME}
—
The home directory of the WebLogic Server domain, where the
APM Java Agent is installed.
apmagent
—
The root of the APM Java Agent's installation directory. No files
are stored directly in this directory. Note that there will be exactly
one APM Java Agent installation directory for this domain (on this
host) regardless of how many WebLogic Servers are being
monitored.
config/
—
All of the APM Java Agent's domain-level configuration files are
stored directly in this directory.
—
agentWallet
If this domain is using an Oracle Wallet to hold the APM Java
Agent's Authorization Token (acting as the APM Java Agent's
Credential Store), then this directory will exist, and will hold the
cwallet.sso file which is the wallet.
—
(server 1)
For each server in the domain that is being monitored, a
configuration directory will be created when the APM Java Agent
first discovers that server. Configuration data that can be modified
on a server-by-server basis (as opposed to that for the entire
domain), will be found here.
...(server N)
lib/
—
All of the APM Java Agent's .jar files will be found under the lib
directory.
—
action
The three sub-directories under the lib directory.
agent
system
Setting Up Oracle Management Cloud 3-45
Setting Up Application Performance Monitoring
Directory
Sub-directory
Description
logs/
—
The APM Java Agent's log files will be stored in one of this
directory's sub-directories. No files will be found directly in this
directory.
—
(server 1)
For each server in the domain being monitored, a log directory
will be created when the APM Java Agent first discovers that
server. All log files pertaining to a particular server will be stored
in these sub-directories.
...(server N)
Setting Up APM .Net Agents
Complete these tasks sequentially to deploy the APM .NET Agent.
•
Prerequisites for Deploying APM .Net Agent
•
Preparing to Deploy APM .Net Agent
•
Downloading the Master Installer for APM .NET Agent
•
Installing APM .Net Agent
•
Verifying APM .Net Agent Installation
•
Configuring APM .Net Agent Parameters
•
Disabling Monitoring by APM .Net Agent
Prerequisites for Deploying APM .Net Agent
The section covers the key considerations and prerequisites for deploying APM .Net
Agent.
Prerequisites
•
Windows Server 2008 and above
•
.Net Framework 3.5 and above
•
cURL with SSL support
•
UnZip software
•
Other considerations:
–
The machine hosting the IIS Server should be able to establish an HTTPS
connection (either over a proxy server or not) to Oracle Management Cloud.
–
Administrator Access to the machine where APM .Net Agent will be
deployed
–
Ability to restart IIS
Preparing to Deploy APM .Net Agent
Before you can download and install an APM .Net Agent, ensure that you set the
staging directory in the target host running the IIS server.
3-46 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Setting the Staging Directory
Note:
If you are deploying the APM .Net agent over a proxy server, then you need
to set the following environment variables through the command line where
you will execute AgentInstall.bat:
•
set http_proxy=http://www-hostname.abc.com:<port>/
•
set https_proxy=http://wwwhostname.example.com:<port>/
The staging directory, %STAGE_DIR% is the path to a directory that is created by the
download script, where the software is downloaded, and executed from.
Note: The staging directory must not exist prior to running the
AgentInstall.bat downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
set STAGE_DIR=%TEMP%\apm_staging
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
set REG_KEY=<Registration Key>
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
set GW_HOST "<Gateway Host Name>"
set GW_PORT "<Gateway Port>"
Downloading the Master Installer for APM .NET Agent
Download the master installer to a temporary directory from where APM .Net Agent
will be deployed.
Setting Up Oracle Management Cloud 3-47
Setting Up Application Performance Monitoring
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM .Net Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.bat: The installation script used to deploy the APM .Net
agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.bat script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM .Net Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
AgentInstall.bat AGENT_TYPE=apm_dotnet_agent STAGE_LOCATION=%STAGE_DIR%
AGENT_REGISTRATION_KEY=%REG_KEY% -download_only
3-48 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM .Net Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM .Net Agent, and
then run AgentInstall.bat.
b.
If you’re deploying the APM .Net Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
AgentInstall.bat AGENT_TYPE=apm_dotnet_agent STAGE_LOCATION=%STAGE_DIR%
AGENT_REGISTRATION_KEY=%REG_KEY% -download_only GATEWAY_HOST=${GW_HOST}
GATEWAY_PORT=${GW_PORT}
Your directory should contain the following files along with the other APM .Net
Agent installation content:
a.
OMC.ini which will be used while installing the APM .Net Agent.
b.
emcs.cer required in case the machine does not recognize the Oracle
certificate.
10. If the APM .Net Agent needs to go through a proxy, edit the OMC.ini file
providing these additional values as required:
•
proxy host
•
proxy port. By default, the value is 8080.
•
proxy user name - applicable if the proxy requires authentication
•
proxy password - applicable if the proxy requires authentication
•
domain - applicable if the proxy requires specifying the domain
11. Enable the performance counters of the IIS application you wish to monitor. For
this, the application pool user must be a member of the 'Performance Monitor
Users' group. Refer to the Microsoft IIS documentation for detailed instructions.
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing APM .Net Agent
After you have downloaded and extracted the installer, install the APM .Net Agent in
your IIS server domain.
To install the APM .Net Agent on your IIS server:
1. Stop the IIS server.
iisreset /stop
2. Execute the APM .Net Agent installer.
a.
Ensure that the OMC.ini file is in the same directory as the ApmAgent.msi
file.
b.
Run the ApmAgent.msi executable. The APM .Net Agent installation wizard
guides you through the installation process.
Setting Up Oracle Management Cloud 3-49
Setting Up Application Performance Monitoring
c.
Specify the installation directory.
d.
Specify the host name.
e.
Select the applications to be monitored in the Monitored Application
Configuration screen. You can choose to monitor all applications on the IIS
server, or manually select specific applications from the list.
f.
Click Install.
3. Start your IIS server.
iisreset /start
Verifying APM .Net Agent Installation
You can verify that the installation of Oracle Application Performance Monitoring
Cloud Service is successful by examining the logs and verifying that the user interface
displays the Application Server. You can also verify the structure of the installation
directory.
Verify that the installation of Application Performance Monitoring is successful by:
1. Using the Application Performance Monitoring Web UI
2. Examining the APM .Net Agent logs located at C:\ProgramData\Oracle
\ApmAgent\logs\<site>\.
Note that the log files are not initially created, even if the installation of APM was
successful. The log files get created and populated only when the application you
are monitoring is running, and shows some activity which results in data depicted
on the Application Performance Monitoring Web UI.
•
If the agent logs are empty without any data, check the Windows Event
Viewer for any possible problems with the agent installation. (See Custom
Views and select Administrative Events.)
•
If you see the following message
The underlying connection was closed: Could not establish trust relationship for the
SSL/TLS secure channel
in the agent logs, it means that the OMC certificate was not provisioned since
the certificate was not available. Add the root certificate emcs.cer to the
trusted root certification authorities on your local machine. See https://
technet.microsoft.com/en-in/library/cc754841.aspx#BKMK_addlocal.
Configuring APM .Net Agent Parameters
You can configure deployment parameters of your APM .Net Agent to control the
monitoring of applications.
•
APM .Net Agent Installation Directories
•
Configuration Directory
•
Logs Directory
•
Important Considerations
3-50 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
•
Configuration Settings
•
Proxy and Gateway Settings
APM .Net Agent Installation Directories
The APM .Net Agent installation directory has an installation directory, configuration
directory and logs directory.
The agent installation directory is specified by the environment
variable ORACLE_APM_AGENT_HOME, which gets automatically set by the installer.
Each agent instance contains configuration directory and logs directory.
Examples:
Installation Directory: c:\Program Files\Oracle APM .Net Agent
Configuration directory:c:\ProgramData\Oracle\ApmAgent\config
\<appName>
Logs directory: c:\ProgramData\Oracle\ApmAgent\logs\<appName>
Configuration Directory
By default, the agent configuration directory for a monitored application is c:
\ProgramData\Oracle\ApmAgent\config\<appName>.
You can customize the configuration of an APM .Net agent instance by adding an
AgentConfig.ini file to the configuration directory. By customizing the
configuration you can disable or turn log traces for a specific agent.
After you have made the configuration changes, only the agent instance using this
configuration directory will detect the configuration change and restart. If several
agent instances are monitoring the same replicated application, all agent instances will
detect the configuration change and restart.
Logs Directory
The APM .Net Agent logs directory contains three log files: AgentStartup.log,
AgentStatus.log and Agent.log.
•
AgentStartup.log contains the agent logs related to startup. You can verify if
the agent started up correctly from this file.
•
Agent.log contains all agent logs, including the logs found in AgentStartup.
The change the level of logging in these files, see Configuration Settings.
Important Considerations
Some important considerations before configuring the parameters:
1.
Any change to the installed configuration files (AgentConfig.ini and
OMC.ini), applies to all agent instances running on the machine.
2.
An agent automatically detects any change to any of its configuration files. When
this happens an agent restarts, making any new setting immediately active. If a
change is made to the installation directory configuration files
(AgentConfig.ini or OMC.ini), all agents on the machine restart reading the
changed configuration files as they start up. If a specific AgentConfig.ini
Setting Up Oracle Management Cloud 3-51
Setting Up Application Performance Monitoring
configuration file gets changed (e.g., from an agent instance configuration
directory), only the specific agent restarts.
Configuration Settings
Property
Description
oracle.apmaas.agent.disable
Defaults to False when not specified. If
set to True, the agent is disabled (agent
instance is shutdown).
oracle.apmaas.agent.trace.bootstrap.limito
racle.apmaas.agent.trace.bootstrap.rotatio
n
oracle.apmaas.agent.trace.startup.limit
oracle.apmaas.agent.trace.startup.rotation
oracle.apmaas.agent.trace.status.limit
oracle.apmaas.agent.trace.status.rotation
oracle.apmaas.agent.trace.limit
oracle.apmaas.agent.trace.rotation
oracle.apmaas.agent.trace.<area> =
<level>
oracle.apmaas.agent.trace = <level>
oracle.apmaas.agent.trace.flow =
verbose
AgentBootstrap log file settings —
•
Rotation default is 2
•
Limit default is 20 Mb
•
Limit indicated in Mbs (Example: 10
for 10 Mb)
AgentStartup log file settings —
•
Rotation default is 2
•
Limit default is 20 Mb
•
Limit indicated in Mbs (Example: 10
for 10 Mb)
AgentStatus log file settings —
•
Rotation default is 2
•
Limit default is 20 Mb
•
Limit indicated in Mbs (Example: 10
for 10 Mb)
Agent log file settings —
•
Rotation default is 2
•
Limit default is 20 Mb
•
Limit indicated in Mbs (Example: 10
for 10 Mb)
area: Instrumentation, Startup,
Http, MetricsProcessor,
Sampling, Handler, Transport,
Config, InternalMetrics,
SqlServer, Utility, Injection
level: verbose, all, off
All trace areas
level: verbose, all, off
When the trace area flow is enabled with
the level verbose, detailed traces of the
flow processor are logged in a file named
AgentFlowTrace.log. See section below
for details.
3-52 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Property
Description
oracle.apmaas.agent.trace.overhead
= verbose | all
Enable this to get a dedicated log file
named AgentOverheadStatus.log
created. The file contains metrics on probe,
transport (verbose) and optionally JSON,
core runtime (all) internal processing
overhead metrics, and some memory
metrics. These metrics can be used to get
the time that the agent adds (overhead) to
the monitored application, in
microseconds. Note that fetching these
metrics also adds overhead, so the real
overhead is few microseconds less than the
logged overhead.
oracle.apmaas.agent.trace.overhead.
format = csv | json
Set this property value to csv to get a
Comma Separated Values output format
instead of a user readable text format (this
applies to the
AgentOverheadStatus.log file). Set
this value to json to create separate JSON
files. If the json format is specified, the file
AgentOverheadStatus.log is not
created (since decated files are created
instead).
oracle.apmaas.agent.trace.observations =
verbose
Set this property to log all observations
sent by the agent in a local file, within the
agent log directory. By default, the file
name is Observations.log. Use one of
properties below instead of this one to
specify a different file name.
Setting Up Oracle Management Cloud 3-53
Setting Up Application Performance Monitoring
Property
oracle.apmaas.agent.testServerUrl = file
| url
OR
oracle.apmaas.agent.trace.observations.loc
ationUrl = file | url
Description
Set any of these properties to a file name to
log observations within the specified file
name in the agent log directory. If a URL is
specified (typically the URL AgentCLI
listens on), observations will be sent to the
specified URL. If the agent is setup to
communicate with cloud services,
observations will be sent both to cloud
services and to the specified URL. To
disable communication with cloud services
and only have the agent communicate with
the specific URL, set the property
oracle.apmaas.agent.test.skipClo
udStartup=true
Note that if you log observations within a
file, you can also use the following setting:
oracle.apmaas.agent.trace.observations
.maxSizeMB (same as limit, defined
for Java cross platform
compatibility)
oracle.apmaas.agent.trace.observations
.limit (same semantic as limit
described above)
oracle.apmaas.agent.trace.observations
.rotation (same semantic as rotation
described above)
oracle.apmaas.agent.trace.observations
.prettyPrint (set it to true, to
pretty print logged observations)
oracle.apmaas.agent.identity.concurrent.ma
x
Maximum number of agents allowed to
run concurrently (should be equal to
max_worker_proecess defined in
ApplicationPool.
The default value is 1.
oracle.apmaas.agent.lock.identity.waitInMs
When all agent identities are being used,
this property defines how long (in ms)
the .Net agent will wait before trying to
retrieve agent identity again.
The default value is 10 seconds.
oracle.apmaas.agent.lock.identity.waitTime
sToWriteLog
When all agent identities are being used
and the .Net agent is trying to retrieve
agent identity again, this property defines
after how many times of trying, the .Net
agent will write a log to inform user that it
is still trying. The first trying will always
be logged.
The default value is 120.
3-54 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Proxy and Gateway Settings
If you are installing and provisioning the APM .Net Agent in environments that
require the use of proxy servers, use these additional options. Contact your network
administrator for these values.
Proxy Parameters
Option
Description
oracle.apmaas.agent.proxyHost
The proxy server’s host name. This is an
optional parameter.
oracle.apmaas.agent.proxyPort
The proxy server’s port. This is an optional
parameter.
oracle.apmaas.agent.proxyAuthUser
This is the user name the agent will use if the
proxy server requires authentication.
oracle.apmaas.agent.proxyAuthPass
word
This is the password required if the proxy
server requires authentication.
oracle.apmaas.agent.proxyAuthDoma
in
This is the name of the domain if the proxy
server requires authentication.
If you are installing and provisioning the APM .Net Agent in environments that
require the use of Gateway, use these additional options. Contact your network
administrator for these values.
Gateway Parameters
Option
Description
oracle.apmaas.agent.uploadRoot
The APM agent’s root directory.
oracle.apmaas.agent.collectorRoot
The APM agent’s collector root.
Disabling Monitoring by APM .Net Agent
You can disable monitoring by Application Performance Monitoring on certain pages.
In the APM .Net Agent’s configuration file, make the following settings:
•
To disable monitoring: oracle.apmaas.agent.jsinjection=false
•
To disable specific URLs:
oracle.apmaas.agent.jsinjection.disableRegex=<regex>
•
Add oracle.apmaas.agent.browser.observations
Setting Up APM Node.js Agents
Complete these tasks sequentially to deploy the APM Node.js Agent.
•
Prerequisites for Deploying APM Node.js Agent
•
Preparing to Deploy APM Node.js Agent
•
Downloading the Master Installer for APM Node.js Agent
Setting Up Oracle Management Cloud 3-55
Setting Up Application Performance Monitoring
•
Installing and Provisioning APM Node.js Agent
•
Starting your Node.js Application
•
Verifying that the APM Node.js Agent is Monitoring the Application
•
Configuring Browser Injection with APM Node.js Agent
•
Configuring Specific URLs for Oracle Management Cloud Services
Prerequisites for Deploying APM Node.js Agent
The section covers the key considerations and prerequisites for deploying APM
Node.js Agent.
Prerequisites
•
cURL with SSL support
•
Unzip
•
Other considerations:
–
The machine where you install the APM Node.js Agent should be able to
establish an HTTPS connection (either over a proxy server or not) to Oracle
Management Cloud.
Preparing to Deploy APM Node.js Agent
Before you can deploy the APM Node.js Agent, ensure that you complete the
following preparation.
Create a Staging Directory
Create a staging directory, $STAGE_DIR or %STAGE_DIR% in the folder where the
APM Node.js Agent software is extracted, and executed from.
Note:
If you are deploying the APM Node.js agent over a proxy server, then you
need to set the following environment variables through the command line
where you will execute AgentInstall.sh:
•
set http_proxy=http://www-hostname.abc.com:<port>/
•
set https_proxy=http://wwwhostname.example.com:<port>/
Set the environment variable to the staging directory:
Windows: set STAGE_DIR=%TEMP%\apm_staging
Linux: setenv STAGE_DIR /scratch/apm_staging
Setting the NODE_PATH Variable
Set the NODE_PATH variable to point to node_modules:
•
On Linux:
3-56 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
<Node Installation Directory>/lib/node_modules
•
On Windows:
<USER_HOME>\AppData\Roaming\npm\node_modules
Setting the NODE_APP_HOME Variable
Set the NODE_APP_HOME variable to point to the folder in which the node application
is running.
•
If you're using a Bash shell:
export NODE_APP_HOME=<Node Application Directory>
•
If you're using a C shell:
setenv NODE_APP_HOME "<Node Application Directory>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
setenv GW_HOST "<Gateway Host Name>"
setenv GW_PORT "<Gateway Port>"
Downloading the Master Installer for APM Node.js Agent
Download the master installer to a temporary directory from where APM Node.js
Agent will be deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Node.js Agent in your data center.
4. Click Next to proceed.
Setting Up Oracle Management Cloud 3-57
Setting Up Application Performance Monitoring
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh or AgentInstall.bat : The installation script used to
deploy the APM Node.js agent. You can see a list of supported parameters and
their definitions in Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.bat or AgentInstall.bat script to install agents on your
target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Node.js Agent deployed on your on-premises
hosts. For more information about creating a registration key, see Creating a
Registration Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_nodejs_agent STAGE_LOCATION=%STAGE_DIR%
AGENT_REGISTRATION_KEY=%REG_KEY% -download_only
3-58 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM Node.js Agent over a proxy server, ensure
that you perform the steps listed in Preparing to Deploy APM .Net Agent,
and then run AgentInstall.bat or AgentInstall.sh.
Your directory should contain the following files along with the other
APM Node.js Agent installation content:
b.
i.
agent_software_build.xml
ii.
ProvisionApmNodeAgent.sh
iii.
ProvisionApmNodeAgent.cmd
iv.
emcs.cer required in case the machine does not recognize the
Oracle certificate.
v.
oracle-apm-config.json
vi.
oracle-apm-1.7.5.tgz
If you’re deploying the APM Node.js Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_nodejs_agent STAGE_LOCATION=$
{STAGE_DIR} AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
GATEWAY_HOST=${GW_HOST} GATEWAY_PORT=${GW_PORT}
10. If the APM Node.js Agent needs to go through a proxy, edit the oracle-apm-
config.json file providing these additional values as required:
•
proxy host
•
proxy port. By default, the value is 8080.
•
proxy user name - applicable if the proxy requires authentication
•
proxy password - applicable if the proxy requires authentication
•
domain - applicable if the proxy requires specifying the domain
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Node.js Agent
After you have downloaded and extracted the installer, install the APM Node.js
Agent.
To install the APM Node.js Agent :
1. Execute the APM Node.js Agent installer.
Setting Up Oracle Management Cloud 3-59
Setting Up Application Performance Monitoring
Note: The Provisioning script will compute a default hostname and use that
as one of the ID attributes. To override the default, run the provisioning script
with the ORACLE_HOSTNAME argument.
Example:
•
On Linux:
./ProvisionApmNodeAgent.sh -h <hostname>
•
On Windows:
ProvisionApmNodeAgent /h=<hostname>
•
cd ${STAGE_DIR}
ProvisionApmNodeAgent
Note: Ensure that the above script is run from a regular command prompt,
and not from the Windows Power Shell.
•
On Linux:
cd ${STAGE_DIR}
chmod +x ProvisionApmNodeAgent.sh
./ProvisionApmNodeAgent.sh
2. If you are installing and provisioning the APM Node.js Agent in environments that
require the use of proxy servers, use these additional options. Contact your
network administrator for these values.
Option
Description
-ph {http_proxy_host}
The proxy server’s host name. This is an
optional parameter.
-pp {http_proxy_port}
The proxy server’s port. This is an optional
parameter.
-pt {http_proxy_auth_token}
This is the authorization token that the
agent will use if the proxy server requires
authentication. This is an optional
parameter that will be passed literally as
the proxy authorization header to the proxy
server.
Verify the installation:
1.
Ensure that the oracle-apm directory is created in the node_modules
directory of your Node installation as below.
On Linux: $NODE_HOME/lib/node_modules
On Windows: <USER_HOME>\AppData\Roaming\npm\node_modules
2.
In the node_modules directory, within oracle-apm, a folder called data is
created with the following files:
•
oracle-apm-config.json
3-60 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
•
emcs.cer
Troubleshooting
If you see this error — npm ERR! code 1 - error, ignore it. This is an indication
that oracle-apm agent was not installed previously.
Starting your Node.js Application
Once you install the APM Node.js Agent, configure the application to get monitored.
1.
Stop the Node application to be monitored.
2.
Set the NODE_PATH environment variable to point to node_modulesas below.
On Linux: $NODE_HOME/lib/node_modules
On Windows: <USER_HOME>\AppData\Roaming\npm\node_modules
3.
Navigate to your application's entry point js file and add the below line at the
top of the file:
require('oracle-apm');
Here is an example of a file after adding the above line:
require('oracle-apm');
var express = require('express');
var app = express();
app.get('/', function (req, res) {
res.send('Hello World!');
});
app.listen(3000, function () {
console.log('Example app listening on port 3000!');
});
4.
Start the application.
Example: node /scratch/Apps/MyApp/server.js
Verifying that the APM Node.js Agent is Monitoring the Application
You can verify that the deployment of the APM Node.js Agent is successful by
examining the logs and verifying that the user interface displays the application. You
can also verify the structure of the installation directory.
Verify that the installation of Application Performance Monitoring is successful by:
1. Examining the APM Node.js Agent logs located at <APP_HOME>/oracle-apm/
logs.
Note that the log files are not initially created, even if the installation of APM was
successful. The log files get created and populated only when the application you
are monitoring is running, and shows some activity which results in data depicted
on the Application Performance Monitoring Web UI.
2. Looking for Expected Directories and Files
Once your Node.js application is started, the following directories and files are
available under the folder that contains your main module (NODE_APP_HOME):
Setting Up Oracle Management Cloud 3-61
Setting Up Application Performance Monitoring
•
oracle-apm
|___ config
|____ oracle-apm-config.json
|___ identities
|____ AgentIdentity_server.json
|___ logs
|____ Agent_server.log
•
The config folder contains just one file - oracle-apm-config.json that
has configuration information to connect to Oracle Management Cloud.
•
The identities folder contains the agent identity. This will have as many
files as the number of main modules in your current NODE_APP_HOME. The
files will be named as AgentIdentity_<main_module>.json. Thus if you
have two main modules, server.js and client.js, in your current
NODE_APP_HOME, this folder will have files AgentIdentity_server.json
and AgentIdentity_client.json.
Note: If this folder is deleted or if the files in this folder are deleted or edited,
then, the application will take on a new agent identity on startup.
•
The logs folder contains one log file per main module. Log files will be named
in the format Agent_<main_module>.log . Thus, if you have two main
modules, server.js and client.js, in your current APP_HOME, this folder
will have files Agent_server.log and Agent_client.log.
3. Looking for successful Agent Start-up message in Agent_<main_module>.log
After a successful start-up, the following message should be found in the Agent
log file:
INFO Agent with agentId (hex) {Agent_ID} successfully
registered with the security service and retrieved its
managed entity Id {Me_ID}
4. Checking for Errors/Warnings in Agent log file
On starting the application for the first time after the deployment, the following
messages are expected in the log:
WARNING Unable to load json data from file <identity_file_name> : Error: ENOENT,
no such file or directory <identity_file_name>
WARNING Status 404 ,message: Not Found ,data received: Cannot recover the agent
as the, given agent cannot be found in ODS, requestDetails: hostname:...
5. Using the Application Performance Monitoring Web UI
Configuring Browser Injection with APM Node.js Agent
APM Node.js agent is integrated with static Javascript and you can configure the
browser injection to control the behavior.
Enabling Browser Injection
By default, browser injection is enabled in the APM Node.js Agent. To disable/enable
browser injection:
1.
Navigate to the folder APP_HOME\oracle-apm.
3-62 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note: The oracle-apm folder gets created only when the application to be
monitored has been started at least once with after Application Performance
Monitoring has been deployed.
2.
Run the following command:
To enable browser injection: oracle-apm config set
enableBrowserAgent true
To disable browser injection: oracle-apm config set
enableBrowserAgent false
Configuring Browser Injection
Configuring URLs
You can configure ApmClientCollector URL and the Javascript Download
URL to change the default settings.
By default, the APM Node.js Agent will pick the ApmClientCollector URL and the
static Javascript library URL from the registry that it has been configured against.
To configure the URLs:
1.
Navigate to the folder APP_HOME\oracle-apm.
2.
Run the following commands to configure the respective URLs:
oracle-apm config set jsLibraryUrl http://<ip address>:<port number>/
APMaaSCollector/external/collector/staticlib/apmeum.js
oracle-apm config set collectorUrl http://<ip address>:<port number>/
APMaaSCollector/external/collector
Injection Type
By default, the browser injection type is set to reference which means HTTP response
is instrumented by adding a reference to the Javascript.
Configuring Specific URLs for Oracle Management Cloud Services
You can configure specific URLs for Oracle Management Cloud services.
Installation or upgrade of the APM Node.js Agent adds some default URLs to the
Oracle Management Cloud services. If there are changes to the URLs due to changes in
network configuration, run these commands to set the specific URLs:
oracle-apm
suffix for
oracle-apm
suffix for
oracle-apm
suffix for
oracle-apm
suffix for
config set regManagerUrl http://<ip address>:<port number>/<static url Security Service>
config set dataStorageUrl http://<ip address>:<port number>/<static url Data storage service>
config set nextMessageUrl http://<ip address>:<port number>/<static url Message controller service>
config set acknowledgeUrl http://<ip address>:<port number>/<static url Message controller service>
Execute the above commands from node_modules/oracle-apm folder to make
the change globally in the installed agent. All the Node.js applications will receive the
changes on restart.
Execute the above commands from APP_HOME/oracle-apm folder to make the
change in a specific Node.js application.
Setting Up Oracle Management Cloud 3-63
Setting Up Application Performance Monitoring
Setting Up APM Ruby Agents
Complete these tasks sequentially to deploy the APM Ruby Agent.
•
Prerequisites for Deploying APM Ruby Agent
•
Preparing to Deploy APM Ruby Agent
•
Downloading the Master Installer for APM Ruby Agent
•
Installing and Provisioning APM Ruby Agent
Prerequisites for Deploying APM Ruby Agent
The section covers the key considerations and prerequisites for deploying APM Ruby
Agent.
Prerequisites
•
Supported versions of Ruby and Rails application server:
–
Ruby 2.3.0 and Rails 3.2
–
Ruby 2.3.0 and Rails 4.2
•
cURL with SSL support
•
UnZip software
•
Other considerations:
–
The machine hosting the Rails application server should be able to establish
an HTTPS connection (either over a proxy server or not) to Oracle
Management Cloud.
–
The install user of APM Ruby Agent should be the same as the Rails
application server user.
–
The Rails application server user should have read and write permissions to
the directories that host the APM Ruby Agent.
Preparing to Deploy APM Ruby Agent
Before you can download and install an APM Ruby Agent, ensure that you set the
staging directory in the target host running the Rails application server.
Setting the Staging Directory
Note:
If you are deploying the APM Ruby agent over a proxy server, then you need
to set the following environment variables through the command line where
you will execute AgentInstall.sh:
•
export http_proxy=http://www-hostname.abc.com:<port>/
•
export https_proxy=http://wwwhostname.example.com:<port>/
3-64 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
The staging directory, $STAGE_DIR is the path to a directory that is created by the
download script, where the software is downloaded, and executed from.
Note: The staging directory must not exist prior to running the
AgentInstall.sh downloader script. You should set the environment
variable to the staging directory, so that the variable is used by the installation
script to automatically create the directory during installation.
Set the environment variable to the staging directory:
•
If you're using a Bash shell:
export STAGE_DIR=/scratch/apm_staging
•
If you're using a C shell:
setenv STAGE_DIR "/scratch/apm_staging"
You can use any directory as a staging directory, but we recommend that you use a
directory similar to /scratch/apm_staging.
Setting the Registration Key
After creating or downloading a registration key, set the REG_KEY variable to the
registration key.
•
If you're using a Bash shell:
export REG_KEY=<Registration Key>
•
If you're using a C shell:
setenv REG_KEY "<Registration Key>"
Deploying the Gateway
Gateway is not a mandatory component while deploying Application Performance
Monitoring. Use the Gateway in the following scenarios:
•
If you have an application server that does not support Transport Layer Security
(TLS) protocol 1.2
•
If you have older versions of .NET IIS servers and Java Application Servers with
JDK less than 1.7 (for example, WebLogic 10.3.6)
Before deploying, review the information in Prerequisites for Deploying Oracle
Management Cloud Agents. For instructions on how to deploy the Gateway, see
Deploying the Gateway.
Setting the Gateway Variables
Set the values for Gateway host and port.
•
If you're using a Bash shell:
export GW_HOST=<Gateway Host Name>
export GW_PORT=<Gateway Port>
•
If you're using a C shell:
set GW_HOST "<Gateway Host Name>"
set GW_PORT "<Gateway Port>"
Setting Up Oracle Management Cloud 3-65
Setting Up Application Performance Monitoring
Downloading the Master Installer for APM Ruby Agent
Download the master installer to a temporary directory from where APM Ruby Agent
will be deployed.
To download the master installer:
1. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
2. Click Launch APM.
3. Review the information in this page to understand how to set up Application
Performance Monitoring by deploying the APM Ruby Agent in your data center.
4. Click Next to proceed.
5. To start downloading the installer to a local or shared directory in your data center,
click Download Master Installer.
The master installer is a ZIP file that contains the following:
•
AgentInstall.sh: The installation script used to deploy the APM Ruby
agent. You can see a list of supported parameters and their definitions in
Running the AgentInstall Script.
•
Read Me file: A file containing instructions about how to use the
AgentInstall.sh script to install agents on your target hosts.
6. Create a registration key that will be used during the time of installing a new agent.
Oracle Application Performance Monitoring Cloud Service verifies this key before
accepting any data sent by APM Ruby Agent deployed on your on-premises hosts.
For more information about creating a registration key, see Creating a Registration
Key.
7. Click Done after the download is complete.
Note: During the download, some browsers may change the name of the
installer. Ensure that you use the file that is currently downloaded for
installation. For example, if your directory already contained a file named
AgentInstall.zip, the browser might rename the newly downloaded file
to AgentInstall(1).zip. Ensure that you use the file
AgentInstall(1).zip.
8. Extract the contents of the master installer ZIP file.
9. From the local or shared directory where you have extracted the contents of the
master installer ZIP file, run the following command to download the software:
./AgentInstall.sh AGENT_TYPE=apm_ruby_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only
3-66 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
Note:
a.
If you’re deploying the APM Ruby Agent over a proxy server, ensure that
you perform the steps listed in Preparing to Deploy APM Ruby Agent,
and then run AgentInstall.sh.
b.
If you’re deploying the APM Ruby Agent to use Gateway, include the
following parameters before running AgentInstall.sh as below:
./AgentInstall.sh AGENT_TYPE=apm_ruby_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY} -download_only GATEWAY_HOST=${GW_HOST}
GATEWAY_PORT=${GW_PORT}
Your directory should contain the following files along with the other APM Ruby
Agent installation content:
a.
*agent_config.yml* which will be used while installing the APM Ruby
Agent.
b.
emcs.cer required in case the machine does not recognize the Oracle
certificate.
10. If the APM Ruby Agent needs to go through a proxy, edit the agent_config.yml
file providing these additional values as required:
•
proxy host
•
proxy port. By default, the value is 8080.
•
proxy user name - applicable if the proxy requires authentication
•
proxy password - applicable if the proxy requires authentication
If you need to download the master installer again at a later date, see Optional:
Downloading the Master Installer on Demand.
Installing and Provisioning APM Ruby Agent
After you have downloaded and extracted the installer, install and provision the APM
Ruby Agent on your Rails application server.
To install the APM Ruby Agent:
1. Navigate to your staging directory from where to provision the APM Ruby agent:
cd ${STAGE_DIR}
The stage directory contains the following:
•
Ruby agent gem file: oracle_apm-<Version>.gem
•
Configuration file: agent_config.yml
•
Certificate file: emcs.cer
•
Agent software version details: agent_software_build.xml
2. Enable the APM Ruby agent. This is a 4–step process:
Setting Up Oracle Management Cloud 3-67
Setting Up Application Performance Monitoring
a.
Install APM Ruby agent gem:
i.
If you are not already in the stage directory, navigate to the directory:
cd ${STAGE_DIR}
ii.
Install the APM Ruby agent gem:
gem install oracle_apm-<version>.gem
Example:
gem install oracle_apm-1.18.0.gem
Check after installation:
$ gem list | grep apm
oracle_apm (1.18.0)
b.
Plug in the APM Ruby Agent:
To have the APM Ruby agent monitor your Ruby on Rails application, add the
APM Ruby agent gem to the application Gemfile at the beginning of the list.
i.
Update the Gemfile of the application by adding gem 'oracle_apm'.
Here is an example:
$ head Gemfile
source 'https://rubygems.org'
gem 'oracle_apm'
# Bundle edge Rails instead: gem 'rails', github: 'rails/rails'
gem 'rails', '4.2.6'
# Use sqlite3 as the database for Active Record
gem 'sqlite3'
c.
Update the Configuration file:
i.
In your Rails application config directory, create a directory
named apm_agent.
ii.
Copy the file named agent_config.yml from STAGE_DIR in
the apm_agent configuration directory. This configuration file is parsed
as the agent starts up.
i.
Navigate to the config directory from your Ruby on Rails application.
$ cd config/
ii.
Create an apm_agent directory:
$ mkdir apm_agent
iii.
Copy the agent_config.yml file to apm_agent directory:
$ cp $STAGE_DIR/agent_config.yml ./apm_agent
iv.
Copy the Certificate File to apm_agent directory:
$ cp $STAGE_DIR/emcs.cer ./apm_agent
For example, the agent_config.yml contains the below details.
These details change according to the environment.
3-68 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
$ cat agent_config.yml
upload_root: https://<omc_host>:4443/
collector_root: http://<omc_host>:7777
omc_auth_token: Basic RU0wMV9FTUNTX0dMT0JBTF9JTlRFU...
registration_key: EQAAAAxidWbZ...
tenant: <tenant_name>
d.
Restart Ruby on Rails Application:
Once the Gemfile has been added and the configuration file is specified,
restart the Ruby on Rails application.
Verifying that the APM Ruby Agent is Monitoring the Application
You can verify if the deployment of the APM Ruby Agent is successful by examining
the logs and verifying that the user interface displays the application.
APM Ruby agent logs are located in the Rails application log directory, within the
apm_agent directory: <rails_app>/log/apm_agent.
As the Rails application starts up, the agent creates three log files:
•
agent.log
•
agent_startup.log
•
agent_status.log
The agent_startup.log contains startup logs and will eventually log the following
“Agent startup successfully completed”.
The agent_status.log file contains a summary of internal agent metrics showing
the amount of traffic monitored, number of observations sent, and number of
warnings or errors encountered among other data.
Setting up APM on Mobile Clients
You can deploy Application Performance Monitoring on mobile clients.
•
Deploying APM Mobile Agent on iOS
•
Deploying APM Mobile Agent on Android
Deploying APM Mobile Agent on iOS
You can deploy Application Performance Monitoring on a mobile device running on
iOS.
To deploy APM mobile agent on an iOS device:
1. Download the Master Installer. See Downloading the Master Installer.
2. Extract the contents of the Master Installer zip file.
3. Download the software.
a. From the local or shared directory where you extracted the contents of the
master installer, run the following command:
./AgentInstall.sh AGENT_TYPE=apm_ios_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY}
Setting Up Oracle Management Cloud 3-69
Setting Up Application Performance Monitoring
b. Navigate to the stage directory, and extract the contents of the folder
ApmAgent -<version> using Unzip. This folder contains
APMMobileAgent.framework.
4. Register iOS mobile client on Application Performance Monitoring:
a. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
b. Click Launch APM.
c. From the Administration menu, click Mobile Client Registrations.
d. Provide the registration details — name of the application, mobile client
platform (iOS), and the registration key. You can reuse the registration key
generated in the Agent Download page.
e. Click Register.
This generates an ID for the application, and this ID will be used in a later step.
5. Deploying iOS Mobile Agent: Add APMMobileAgent.framework.
a.
Drag and drop the APMMobileAgent.framework into Xcode Application
Project.
b.
Select Copy items if needed.
c.
In Add to targets, select the target iOS application.
d.
Select Finish.
6. Add APMMobileAgent.bundle.
a.
In the Project Navigator, select APMMobileAgent.framework. Right click
and select Show In Finder. The Finder displays the copied
APMMobileAgent.framework.
b.
Drag and drop the APMMobileAgent.bundle into your project.
c.
In Add to targets, select the target iOS application.
d.
Select Finish.
7. Add dependency.
a.
Navigate to Xcode’s project navigator.
b.
Select the application’s Xcode project.
c.
Select the target.
d.
Navigate to Build Phases.
e.
In the Link Binary with Libraries section, click +.
f.
Add libsqlite3.0.tbd.
8. Initialize APMMobileAgent.framework.
a.
Go to AppDelegate.m
3-70 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
b.
Add #import<APMMobileAgent/APMMobileAgent.h>
c.
Add [APMMobileAgent start] in (BOOL)application:
(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOption
9. Copy the certificate file.
a. Open the terminal and navigate to the STAGE_LOCATION folder and find
emaas.cer file.
b. Using the terminal, run openssl x509 -inform pem -in emaas.cer -
outform der -out emaasOut.cer.
c. Copy emaasOut.cer into APMMobileAgent.framework/
APMMobileAgent.bundle.
10. Update AgentStartup.properties properties file.
a. Navigate to APMMobileAgent.framework/APMMobileAgent.bundle.
b. Using an editor, add these values to the ApmMobileAgent.properties file:
•
oracle.apmaas.agent.collectorServiceUrl = http://
example.com:7777
•
oracle.apmaas.agent.tenant = sample_tenant
•
oracle.apmaas.agent.appId = ID generated when registering the
mobile client on APM. See step 4 above.
You can get the values for ApmClientCollector_URL and
Tenant_ID from the ApmMobileAgent.properties file located in
STAGE_LOCATION.
Note:
11. Build the Application.
a.
From the Product menu, click Clean.
b.
From the Product menu, click Build.
c.
From the Product menu, click Run.
Deploying APM Mobile Agent on Android
You can deploy Application Performance Monitoring on a mobile device running on
Android.
To deploy APM mobile agent on an Android device:
1. Download the Master Installer. See Downloading the Master Installer.
2. Extract the contents of the Master Installer zip file.
3. Download the software.
a. From the local or shared directory where you extracted the contents of the
master installer, run the following command:
Setting Up Oracle Management Cloud 3-71
Setting Up Application Performance Monitoring
./AgentInstall.sh AGENT_TYPE= apm_android_agent STAGE_LOCATION=${STAGE_DIR}
AGENT_REGISTRATION_KEY=${REG_KEY}
b. Navigate to the stage directory, and extract the contents of the folder
ApmAgent -<version> using Unzip.
4. Register Android mobile client on Application Performance Monitoring:
a. Sign in to My Services (http://cloud.oracle.com/sign_in), and go to the
Dashboard page.
b. Click Launch APM.
c. From the Administration menu, click Mobile Client Registrations.
d. Provide the registration details — name of the application, mobile client
platform (Android), and the registration key.
e. Click Register.
This generates an ID for the application, and this ID will be used in a later step.
5. Compile the Android application with the Mobile Agent.
a. Update the AndroidManifest.xml file with the below values.
b. Set the following permissions:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
c. In the application tag, add the following receiver and service:
<receiver
android:name="com.oracle.emaas.agent.android.runtime.receiver.APMReceiver"/>
<service
android:name="com.oracle.emaas.agent.android.runtime.service.APMService"/>
d. Update compile and run time jar files (jar files extracted from ApmAgent-
<version> agent zip file.
•
Copy apmandroidagentruntime.jar to app/libs.
•
Copy apmdxagent.jar in any temp location and update in path in
build.gradle file.
Example:
dependencies {
classpath files('../../../oracle/work/libs/apmdxagent.jar')
}
apply plugin: 'com.oracle.agentplugin'
Note: It is recommended that you add the apply plugin tag at the end of the
build.gradle file.
6. Create and update ApmMobileAgent.properties file.
a. In the application’s assets folder, create ApmMobileAgent.properties file.
b. Using an editor, add these values to the ApmMobileAgent.properties file:
3-72 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
•
ApmClientCollector_URL = http://example.com:7777
•
Tenant_ID = sample_tenant
•
MobileApp_ID = ID generated when registering the mobile client on APM.
See step 4 above.
You can get the values for ApmClientCollector_URL and
Tenant_ID from the ApmMobileAgent.properties file located in
STAGE_LOCATION.
Note:
7. Build the application.
a. From the Build menu, click Clean.
b. From the Build menu, click Build.
c. From the Run menu, click Run.
Setting up APM on Mobile Containers
You can deploy Application Performance Monitoring on containers.
You can monitor the performance on applications installed on containers, by
deploying Application Performance Monitoring on the containers. See Setting up APM
on Docker.
Setting up APM on Docker
You can deploy Application Performance Monitoring on Docker.
•
Setting up APM Java Agent on Docker
•
Setting up APM Node.js Agent on Docker
•
Setting up APM Ruby Agent on Docker
Setting up APM Java Agent on Docker
Reference topic:
•
Setting Up APM Java Agents
To install APM Java agent in a Docker container:
1.
Install the desired application server on the container.
2.
Provision APM Java Agent agent in the container similar to provisioning the
agent on any other host.
3.
Modify the startup script of your application server to include ApmAgent
startup property.
4.
From the apmagent/config/AgentStartup.properties file, manually
remove the line "oracle.apmaas.agent.hostname" .
5.
Build the image of the container.
Setting Up Oracle Management Cloud 3-73
Setting Up Application Performance Monitoring
6.
Within the container, run the application and Application Performance
Monitoring to monitor the performance of the application.
Setting up APM Node.js Agent on Docker
Reference topics:
•
Setting Up APM Node.js Agents
•
Installing and Provisioning APM Node.js Agent
To set up APM Node.js Agent within a Docker container, follow these additional steps
apart from the ones listed in Setting Up APM Node.js Agents.
1.
After you have downloaded the master installer and extracted it, copy the APM
Node.js Agent installer bits into your Docker container.
2.
Run the provisioning script to install the agent in the container. See Installing and
Provisioning APM Node.js Agent.
3.
Copy the application files into the container. This is the application that will be
monitored by Application Performance Monitoring.
4.
Expose the required ports and start your Node.js application.
5.
Build the image of the container.
Here’s an example of a docker file ready to install APM Node.js Agent:
COPY ./<Stage_DIR>/usr/src/provision
ENV NODE_PATH /usr/local/lib/node_modules
RUN /bin/bash ProvisionApmNodeAgent.sh -h <host>
COPY ./<your application>/usr/src/<application folder>
WORKDIR /usr/src/<application folder>
EXPOSE 3000
RUN npm -g list --depth=0
CMD [ "npm", "start" ]
6.
Spawn a new docker container:
sudo docker run -h <host> -p <port>:3000 -d node-web-app
Note: The parameter -h is essential for the hostname validation to succeed
during provisioning the agent. This is required if your container is not able to
resolve the /etc/hosts file.
Verifying the Installation
To verify the installation of the APM Node.js Agent in your container:
1.
View the list of containers running on the host and get the ID of your container
using this command:
sudo docker ps
3-74 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
2.
Login to the container using this command:
sudo docker exec -it <container id> /bin/bash
3.
Navigate to the oracle-apm folder of your application. Check the folder
containing the container id to locate the Agent’s configuration and log folders.
Verify the log contents are similar to the agent deployed on any other normal
host.
Setting up APM Ruby Agent on Docker
Reference topic:
•
Setting Up APM Ruby Agents
Setting up APM Ruby Agent on a Docker container is no different from setting up the
agent on any host. Follow the instructions in Setting Up APM Ruby Agents.
Verifying the Installation
To verify the installation of the APM Ruby Agent in your container:
1.
Check the agent_startup.log file to see if the APM Ruby agent is running
within the container:
INFO <CONFIG> OS Container information: type=docker, identity=<long identity of
the container>
2.
In the startup.log, the Host discovery type has two new fields —
osContainerType and osContainerId.
Example
25c4188 <2016-04-12T12:26:13:468> INFO <STARTUP> #<OracleAPM::HostInfo:
0x0000000411f428 @hostName="myvm.jc", @osName="linux-gnu", @osVersion="",
@architecture="x86_64-linux", @processorCount=4, @osContainerType="docker",
@osContainerId="<long identity of the container>", @agentIdKey="<agent id>=",
@agentVerKey="<agent version key>", @idKey="<identity key>", @verKey="<version
key>>
Troubleshooting the Deployment of Application Performance Monitoring
If you run into problems while deploying Application Performance Monitoring, here
are some workarounds.
OSGi (Open Services Gateway initiative) property setting
If the application you would like to monitor has a dependency on OSGi, make these
manual settings to ensure proper framework boot delegation so that the application
that is being monitored does not break.
•
WebLogic Server: On your WebLogic Server, ensure the monitored OSGi
framework instances have the Java system property, oracle.apmaas.* added
to the Framework Boot delegation property as follows:
-Dorg.osgi.framework.bootdelegation=oracle.apmaas.*
Refer to the WebLogic documentation on ways to change the WebLogic OSGi
settings.
•
Atlassian JIRA Felix OSGi container (Tomcat): Add the following option to the
JIRA container's startup options:
Setting Up Oracle Management Cloud 3-75
Setting Up Application Performance Monitoring
Datlassian.org.osgi.framework.bootdelegation=oracle.apmaas.*,sun.*,org.apache.xer
ces,org.apache.xerces.*,org.apache.naming,org.apache.naming.*,org.apache.catalina
,org.apache.catalina.*
Logs not created
If APM Agent logs are not created even when the application is running, check if the javaagent option for ApmAgentInstrumentation.jar was added correctly to
the server startup command.
Certificate log errors while deploying APM Node.js Agent
If you see a warning message in the logs with the following content, then delete the
file emcs.cer from NODE_PATH/oracle_apm/data/.
Warning:
Failed to call hostname: <registry_server>, port: <path>l, path: /registry/instances?
status=UP&serviceName=SecurityService&version=1.0%2B, method: GET, header: X-USERIDENTITY-DOMAIN-NAME=<tenant_id>, header: Content-Type=application/json ,failure
message: certificate not trusted
Application to be monitored by APM Node.js Agent is within proxy
If you are installing and provisioning the APM Node.js Agent in environments that
require the use of proxy servers, use these additional options in oracle-apmconfig.json. Contact your network administrator for these values.
1.
Using a text editor, open NODE_APP_HOME/oracle-apm/config/oracleapm-config.json.
2.
Add the following properties at the end of existing properties in the file:
Option
Description
proxyHost
The proxy server’s host name.
proxyPort
The proxy server’s port.
proxyAuth
This is the authorization token that the
agent will use if the proxy server requires
authentication. Provide the value in clear
text. This is an optional parameter that will
be passed literally as the proxy
authorization header to the proxy server.
Here is an example of the properties added to the end of oracle-apmconfig.json:
{
"tenant": "tenantid",
"registrationKey": "REGKEY==",
"registryServiceUrl": "https://host:port/registry",
"auth": "AUTH==",
"MCAccessRateSeconds": 60,
"MEIDCheckRateSeconds": 60,
"proxyHost":"hostname",
"proxyPort":90,
3-76 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
"proxyAuth":"username:password"
}
APM Java Agent reports 'Remote certificate is not trusted’
When installing the APM Java Agent, if the agent reports that the remote certificate is
not trusted, create and add a remote certificate.
The remote certificate is the certificate presented to the agent, usually by Oracle
Management Cloud, during the agent's attempt to establish an SSL connection.
However, if the agent traffic goes through an intermediary, then, it is the certificate of
the intermediary (for example, proxy) that might run into this error.
The certificate is included in the agent log information, and can be used to create
a .cer file.
If the Java Agent's logs contain the SEVERE message Remote certificate is not trusted,
AND if the Java agent's traffic goes through a proxy which presents a certificate not
signed by a well-known certification authority, then, add the proxy's certificate(s) to
the agent's trust list:
1.
Edit your AgentStartup.properties file.
2.
In the pathToCertificates property, add the full path to your proxy
certificate .cer file.
3.
Save the file.
4.
Restart your application server.
If you don't have the proxy certificate handy, you could also copy it from the agent's
log:
1.
From the agent’s log file, copy the block of lines starting with the line
-----BEGIN REMOTE CERTIFICATE-----
and ending with the line
-----END REMOTE CERTIFICATE----2.
Delete the word REMOTE (along with the trailing space) from both the BEGIN line
and the END line.
3.
Delete lines 2-6 (the information that describes the certificate).
4.
Save the file as a .cer file.
The contents of the .cer file will look like this:
-----BEGIN CERTIFICATE----certificate base64 content
-----END CERTIFICATE-----
Security Access errors while starting APM Java Agent
If you run the APM Java Agent with a Java security manager and see an error message
with the following content:
java.security.AccessControlException: access denied()
or
Setting Up Oracle Management Cloud 3-77
Setting Up Application Performance Monitoring
access denied()
add the following block to the Java security policy file:
grant codeBase "file:<path_to>/apmagent/-" { permission
java.security.AllPermission; };
Exception Errors while using ATG Commerce
If you are using Application Performance Monitoring to monitor the ATG Commerce
application, using browser injection might throw exception errors.
To resolve this, open the properties file, apmagent/config/
AgentStartup.properties, and add the following property:
oracle.apmaas.agent.browser.copyBuffer=true
Transferring Data through Reverse Proxy
You can use the reverse proxy technique to send data in restricted environment so that
it can be processed by Application Performance Monitoring.
The reverse proxy technique allows browsers to find a way through the customer
firewall that is open for access only to the Oracle Collector. The browser will find the
reverse proxy and interact with it like the Oracle cloud end point. You can configure
reverse proxy by following these steps:
•
Configure APM Agent to use a different collectorUrl
•
Configuring a Reverse Proxy
Configure APM Agent to use a different collectorUrl
The APM Agent should override the end point it receives from Oracle cloud with the
local end point of the reverse proxy. This can be done by configuring the property for
collectorUrl in AgentStartup.properties file. This setting will override the
default value that is retrieved from Oracle cloud through service registry. When there
are no https sites that require monitoring, set the collectorUrl to http instead of
https.
Here is an example of the setting:
oracle.apmaas.agent.collectorUrl=https://myproxy.example.com:4443/APMaaSCollector/
external/collector
In the example above, replace myproxy.example.com and the port number 4443
with the hostname and the port number of the machine where the reverse proxy is
installed. Once the collectorUrl is updated, bounce the application server(s).
Configuring a Reverse Proxy
You can configure a reverse proxy using any reverse proxy configuration tools like
NGINX, Squid or WebLogic ProxyPlugin.
Note: If you have an Oracle HTTP Server setup, skip steps 1-6. If you are
using a trusted certificate, skip step 7.
1.
Navigate to http://www.oracle.com/technetwork/middleware/webtier/
downloads/index.html
3-78 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
2.
Accept the license agreement.
3.
Scroll to Oracle WebTier 12cR2 and Oracle HTTP Server 12.2.1.1.
4.
Select Linux-64 bit and download the installer.
5.
Follow the documentation to install Oracle HTTP Server at https://
docs.oracle.com/middleware/1213/index.html.
Note:
6.
The above document assumes that OHS is installed at /Oracle.
Start the nodemanager.
# export DOMAIN_HOME=<WLS Domain home>
# cd $DOMAIN_HOME/bin
# nohup ./startNodeManager.sh > nm.out&
Example:
# export DOMAIN_HOME="/Oracle/Middleware/Oracle_Home/user_projects/domains/
base_domain"
# cd $DOMAIN_HOME/bin
# nohup ./startNodeManager.sh > nm.out&
7.
Add the HTTP Server certificate to wallet.
a.
Prepare the wallet:
# export DOMAIN_HOME=<WLS Domain home>
# cd $DOMAIN_HOME/config/fmwconfig/components/OHS/instances/ohs1/keystores
# mkdir proxy
# $DOMAIN_HOME/../../../oracle_common/bin/orapki wallet create -wallet . auto_login_only
Example:
# export DOMAIN_HOME=/Oracle/Middleware/Oracle_Home/user_projects/domains/
base_domain
# cd $DOMAIN_HOME/config/fmwconfig/components/OHS/instances/ohs1/keystores
# mkdir proxy
# $DOMAIN_HOME/../../../oracle_common/bin/orapki wallet create -wallet . auto_login_only
b.
Get the Certificates and add to the wallet:
Method 1:
# echo -n | openssl s_client -connect <OMC collector URL>:<port> | sed -ne
'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/proxy_certificate.cert
Method 2:
i.
Install (or update) the CA certificates:
# yum update ca-certificates
ii.
Split the bundle CA root file containing all certificates into separate files.
(orapki cannot handle a bundle.)
# awk 'BEGIN {c=0;} /BEGIN CERT/{c++} { print > "cert." c ".pem"}'
< /etc/pki/tls/certs/ca-bundle.crt
Setting Up Oracle Management Cloud 3-79
Setting Up Application Performance Monitoring
iii.
Load the individual certificates into the OHS proxy wallet.
# for i in `ls cert.*.pem`; do / Oracle/Middleware/Oracle_Home/
oracle_common/bin/orapki wallet add -wallet . -cert $i -trusted_cert auto_login_only; done
8.
Get the APM collectorUrl from Oracle cloud.
# wget -q -O - <application url> | grep -Po
"baseCollectorUrl=(.*?)APMaaSCollector" | sed -e "s/'//"
9.
Configure HTTPS reverse proxy with Oracle HTTP Server.
a.
In an editor, open the ssl.conf file located in the folder ohs1.
# export DOMAIN_HOME=<WLS Domain home>
DOMAIN_HOME/config/fmwconfig/components/OHS/instances/ohs1
Example:
# export DOMAIN_HOME="/Oracle/Middleware/Oracle_Home/user_projects/domains/
base_domain"
# vi $DOMAIN_HOME/config/fmwconfig/components/OHS/instances/ohs1/ssl.conf
b.
Configure the SSL reverse proxy in an existing virtualhost definition section.
Example:
...
<VirtualHost *:4443>
<IfModule ossl_module>
# SSL Engine Switch:
# Enable/Disable SSL for this virtual host.
SSLEngine on
SSLProxyEngine on
SSLProxyWallet "${ORACLE_INSTANCE}/config/fmwconfig/components/$
{COMPONENT_TYPE}/instances/${COMPONENT_NAME}/keystores/proxy"
SSLProxyVerify none
ProxyPass "/APMaaSCollector" "https://cloud_APM_Collector/
APMaaSCollector"
ProxyPassReverse "/APMaaSCollector" "https://cloud_APM_Collector/
APMaaSCollector"
ProxyPreserveHost On
ProxyRequests off
...
</VirtualHost>
...
c.
Replace the URL https://cloud_APM_Collector/APMaaSCollector
with the actual collector URL on Oracle cloud from step 8.
Note: To use HTTP communication between browser and Reverse Proxy,
comment out the SSLEngine on line.
d.
Start ohs1 component.
# export DOMAIN_HOME=<WLS Domain home>
# cd DOMAIN_HOME/bin
# ./startComponent.sh ohs1
Example:
3-80 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Setting Up Application Performance Monitoring
# export DOMAIN_HOME=/Oracle/Middleware/Oracle_Home/user_projects/domains/
base_domain
# cd DOMAIN_HOME/bin
# ./startComponent.sh ohs1
Setting Up Oracle Management Cloud 3-81
Setting Up Application Performance Monitoring
3-82 Deploying and Managing Oracle Management Cloud Agents
4
Upgrading and Deleting the Oracle
Management Cloud Agents
After deploying Oracle Management Cloud agents on your target hosts, you can
perform routine administration tasks, such as viewing, monitoring, and managing the
Oracle Management Cloud agents using the Oracle Management Cloud Agents page.
To access the Oracle Management Cloud Agents page, click the navigator icon of your
Oracle Management Cloud service, and then click Agents under Administration.
Monitoring activities include viewing and verifying the:
•
Name of the components
•
Version of the cloud agent
•
Target host name
•
Installation date
•
Registration keys associated with gateways, data collectors, cloud agents, and
APM Java Agents
•
Connected data collectors and cloud agents for a gateway
•
Last check-in time of the Oracle Management Cloud agents
•
Value, current usage, and the maximum registration limit of registration keys
Routine administration tasks include:
•
Upgrading or removing:
–
Gateways
–
Data Collectors
–
Cloud agents
–
APM Java Agents
•
Downloading, revoking, or creating registration keys
•
Downloading the master installer
Topics:
•
Roadmap for Routine Administration Tasks
•
About Upgrading Oracle Management Cloud Agents
•
Upgrading Oracle Management Cloud Agents
Upgrading and Deleting the Oracle Management Cloud Agents 4-1
Roadmap for Routine Administration Tasks
•
Removing Data Collectors
•
Removing Cloud Agents and Gateways
•
Managing Registration Keys
•
Managing APM Agents
•
Optional: Downloading the Master Installer on Demand
Roadmap for Routine Administration Tasks
This section is a roadmap of the routine administration tasks that you can perform as
the administrator of your Oracle Management Cloud service.
Task
More Information
Upgrade Oracle Management Cloud agents
whenever Oracle releases an updated version
of the agent software.
About Upgrading Oracle Management Cloud
Agents.
Create and manage registration keys to use
with Oracle Management Cloud agents when
necessary.
Managing Registration Keys.
Remove Oracle Management Cloud agents
deployed on target hosts when necessary.
•
•
•
Removing APM Java Agents
Removing Data Collectors
Removing Cloud Agents and Gateways
About Upgrading Oracle Management Cloud Agents
Oracle releases updates of the agent software at periodic intervals. You should
correspondingly upgrade your Oracle Management Cloud agents whenever it is
feasible to do so.
Upgrading Oracle Management Cloud agents is a seamless process without any data
loss. The data feed generated during the upgrade process is stored in the agent state
directory. Once the agent comes back online, the data files get uploaded to Oracle
Management Cloud. We recommend that you check the Oracle Management Cloud
Agents page and verify that you have deployed the latest version of agent software.
To check if there is a newer version of the agent available, click on corresponding
agents page.
On the Oracle Management Cloud Agents page, you’ll see a list of gateways, data
collectors, cloud agents, and APM Java Agents that you’ve deployed. Click a specific
Oracle Management Cloud agent to view the following information:
•
Name and host name
•
Version
•
Time since last check in
•
Installation date
•
Last check-in time
•
Connected agents
•
An upgrade notification message
4-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
About Upgrading Oracle Management Cloud Agents
•
Registration key associated with the cloud agent
At the time of upgrading the agents, ensure that you upgrade a gateway before you
upgrade the associated data collector or cloud agents that are communicating through
it. Oracle Management Cloud supports the backward compatibility of Oracle
Management Cloud agents. For example, you can have a newer version of a gateway
with older versions of the associated Oracle Management Cloud agents or you can
have a older version of a gateway with newer versions of the associated Oracle
Management Cloud agents. After deploying this gateway go to the OMC agent page
to check if a new update available for this gateway and then choose to upgrade now or
later.
After you install or upgrade your Oracle Management Cloud agents, it is required to
run root.sh as a root user. Running root.sh as a root user adds entries in
the /etc/init.d file to restart the agent automatically in case of server reboot. If you
don’t wish to run root.sh post install or upgrade, it will not hamper any
functionality, and the script and can also be run later.
You can find the agent upgrade logs at the following location:
$AGENT_HOME/logs/AgentUpgrade_*.log
Upgrade Use Cases
Example 4-1
Use Case 1
I am an existing Oracle Management Cloud customer having an existing onpremises Oracle Enterprise Manager Cloud Control. I want to upgrade to the latest
version of Oracle Management Cloud, but I don’t need the existing gateway or the
data collector.
You can deinstall the gateway and data collector, and you can install the updated
cloud agent. However, in that case, you won’t be able to harvest data from your
existing on-premises Oracle Enterprise Manager Cloud Control.
Example 4-2
Use Case 2
I am an existing Oracle Management Cloud customer having an existing onpremises Oracle Enterprise Manager Cloud Control. I have a gateway, a data
collector, and cloud agents installed in my setup. I want to upgrade to the latest
version of Oracle Management Cloud, and I want to remove the gateway, because it
is an optional agent in the latest version of Oracle Management Cloud. How do I
deinstall the gateway ensuring minimal data loss?
Do the following:
1.
Stop the data collector, cloud agents, and gateway using omcli on the host that is
running the agents.
/<agent_install_directory>/bin/omcli stop agent
2.
Check the status of the agents using omcli.
/<agent_install_directory>/bin/omcli status agent
Run this command multiple times till the value of Pending Files displays 0 in
the output.
3.
Start the agents using omcli.
/<agent_install_directory>/bin/omcli start agent
Upgrading and Deleting the Oracle Management Cloud Agents 4-3
Upgrading Oracle Management Cloud Agents
4.
Go to Oracle Management Cloud Agents page in the Oracle Management Cloud
console and remove the gateway.
5.
Upgrade the data collector.
6.
Upgrade the cloud agents.
Upgrading Oracle Management Cloud Agents
This section describes the procedure to upgrade the gateway, data collector, and the
cloud agent. You can upgrade all the cloud agents installed in an identity domain /
tenant or upgrade a single agent.
Upgrading All Oracle Management Cloud Agents
To upgrade all cloud agents, follow these steps:
1.
Click the navigator icon on the navigation bar, and then click Agents.
2.
On the Oracle Management Cloud Agents page, click <Gateways / Data
Collectors / Cloud Agents> on the left navigation pane to select the OMC agents
to be upgraded.
3.
On the selected OMC agents page, click Upgrade All. The Upgrade All button is
automatically enabled if an upgrade is available for all gateways installed in the
identity domain/tenant.
4.
Check the Version column that displays a notification message indicating that the
OMC agents are up to date.
All the cloud agents are upgraded.
Before Upgrading Data Collectors
The default roles and privilege given to data collector user during install may be
altered or revoked due to in-house security policies. If this is the case, run the
following script at regular intervals to confirm that all necessary and sufficient roles
and privileges are still intact:
1.
You can click this link to download the script or navigate to the Data Collector
Home: $HARVESTER_ORACLE_HOME/sysman/admin/scripts/emaas/
harvester/script/check_privs.sql and download the script. The script
must be downloaded to a host from which you can connect to the Oracle
Management Repository database.
2.
Connect to the Oracle Management Repository database as the Data Collector
install user as follows:
./sqlplus HARVESTER_USERNAME@<OMR_CONNECT_STRING>
3.
Run the script.
Upgrading a Single Oracle Management Cloud Agent
To upgrade a single cloud agent, follow these steps:
1.
On the Oracle Management Cloud Agents page, from the list of OMC agents,
identify the OMC agent that needs to be upgraded. Use the Search feature to find
the specific OMC agent.
4-4 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Removing Data Collectors
2.
Click the OMC agent to view additional information in the expanded view. The
Version column displays a notification when an upgrade for the OMC agent is
available.
3.
To upgrade the agent, click the Actions menu on the right side of the page and
select Upgrade.
4.
Check the Version column that displays a notification message indicating that the
cloud agent is up to date.
The cloud agent is upgraded
Removing Data Collectors
You can remove data collectors installed on a host using the Oracle Management
Cloud Agents page.
When you remove a data collector, information about targets, target properties,
metrics, performance metrics, and events are no longer collected.
To remove data collectors:
1. Log on to the host that is running the data collector.
2. Navigate to the agent’s Oracle Home directory, and run the following command to
de-install the data collector:
$AGENT_HOME/sysman/install/AgentInstall.sh -deinstall SYS_USERNAME=<username>
SYS_USER_PASSWORD=<password>
Note:
You don’t need to perform any action on the Oracle Management Cloud
Agents page. The preceding command will deregister and remove the data
collector.
The data collector is removed.
If the host on which you’ve deployed the data collector gets decommissioned, then:
1.
Open the Oracle Management Cloud Home page.
2.
Click the navigator icon on the navigation bar, and then click Agents.
3.
In the Oracle Management Cloud Agents page, click Data Collectors on the left
navigation pane.
4.
In the Data Collectors page, select the data collector whose host has been
decommissioned.
5.
On the right side of the page, click the Actions menu and select Remove.
The data collector is removed from the Oracle Management Cloud Agents page.
Note: If the data collector installation is incomplete or if you want to clean up
the left over schema, follow the instructions provided in the Remove Incomplete
Data Collector Installation or Cleanup section in Troubleshooting.
Upgrading and Deleting the Oracle Management Cloud Agents 4-5
Removing Cloud Agents and Gateways
Removing Cloud Agents and Gateways
You can remove cloud agents and gateways using the Oracle Management Cloud
Agents page.
When you remove a cloud agent associated with a target host, the cloud agent is
unregistered from Oracle Management Cloud and is then deleted.
You may need to remove a cloud agent from your target host if:
•
A cloud agent deployed on the target host is no longer necessary.
•
You no longer need to collect performance metrics, resource data, or logs for a
specific target host.
•
You've modified your deployment topology.
To remove a cloud agent or a gateway:
1. On the Oracle Management Cloud Agents page, click Cloud Agents / Gateways on
the left navigation pane.
2. On the Cloud Agents / Gateways page, select a cloud agent or a gateway that
needs to be removed. Use the Search feature to find a specific cloud agent or
gateway.
Before removing a gateway, ensure that all data collectors and cloud agents
associated with the gateway have also been removed
3. On the right side of the page, click the Actions menu, and select Remove.
The selected cloud agent or gateway is removed.
Note: This method of removing cloud agents removes the cloud agent from
Oracle Management Cloud.
Managing Registration Keys
Managing your registration keys involves creating, downloading and revoking the
keys.
Topics:
•
Creating a Registration Key
•
Downloading a Registration Key
•
Revoking a Registration Key
About Creating Registration Keys
A registration key is issued against your Identity Domain, and it is used at the time of
deploying cloud agents.
You can create a new registration key and use that key for installing a new agent by
specifying the AGENT_REGISTRATION_KEY=<NewKeyValue> parameter to the agent
installer script. See Setting Up Oracle Management Cloud for more information on
running the agent installer script.
4-6 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Managing Registration Keys
A registration key can exist in three states:
•
VALID: The registration key is valid, and it can be used to run the install script.
•
EXPIRED: The registration key’s usage count is greater or equal to the maximum
usage specified at the time of creating the key.
•
DISABLED: The registration key is explicitly set to be in the disabled state by
calling a Cloud Service REST API.
Creating a Registration Key
This section provides information about creating a registration key.
To create a new registration key:
1. On the Oracle Management Cloud home page, click the navigator icon on the
navigation bar, and then click Agents.
2. On the Oracle Management Cloud Agents page, click Registration Keys on the left
navigation pane.
The Registration Keys page displays a list of all registration keys.
3. Enter the required details in the Registration Keys page:
a. In the Name field, specify a name to identify the registration key.
b. In the Registration Limit field, enter a number which indicates the maximum
number of agents, data collectors, and gateways that can be associated with the
registration key.
c. Click Create New Key.
A new registration key is created.
Downloading a Registration Key
This section provides information about downloading a registration key.
You can download a registration key from the Oracle Management Cloud Agents
page.
1. In the Oracle Management Cloud Agents page, click Registration Keys on the left
navigation pane.
The Registration Keys page displays a list of all registration keys.
2. From the list of registration keys, select the key that you want to download.
3. On the right side of the page, click the actions menu and select Download.
A text file registrationKey.txt containing the value of the registration key is
downloaded to your local drive.
4. To view the key value, open the registrationKey.txt file.
The registration key is downloaded.
Upgrading and Deleting the Oracle Management Cloud Agents 4-7
Managing APM Agents
Revoking a Registration Key
This section provides information about revoking a registration key.
You can revoke a registration key when necessary.
To revoke a key:
1. In the Oracle Management Cloud Agents page, click Registration Keys on the left
navigation pane.
The Registration Keys page displays a list of all registration keys.
2. From the list of registration keys, click the registration key that you want to revoke.
3. On the right side of the page, click the actions menu and select Revoke.
The registration key is revoked.
Managing APM Agents
A user with Application Performance Monitoring administrator role can remove APM
Agents or update to the latest version of the agent.
Topics:
•
Upgrading APM Java Agents
•
Removing APM Java Agents
•
Removing APM .Net Agent
•
Upgrading APM Node.js Agents
•
Removing APM Node.js Agents
Upgrading APM Java Agents
This section discusses how you can upgrade APM Java Agents.
Prerequisite:
Stop the server where the APM Java Agent to be upgraded is installed.
To upgrade APM Java Agents:
1. Download the latest master installer, AgentInstall.zip.
2. Extract the contents of the ZIP file to a local or shared directory.
3. Download the agent install software.
For information on the above steps 1 to 3, see Downloading the Master Installer for
APM Java Agent.
4. Optionally backup the existing APM Java Agent.
5. Install and provision the APM Java agent for your administration server. Provision
the new APM Java Agent to the same destination. Ensure you are logged in as the
same user that installed the initial APM Java Agent.
4-8 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Managing APM Agents
You will be prompted to Overwrite, or Upgrade existing APM Java Agent.
a.
Overwrite - New APM Java Agent will be installed over the existing one.
b.
Upgrade - The APM Java Agent is upgraded to new version, and all
customized properties are retained. Both lib and config directories in
apmagent are backed up to lib.backup and config.backup respectively.
Removing APM Java Agents
This section provides information about disabling and removing APM Java Agents.
To disable and remove APM Java Agents from a WebLogic domain, complete the
following tasks:
•
Task 1: Disable the APM Java Agent in the WebLogic Server Domain
•
Task 2: Delete the APM Java Agent Software from the WebLogic Server Domain
•
Task 3: Remove APM Java Agent References from Oracle Management Cloud
Task 1: Disable the APM Java Agent in the WebLogic Server Domain
1. Stop the WebLogic Server:
% cd $DOMAIN_HOME/bin
% ./stopWebLogic.sh
2. Remove the edited version of the startWebLogic.sh script, and replace it with
the original script that was backed up before you installed the APM Java Agent:
% mv startWebLogic.sh.orig startWebLogic.sh
3. Restart the WebLogic Server:
% cd $DOMAIN_HOME
% nohup ./startWebLogic.sh >& startup.log &
Note:
Note that in the above script you are using the $DOMAIN_HOME version of
startWebLogic.sh, even though you had earlier edited the
$DOMAIN_HOME/bin version. Invoking this script from one level higher will
in fact invoke the script from a lower level.
Task 2: Delete the APM Java Agent Software from the WebLogic Server Domain
1. Remove the directory where the APM Java Agent files were extracted:
% cd $DOMAIN_HOME
% rm -r apmagent
2. Remove the directory where you initially extracted the APM Java Agent
installation software. For example:
% cd $DOMAIN_HOME
% rm -r apm_agent
Upgrading and Deleting the Oracle Management Cloud Agents 4-9
Managing APM Agents
Task 3: Remove APM Java Agent References from Oracle Management Cloud
1. On the Oracle Management Cloud Agents page, click APM Agents on the left
navigation pane.
2. On the APM Agents page, select the APM Java Agent that you want to remove.
Use the Search feature to search for a specific APM Java Agent.
3. On the right side of the page, click the Actions menu and select Remove.
Removing APM .Net Agent
This section provides information about disabling and removing APM .Net Agents.
A administrator can remove APM .Net Agents by completing the following tasks:
•
Task 1: Remove APM .Net Agent
•
Task 2: Remove APM .NET Agent References from Oracle Management Cloud
Task 1: Remove APM .Net Agent
1. You can remove APM .Net Agent in any of the following ways:
•
Navigate to the installation directory and run the following command:
msiexec /x ApmAgent.msi
OR
•
Navigate to the Control Panel and remove Oracle APM .NET Agent.
Task 2: Remove APM .NET Agent References from Oracle Management Cloud
1. On the Oracle Management Cloud Agents page, click APM Agents on the left
navigation pane.
2. On the APM Agents page, select the APM .Net Agent that you want to remove.
Use the Search feature to search for a specific APM .Net Agent.
3. On the right side of the page, click the Actions menu and select Remove.
Upgrading APM Node.js Agents
This section discusses how you can upgrade APM Node.js Agents.
Prerequisites
•
Ensure that the environment variables are set appropriately as listed in Preparing
to Deploy APM Node.js Agent.
•
Ensure that none of the files in the node_modules/oracle-apm folder are open.
•
Stop the server where the APM Node.js Agent to be upgraded is installed.
•
Ensure you are logged in as the same user that installed the initial APM Node.js
Agent.
To upgrade APM Node.js Agents:
4-10 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Managing APM Agents
1. Download the latest master installer, AgentInstall.zip.
2. Extract the contents of the ZIP file to a local or shared directory.
3. Download the agent install software.
For information on the above steps 1 to 3, see Downloading the Master Installer for
APM Node.js Agent.
4. Optionally, backup the existing APM Node.js Agent.
5. Install and provision the APM Node.js agent by running the provisioning script.
For instructions on installation, see Installing and Provisioning APM Node.js
Agent.
APM Node.js agent displays the list of changes made by the upgrade process, and
prompts for confirmation. On confirmation, the APM Node.js Agent is upgraded to
the new version, and all customized properties are retained. The oracle-apm
directory and the oracle-apm-config.json file in apmagent are backed up to
${STAGE_DIR}/temp.
Note:
Review the hostName property, since this value will overwrite the hostName
which was used by the agent prior to upgrade.
The upgrade computes a default hostname and uses the same. To override
this default, rerun the provisioning script with ORACLE_HOSTNAME argument.
The following changes occur when you choose to upgrade APM Node.js Agent:
1.
A new version of APM Node.js Agent software will be installed in the nodemodules folder.
2.
Updated oracle-apm-config.json will be copied over from STAGE_DIR to
node-modules/oracle-apm/data folder. Existing file will be backed up with
a .backup extension. Custom properties edited previously like proxy params
etc will be copied over to the new file.
3.
All .cer certificate files will be converted into the correct format and copied over
to node-modules/oracle-apm/data folder.
4.
Start the Node.js applications. The required config files will be copied to the
respective NODE_APP_HOME/oracle-apm/data folder.
Troubleshooting Upgrade Issues
The upgrade overwrites oracle-apm agent files in the %NODE_PATH% folder. If any
file from this folder (for example, oracle-apm-config.json file) is open during
the upgrade, the following npm error occurs, and the upgrade process stops.
npm ERR! code EPERM
npm ERR! errno -4048
npm ERR! syscall rename
npm ERR! Error: EPERM: operation not permitted, rename '%NODE_PATH%\oracle-apm' ->
'%NODE_PATH%\.oracle-apm.DELETE'
Upgrading and Deleting the Oracle Management Cloud Agents 4-11
Managing APM Agents
With the above error, the oracle-apm folder is deleted and hence, a rerun of the
script is treated as a new install. Any locally modified properties are lost due to the
rerun.
Workaround
Follow this workaround before attempting a rerun of the provisioning script:
1.
The backup copy of the old oracle-apm folder is available in the backup folder ${STAGE_DIR}/temp (on Linux) and %TEMP% folder (on Windows). Copy this
folder into node_modules.
2.
Ensure that none of the files from the node_modules/oracle-apm folder are
open, and rerun the provisioning script.
Removing APM Node.js Agents
This section provides information about disabling and removing APM Node.jsAgents.
To disable and remove APM Node.js Agents, complete the following tasks:
•
Task 1: Remove the APM Node.js Agent from the application
•
Task 2: Delete APM Node.js files from the Application folder
•
Task 3: Uninstall APM Node.js Agent
Task 1: Remove the APM Node.js Agent from the application
1. Navigate to the NODE_APP_HOME folder.
2. Open the .js file that serves as the application’s entry point.
3. In the .js file, search for the line that starts with require('oracle-apm'); and
delete it.
Code with Node.js Agent enabled:
require('oracle-apm'); //Newly added require for Oracle APM instrumentation
var express = require('express');
var app = express();
app.get('/', function (req, res) {
res.send('Hello World!');
});
app.listen(3000, function () {
console.log('Example app listening on port 3000!');
});
Code after removing APM Node.js Agent
var express = require('express');
var app = express();
app.get('/', function (req, res) {
res.send('Hello World!');
});
app.listen(3000, function () {
4-12 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Optional: Downloading the Master Installer on Demand
console.log('Example app listening on port 3000!');
});
Task 2: Delete APM Node.js files from the Application folder
1. Navigate to the NODE_APP_HOME folder.
2. Remove the directory oracle-apm where APM Node.js agent was installed
cd $NODE_APP_HOME
rm -r oracle-apm
Task 3: Uninstall APM Node.js Agent
1. Set the environment variable PATH to include $Node_Home/bin.
2. Run the following command to uninstall APM Node.js agent:
npm uninstall -g oracle-apm
Optional: Downloading the Master Installer on Demand
You can download the master installer again if you come across any errors while
performing any of the management tasks.
If you need to download the master installer again or your first download fails, you
can download the master installer as follows:
1.
On the navigation bar, click the navigator icon, and then click Oracle
Management Cloud Agents.
2.
On the Oracle Management Cloud Agents page, click Download on the left
navigation pane.
3.
Click the Learn more icon to access other information resources.
4.
Click the Download icon to download the master installer.
Before downloading the installer ZIP file, ensure that you delete old
instances of the ZIP file which you may have downloaded earlier in the
directory, or download the installer ZIP file to a different directory.
Note:
The master installer is a ZIP file that contains the following:
5.
•
AgentInstall.sh : The installation script used to deploy Oracle
Management Cloud agents on a UNIX-based platform.
•
AgentInstall.bat : The installation script used to deploy Oracle
Management Cloud agents on a Windows platform.
•
Read Me file: A file containing instructions about how to use the
AgentInstall script to install agents on your target hosts.
Click View available keys or create a new one.
For more information about registration keys, see Managing Registration Keys.
Upgrading and Deleting the Oracle Management Cloud Agents 4-13
Optional: Downloading the Master Installer on Demand
4-14 Deploying and Managing Oracle Management Cloud Agents
A
Syntax for Using the APM Java Agent
Installation Script
Here’s the syntax for using the ProvisionApmJavaAsAgent.sh script:
ProvisionApmJavaAsAgent.sh -d <domain_home> [ -h
<hostname> ]
[ -no-prompt [-overwrite]] [ -no-wallet ]
[ -ph proxy_host> -pp proxy_port> [ -pt
proxy_auth_token> ] ]
[ -c client_collector_url> ]
The following table describes the parameters of the
ProvisionApmJavaAsAgent.sh script.
Parameters
Description
-d <domain_home>
Specify the absolute path of the home directory of your application
server. This should be the absolute path of the home directory. The
APM Java Agent software will be installed under this directory.
-h <hostname>
(Optional)
Specify a valid fully qualified host name of your application server.
By default, the installation script determines the hostname of the
machine. Specify this parameter to override this value with another
hostname.
-no-prompt
(Optional)
Do not prompt for confirmation.
-overwrite
(Optional)
Usually, the ProvisionApmJavaAsAgent.sh script displays
various pieces of information that is either supplied to it, or that it
derives. Further, the script asks you to confirm the values. When no-prompt parameter is used, the values are displayed, but you will
not be prompted before proceeding.
Deploy APM Agent and overwrite existing APM Agent, if any.
This parameter works with the -no-prompt parameter.
•
•
Specify -overwrite with -no-prompt to overwrite APM Java
Agent installation without confirmation.
Use -no-prompt without -overwriteto upgrade the existing
installation. With upgrade, all customized properties are
retained.
Syntax for Using the APM Java Agent Installation Script A-1
Parameters
Description
-no-wallet
(Optional)
Do not use Oracle Wallet.
The ProvisionApmJavaAsAgent.sh script assumes that the
AgentInstall.sh script specified an Oracle auto-login wallet
containing the APM Java Agent's authorization token. This
authorization token allows the APM Java Agent to contact the cloud
services that it uses. Oracle Wallet is provisioned as the APM Java
Agent's credential store. This option supports an environment which
does not have the capability to use Oracle Wallet.
If the AgentInstall.sh script does not specify an Oracle Wallet,
then the provisioning script looks for the authorization token in the
properties file that is also specified by the AgentInstall.sh script.
If the -no-wallet parameter is specified, then while running the
provisioning script, this flag ensures that the provisioning script does
not use Oracle Wallet, even if one was provided by the
AgentInstall.sh script.
Instead, the authorization token of the APM Java Agent will be taken
from the properties file specified by the AgentInstall.sh script,
and provisioned in an alternative (non-wallet) credential store for the
APM Java Agent to use.
-ph <proxy host>
(Optional)
Specify the proxy host name if the APM Java Agent uses an HTTP
proxy.
-pp <proxy port>
(Optional)
Specify the proxy port if the APM Java Agent uses an HTTP proxy.
Specify the proxy authorization token if the APM Java Agent is using
HTTP proxy that requires authentication. The token is added to the
credential store of the APM Java Agent. The token is either an Oracle
auto-login wallet or the alternative credential store if a wallet is not
being used.
Sample Command
Following is a sample command that is used to run the
ProvisionApmJavaAsAgent.sh script.
./ProvisionApmJavaAsAgent.sh -d /WLS12.1.3/oracle_home/
user_projects/domains/acme_domain
Use of Outbound Proxy
Optionally, you can use an outbound proxy as the communication channel for the
application. If your environment uses an outbound proxy, then when you provision
your APM Java Agent, there are extra parameters in the
ProvisionApmJavaAsAgent.sh script to specify the proxy host and port. For more
information, run the ProvisionApmJavaAsAgent.sh script with the -help option.
Proxy Authentication
Use of proxy authentication is dependent on your environment. If you configured the
proxy to require authentication, there are additional parameters you must specify
while running the ProvisionApmJavaAsAgent.sh script. For more information,
run the ProvisionApmJavaAsAgent.sh script with the -help option.
A-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
B
Troubleshooting
This section lists some of the common issues such as agent connectivity, problems
during upgrade, and so on, and how these issues can be resolved. It covers the
following:
•
OMC Agent Deployment Video
•
OMC Agent Connectivity Issues
•
Data Collector Stopped Working After Upgrading to Enterprise Manager 13.x
•
Host Name Issues
•
Frequent Password Changes Impact Data Collection
•
Debugging Cloud Agent Installed Via Gateway
•
Remove Incomplete Data Collector Installation or Cleanup
•
Using Log Files for Debugging
•
Verifying if the CURL Version Supports TLS 1.2 Protocol
OMC Agent Deployment Video
This short video outlines the differences between installing OMC agents with and
without Enterprise Manager. It shows you how to install a cloud agent, add an entity,
and check the status of the newly added entity.
Video
OMC Agent Connectivity Issues
If you are encountering any connectivity issues between the OMC Agents and OMC,
then you can run the following command to check the connectivity issues after
installation.
Agent_Home/agent_inst/bin/omcli status agent connectivity
This command displays the list of connectivity issues at the agent.
Connectivity Command Without —verbose Flag
If you run this command without the –verbose flag, the first line of output identifies
the type of agent and whether or not it is running. The subsequent lines list all known
communication issues identified for this type of agent given its current availability
status. Issues output is organized in three columns
Troubleshooting B-1
Symptom
Cause
Observation Time
This is the symptom of the
issue. For example, one
symptom is "The agent is
unable to start."
This is the most likely cause
of the issue. For example, one
cause is "The agent is not
registered."
This is the earliest time the
agent made the observation.
Connectivity Command With –verbose Flag
If the user wishes to see more information, he can execute a more verbose flavor by
adding "-verbose" flag to the command. This adds the following columns:
Category
Confidence
Detail
The type of issue.
An internal measure of
confidence. This can be
thought of as a percentage,
where 100.0 is pure certainty
and 0.0 is no idea. The
confidence measure is based
on empirical data and code
knowledge.
A message that can give
more insight into the
occurrence. This may be an
exception message or
something else.
Understanding the Symptom and the Cause
Cloud Agent Issues
Cause
Symptom
AGENT_UNABLE_TO_START
due to
AGENT_NOT_REGISTERED
The agent cannot start without having been registered with
OMC. The entity id given during registration is what
identifies this agent to the cloud. That entity id is missing.
Agent Config phase runs agent registration. If this fails
(which can happen, for example, if there are required
proxy settings for the agent that are not supplied during
the install) then the agent will not be registered and will be
unable to start. Review the Install logs and check the proxy
settings.
AGENT_UNABLE_TO_COMM
UNICATE due to
SERVER_UNAVAILABLE
In this case, the agent cannot connect to the server. If the
cloud agent is configured for a gateway, it is unable to
connect to that gateway. It could be a network problem or
the gateway is not running. You can run the connectivity
command at the gateway to find out more.
AGENT_UNABLE_TO_COMM
UNICATE due to
AGENT_CERTIFICATE_MISM
ATCH
The agent cannot communicate with its gateway(s) or
OMC because of certificate mismatch failures.
There might be some third party certificate at the proxy
which got changed or perhaps there was some failure to
download the certificates or certificate change at the OMC.
Gateway Issues
B-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Cause
Symptom
AGENT_UNABLE_TO_START
due to
AGENT_NOT_REGISTERED
The agent cannot start without having been registered with
OMC. The entity id given during registration is what
identifies this agent to the cloud. That entity id is missing.
Agent Config phase runs agent registration. If this fails
(which can happen, for example, if there are required
proxy settings for the agent that are not supplied during
the install) then the agent will not be registered and will be
unable to start. Review the Install logs and check the proxy
settings
AGENT_UNABLE_TO_COMM
UNICATE due to
AGENT_CERTIFICATE_MISM
ATCH
The certificate the gateway uses to trust OMC is no longer
correct. This issue can occur if the certificates for OMC
change without gateway updates, or if the customer has a
proxy which also requires a certificate and that was
changed without gateway updates..
•
There is some issue with the OMC. You need to file a
service request.
•
•
AGENT_UNABLE_TO_UP
LOAD due to
DATARECEIVER_SERVIC
E_MISSING
AGENT_UNABLE_TO_DI
SPATCH due to
DATARECEIVER_SERVIC
E_MISSING
AGENT_UNABLE_TO_DI
SPATCH due to
WORKDEPOT_SERVICE_
MISSING
Data Collector Stopped Working After Upgrading to Enterprise Manager 13.x
If you have deployed the data collector on Enterprise Manager 12c and then upgraded
to Enterprise Manager 13.1 or a later version, the data collector needs to be updated.
To update the data collector, follow these steps:
1.
Click this link to download the patch_harvester_after_em_upgrade.sql
script or navigate to $ORACLE_HOME/sysman/admin/scripts/emaas/
harvester/patch_harvester_after_em_upgrade.sql
2.
Connect to the Oracle Management Repository database as a SYS user.
3.
Run the downloaded script using SYS credentials and provide the Data Collector
Schema Name as input.
You can find the Data Collector Schema Name by using the following statement:
SELECT owner
FROM all_objects
WHERE object_name = 'EMAAS_PERF_LOG'
and object_type = 'TABLE';
Note: If multiple rows are displayed in the output, then contact Oracle
Support to find out the correct active schema.
Troubleshooting B-3
4.
After the script has been executed, verify if the data collector schema has been
edition enabled as follows:
SELECT EDITION_ENABLED
FROM DBA_USERS
WHERE username = upper('&DATA_COLLECTOR_SCHEMA_NAME')
‘Y' indicates that edition has been enabled. If not enabled, try running the script
again. If you still see an issue, contact Oracle Support.
5.
Verify if all the objects are valid in the data collector schema as follows:
SELECT object_name from all_objects where owner =
upper(‘&DATA_COLLECTOR_SCHEMA_NAME’) and status = ‘INVALID’;
If any invalid objects are found, try recompiling it again. If you still see an issue,
contact Oracle Support.
Host Name Issues
You may see the following error while deploying OMC agents:
"Error: Unable to resolve the ORACLE_HOSTNAME/Computed
hostname : <hostname>.”
While installing the agent, if the system hostname does not resolve to a fully qualified
domain name (FQDN), because you are not using DNS, then, add the fully qualified
domain name in the etc/hosts file and ensure that it maps to the correct host name
and IP address of the host. Ensure that the localhost is reachable and resolves to
127.0.0.1. The recommended format is as follows:
<ip> <fully_qualified_host_name> <short_host_name>
For example:
If your hostname is "myhost" and your domain is example.com (IPv4):
172.16.0.0 myhost.example.com myhost
If your hostname is is "myhost" and your domain is example.com (IPv6):
aaaa::111:2222:3333:4444 myhost.example.com myhost
You can run the following commands to verify this. You should see the same
hostname and IP address displayed.
$getent hosts `hostname`
$host `hostname -f`
In the output, the fully qualified domain name must appear in the second field as
specified in the /etc/hosts file.
If you can ensure that short hostnames do not have the same value on different hosts
in your environment, you can ignore the FQDN requirement by pass the following
argument to the AgentInstall script:-ignorePrereqs with
ORACLE_HOSTNAME=<host_name>
Frequent Password Changes Impact Data Collection
When the OMR passwords are changed frequently, this may impact data collector
collection Due to the security policies at your data center, if the operating system
password for the user that was used to install the OMR is changed, then the data
B-4 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
collector will stop collection of performance and event data. To update the data
collector with the new password, follow these steps:
1.
Stop the data collector agent.
/<agent_install_directory>/bin/omcli stop agent
2.
Run the following command on the host that is running the data collector:
omcli change_datacollector_host_pwd agent <new password>
3.
Restart the data collector agent.
/<agent_install_directory>/bin/omcli start agent
Debugging Cloud Agent Installed Via Gateway
While installing the cloud agent via a gateway, ensure that the gateway host name you
provide is the same as the host name specified when the gateway was installed. Any
mismatch will result in a failure.
For example: If you have specified the host name as
ORACLE_HOSTANME=abc.xyz.com while deploying the gateway, but while
installing the cloud agent, you specify GATEWAY)HOST=abc, this will result in cloud
agent registration failure.
Error Example:
2017-02-10 11:29:39,308 [1:EE2D8594] DEBUG - Establishing connection to agent at
https://abc.xyz.com:1846/emd/lifecycle/main/... 2017-02-10 11:29:39,321 [1:EE2D8594]
DEBUG - setting user-interaction allowed to false 2017-02-10 11:29:39,329
[1:EE2D8594] INFO - Unable to connect to the agent at https://abc.xyz.com:1846/emd/
lifecycle/main/ [Connection refused] 2017-02-10 11:29:39,694 [1:EE2D8594] DEBUG Establishing connection to agent at https://abc.xyz.com:1846/emd/lifecycle/main/...
2017-02-10 11:29:39,694 [1:EE2D8594] DEBUG - setting user-interaction allowed to
false 2017-02-10 11:29:39,696 [1:EE2D8594] INFO - Disconnecting: client terminus
2017-02-10 11:29:39,696 [1:EE2D8594] INFO - stderr: Status agent Failure:Unable to
connect to the agent at https://abc.xyz.com :1846/emd/lifecycle/main/ [Connection
refused] 2017-02-10 11:29:39,696 [1:EE2D8594] INFO - Exit Code: 1
Remove Incompletely Installed Data Collector
You may need to remove the data collector if the installation is incomplete, or you may
need to delete the data collector schema if the data collector home has been manually
deleted, or if the host has been decommissioned, and so on. In this case, you need to
remove the data collector and clean up the left over schema in the Enterprise Manager
repository. Follow these steps to remove the data collector and the schema:
•
Click the Administration menu option on the Oracle Management Cloud
welcome page and then click Agents.
•
Click the Data Collectors menu option to navigate to the Data Collectors page. If
the data collector to be removed still appears on this page, select the data
collector, right click the Actions menu, then click Remove to remove the data
collector.
Note: Oracle recommends that you save a copy of the data collector schema
before you delete the data collector.
Troubleshooting B-5
•
Login as SYS user to the Oracle Management Repository host and the run the
script to drop collector schema. as follows:
@<script_path>
You are prompted for the <data_collector_schema_name>
To find the <data_collector_schema_name>, enter the following command:
SELECT owner
FROM all_tables
WHERE table_name='EMAAS_PERF_HV_PROPS'
If multiple rows are displayed, this indicates that there is more than one
data_collector_schema. You can either drop all the schemas, one after the
other, or contact Oracle Customer Support.
This script checks if the schema being dropped is data collector schema. If this
validation fails, then the schema will not be dropped.
•
In this case, using SYS user credentials, pass the
data_collector_schema_name as input and run the following command to
drop the data collector schema:
@DROP user <data_collector_schema_name> CASCADE;
Do not use this script if your data collector home is intact and it can communicate with
Oracle Management Cloud. In this case, follow the steps in Removing Data Collectors
section to de-install the data collector.
Using Log Files for Debugging
See Agent Install and Upgrade Logs for details.
Verifying if the CURL Version Supports TLS 1.2 Protocol
To check the TLS protocol supported by the CURL version on your host machine, run
the following command:
$curl --help | grep -i tlsv1.2
If you see tls1.2 in the output, then it indicates that CURL supports the TLS1.2
protocol.
Example
$ curl --help | grep tls
-1/--tlsv1 Use => TLSv1 (SSL)
--tlsv1.0 Use TLSv1.0 (SSL)
--tlsv1.1 Use TLSv1.1 (SSL)
--tlsv1.2 Use TLSv1.2 (SSL)
B-6 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
C
Modifying Proxy Server Settings
To modify the proxy server settings after the agent has been deployed, follow these
steps:
1.
View the current proxy server details being used by the cloud agent.
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYHOST
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
OMC_PROXYHOST=www-xyz.abc.oracle.com
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYPORT
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
OMC_PROXYPORT=20
2.
Clear the current proxy server settings.
/<agent_install_directory>/bin/omcli clear_property agent -name OMC_PROXYHOST
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
EMD clear_property succeeded
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYHOST
Oracle Management Cloud Agent Copyright (c) 1996, 2016 Oracle Corporation. All
rights reserved.
OMC_PROXYHOST=null
/<agent_install_directory>/bin/omcli clear_property agent -name OMC_PROXYPORT
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
EMD clear_property succeeded
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYPORT
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
OMC_PROXYPORT=null
3.
Set the new or updated proxy.
/<agent_install_directory>/bin/omcli setproperty agent -name OMC_PROXYHOST value "www-abc.xyz.example.com"
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
EMD setproperty succeeded
/<agent_install_directory>/bin/omcli setproperty agent -name OMC_PROXYPORT value 80
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
EMD setproperty succeeded
Modifying Proxy Server Settings C-1
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYHOST
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
OMC_PROXYHOST=www-abc.xyz.example.com
/<agent_install_directory>/bin/omcli getproperty agent -name OMC_PROXYPORT
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
OMC_PROXYPORT=80
4.
Stop / start the cloud agent.
/<agent_install_directory>/bin/omcli stop agent
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
Stopping agent ... stopped.
/<agent_install_directory>/bin/omcli start agent
Oracle Management Cloud Agent
Copyright (c) 1996, 2016 Oracle Corporation. All rights reserved.
Starting agent ................... started.
C-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
D
Running the AgentInstall Script
The AgentInstall script is used to deploy Oracle Management Cloud agents.
The AgentInstall script is a part of the master installer ZIP file, which also contains
areadme.txt file. For more information, see Accessing the Master Installer.
Syntax
This example shows the usage of the script and parameters.
AgentInstall.sh|bat
AGENT_TYPE=<Type of agent to be installed. It can be cloud agent, gateway,
or harvester>
AGENT_BASE_DIR=<Agent installation directory>
[AGENT_REGISTRATION_KEY=<cloud agent registration key>]
[AGENT_PORT=<Agent Port>]
[AGENT_INSTANCE_HOME=<cloud agent instance directory>]
[GATEWAY_HOST=<Gateway Host>]
[GATEWAY_PORT=<Gateway Port>]
[EM_AGENT_NAME=<EM Agent Name>|EM_AGENT_HOME=<EM Agent Oracle Home>]
[OMR_HOSTNAME=<OMR Host Name>]
[OMR_PORT=<OMR Port>]
[OMR_USERNAME=<OMR Username>]
[OMR_SID=<OMR SID>|OMR_SERVICE_NAME=<OMR Service Name>]
[OMR_HOST_USERNAME=<OMS Host OS user name>]
[OMR_STAGE_DIR=<Stage director>]
[HARVESTER_USERNAME=<Harvester User Name>]
[STAGE_LOCATION=<Stage Location>]
[ADDITIONAL_PARAMETERS=<Additional Parameters>]
[ADDITIONAL_GATEWAYS=<Additional Gateways>]
[AGENT_PROPERTIES=<Agent Properties>]
[CURL_PATH=<Curl Path>]
[UNZIP_PATH=<Unzip Path>]
[NAMESPACE=<Namespace to uniquely identify the harvested targets in ODS>]
[-download_only=<Only download the agent software>]
[-secureAgent=<Secures the agent and enables the agent communication in
https protocol>]
[-staged=<Use the staged software for deploying the agent.>]
[-help=<Usage of the AgentInstall.sh script>]
Parameters and Values Used While Running the AgentInstall Script
This section lists the parameters used while running the AgentInstall script along
with their descriptions and recommendations for values.
Parameters
Description
AGENT_TYPE
The type of cloud agent to be installed. It can be a cloud agent, gateway or
data collector.
Running the AgentInstall Script D-1
Parameters
Description
AGENT_BASE_DIR
The absolute path to the location where the cloud agent needs to be installed.
AGENT_REGISTRATION_KEY
The cloud agent registration key.
AGENT_PORT
The cloud agent port number.
AGENT_INSTANCE_HOME
The cloud agent instance home.
GATEWAY_HOST
The gateway host through which the cloud agent or data collector
communicates with Oracle Management Cloud.
GATEWAY_PORT
The gateway port.
EM_AGENT_NAME
The Oracle Enterprise Manager agent name. This should be in the format:
hostname:port. This parameter is mandatory for deploying a cloud agent
if you want to monitor data harvested from an existing on-premises Oracle
Enterprise Manager Cloud Control by using a data collector..
EM_AGENT_HOME
The Enterprise Manager agent Oracle home.
OMR_HOSTNAME
The Oracle Management Repository host name.
OMR_PORT
The Oracle Management Repository port.
OMR_USERNAME
The Oracle Management Repository user name.
OMR_USER_PASSWORD
The password used to sign in to the Oracle Management Repository in your
data center.
OMR_HOST_USERNAME
The OMR Host operating system user name.
OMR_STAGE_DIR
The stage directory that will be used by the data collector.
HARVESTER_USERNAME
The data collector user name.
HARVESTER_USER_PASSWOR
D
The password for the user to sign in to the data collector. The password rules
of the data collector are the same as that of the Oracle Management
Repository database password rules, because the data collector creates a
schema in the Oracle Management Repository database. However, data
collector passwords can’t have a special character or numeric as the first
character.
NAMESPACE
The namespace required to uniquely identify the harvested targets in Oracle
Data Store (ODS).
STAGE_LOCATION
The location where the cloud agent software needs to be staged.
ADDITIONAL_PARAMETERS
Any additional parameters.
ADDITIONAL_GATEWAYS
A list of gateway URLs. Provide a valid gateway URL in the format:
http://host:port.
AGENT_PROPERTIES
A list of agent properties. For example:
property1:value1,property2:value2.
CURL_PATH
The absolute path to the location of the curl binary.
UNZIP_PATH
The absolute path to the location of the extracted binary.
-download_only
The script downloads and stages the software without installing it.
D-2 Oracle Cloud Deploying and Managing Oracle Management Cloud Agents
Parameters
Description
-staged
The script uses the staged software for deploying the cloud agent.
-help
Get help about the usage of the AgentInstall.sh script.
Sample Commands
Use the sample commands given here as a reference. Substitute the values in the
command with values relevant to your environment when you run the
AgentInstall.sh script.
Sample Command for Deploying a Gateway
/scratch/AgentInstall.sh|bat
AGENT_TYPE=gateway
AGENT_BASE_DIR=/scratch/gateway_agent
AGENT_REGISTRATION_KEY=cKiu98Lpo6f
AGENT_PORT=1831
Sample Command for Deploying a Cloud Agent with an On-premises Oracle
Enterprise Manager Agent
/scratch/AgentInstall.sh|bat
AGENT_TYPE=cloud_agent
AGENT_BASE_DIR=/scratch/cloud_agent
AGENT_REGISTRATION_KEY=cKiu98Lpo6f
GATEWAY_HOST=example.com
GATEWAY_PORT=1831
EM_AGENT_NAME=example1.com:3872 AGENT_PORT=1831
Sample Command for Deploying a Cloud Agent Without an On-premises Oracle
Enterprise Manager Agent
/scratch/AgentInstall.sh|bat
AGENT_TYPE=cloud_agent
AGENT_BASE_DIR=/scratch/cloud_agent
AGENT_REGISTRATION_KEY=cKiu98Lpo6f
GATEWAY_HOST=example.com
GATEWAY_PORT=1831
Sample Command for Deploying a Data Collector
/scratch/AgentInstall.sh|bat
AGENT_TYPE=data_collector
AGENT_REGISTRATION_KEY=cKiu98Lpo6f
AGENT_BASE_DIR=/scratch/harvester_agent
GATEWAY_HOST=example.com
GATEWAY_PORT=1830
EM_AGENT_NAME=example1.com:3872
HARVESTER_USERNAME=EM_SAAS
HARVESTER_USER_PASSWORD=******
OMR_USERNAME=sys
OMR_USER_PASSWORD=******
OMR_HOSTNAME=example2.com
OMR_PORT=1521
OMR_SID=orcl
NAMESPACE=myOMR
AGENT_PORT=1832
Running the AgentInstall Script D-3
D-4 Deploying and Managing Oracle Management Cloud Agents
E
omcli Command Options
omcli commands let you work with the Oracle Management Cloud agents and
entities or targets. See omcli Command Options for details.
omcli Command Options E-1
E-2 Deploying and Managing Oracle Management Cloud Agents