4 Administer Oracle Application Performance Monitoring
An Oracle Application Performance Monitoring administrator can deploy and administer the service in your environment.
Typical Tasks for Administering Oracle Application Performance Monitoring
Here are the administrative tasks for Oracle Application Performance Monitoring.
Task | Description | More Information |
---|---|---|
Deploy Oracle Application Performance Monitoring | Download and install Oracle Application Performance Monitoring | |
Specify servlet configuration options | Specify how your web application / servlet is being monitored by Oracle Application Performance Monitoring. | |
Set rules for alerts | Set rules for email alerts | |
Set up Synthetic Monitoring | Set up synthetic monitoring, and monitor application performance through synthetic tests | Typical Workflow for Using Synthetic Monitoring |
Set up End User Monitoring | Set up End User Monitoring with manual browser injection, enable and configure settings | Set Up End User Monitoring |
Set up Synthetic Monitoring | Set up Synthetic Monitoring by simulating user paths to detect possible errors | Set Up Synthetic Monitoring |
Set up Custom Instrumentation | Set up Custom Instrumentation and start monitoring technologies not supported out-of-the-box. | Set Up Custom Instrumentation |
Enable Privacy Settings | Enable Privacy Settings to stop APM from storing personal identifiable information. | Enable Privacy Settings |
Customize APDEX Settings
The Application Performance Index, APDEX is a measurement of overall performance of your application.
APDEX is a summary of various measurements, with appropriate weightage on certain important results. Outliers which are otherwise ignored are given due importance in this index. The formula used to calculate APDEX = (Number of Satisfactory samples + (Number of Tolerating samples) / 2 ) / Total samples.
Session Health uses APDEX results for page and AJAX requests, along with the impact of error executions of java scripts and AJAX requests. With the Session health settings, you can influence the weightage given to the various components while calculating session health.
Associate Entities Using Tags
You can associate Application Servers to Database using tags.
- From the Oracle Management Cloud left navigation menu, click Administration and select Entities Configuration.
- Select Tags to view a list of tags that have already been discovered.
- In the Tags screen, click New Key to create a new association with tags.
- In the Create New Key screen, provide a name and value for the key.
Associate Application Servers to a Database Automatically
Application Performance Monitoring automatically creates an association between the App Server and the Database. When the association is not automatic, you can dynamically make the association through matching association tags.
Associate Application Servers to a Database through tags for a new Target
After installing and deploying Application Performance Monitoring, you can associate application servers to a database through tags. The below procedure is for a fresh installation of Application Performance Monitoring.
To associate an APM-Invisible Database with Application Server using tags:
-
Download the APM Agent Software Installer and provision APM Agent. See Types of APM Agents to install the correct APM Agent.
-
Shut down the application server to which you are associating the database.
-
Add the below property in the Properties file to generate an association from the application server to the database:
For APM Java agent:-
From the
apmagent/config
folder, edit theAgentStartup.properties
file and add the below property:<KeyName>=<Tag Value> oracle.apmaas.agent.appServer.uses = Tag_Weblogic_To_Oracle
-
Generic property tag: In the
AgentStartup.properties
file, you can add a new list of tags in the formattag-name [ = tag-value ]
to the below property:oracle.apmaas.agent.appServer.tags
Example:
The above property will create 3 tags:oracle.apmaas.agent.appServer.tags=credToUse=exampletag1,exampletag2,tag3=exampletag3
-
credToUse=exampletag1
-
exampletag2
-
tag3=exampletag3
-
For APM .Net agent:-
From the
<Path where APM Agent Software is extracted>\Oracle APM .NET Agent
folder, edit theAgentConfig.ini
file and add the below property:<KeyName>=<Tag Value> oracle.apmaas.agent.appServer.uses = Tag_DotNet_To_Oracle
In the above configuration file, the following is the Source Entity Marker tag:
Where:assoc_source:<AssociationHint>=<AssociationTag>
-
assoc_source:<AssociationHint>
is the tag key.<AssociationHint>
can be any free form text used to identify, and therefore associate the set of destination entities. The<AssociationHint>
used for the source entity, should match the one used for the destination entity(entities). -
<AssociationTag>
is the tag value.<AssociationTag>
is the intended association tag. It is optional, and if a value is not provided, it defaults toomc_uses
association tag.
An entity can be tagged with one or more source marker tags if the source entity can have different associations with different sets of destination entities. Ensure that the source marker tag is unique.
-
-
Start the application server.
-
Verify that the tags are added to the application.
-
From the Oracle Management Cloud left navigation menu, click Administration and select Entities Configuration.
-
Select Tags to view a list of tags that have already been discovered.
-
-
Verify that the application server is associated with the database in any of these ways:
-
From the Application Definition screen, view the topology.
-
From the App Server screen, click the Topology button to see the association.
-
You can also associate an App Server to a database from the APM UI. See Associating Entities Using Tags.
Discovering App Servers and Database entity using tag from Monitoring Service for a New Installation
-
Install the Oracle Cloud Agent.
-
To discover the database, modify the
db.json
and add the tag element.Example:
{ "entities":[ { "name":"Oracle_DB", "type":"omc_oracle_db", "displayName":"Oracle_DB", "timezoneRegion":"PDT", "credentialRefs":["SQLCreds"], "properties":{ "host_name":{"displayName":"MachineName","value":"sample.test.com"}, "port":{"displayName":"OraclePort","value":"1000"}, "protocol":{"displayName":"Protocol","value":"TCP"}, "sid":{"displayName":"SID","value":"sample"}, "capability": {"displayName": "capability","value": "monitoring"} }, "tags": { "assoc_dest:<assoc_name>" : "" } } ]}
Where
<assoc_name>
can be any string based on user preference. Discover the database entity using cloud agent (omcli add_entity agent db.json
). -
To discover the application server, modify the app server json and add the tag element.
Example:
where{ "entities":[ { "name":"Tomcat_Sample_Demo8", "tags": { "assoc_source:<assoc_name>" : "" }, "type":"omc_tomcat", "displayName":"Tomcat_Sample_Demo8", "timezoneRegion":"PDT", "properties":{ "host_name":{ "displayName":"Host", "value":"abcd.test.com" }, "jmx_port":{ "displayName":"JMX Port Number", "value":"9999"}, "jmx_user_name":{ "displayName":"JMX User Name", "value":""}, "jmx_password":{ "displayName":"JMX Password", "value":""}, "jmx_protocol":{ "displayName":"Communication Protocol", "value":"rmi"}, "jmx_service":{ "displayName":"Service Name", "value":"jmxrmi"}, "ssl_trust_store":{ "displayName":"SSL Trust Store (required when SSL is enabled)", "value":""}, "ssl_trust_store_password":{ "displayName":"SSL Trust Store JMXPassword (required when SSL is enabled)", "value":""}, "ssl_trust_store_password":{ "displayName":"SSL Trust Store JMXPassword (required when SSL is enabled)", "value":""},"version":{ "displayName":"Apache Tomcat Version", "value":"8"}, "catalina_base_directory_path":{ "displayName":"Catalina Base Directory Path", "value":"/scratch/opt/apache-tomcat-8.0.29"}, "LoggingConfigurationFilePath":{ "displayName":"Logging Configuration File Path", "value":""}, "LogLocationCatalina":{ "displayName":"Log Location Catalina", "value":""}, "LogLocationLocalhost":{ "displayName":"Log Location Local Host", "value":""}, "LogLocationHostManager":{ "displayName":"Log Location Manager", "value":""}, "LogLocationHostManager":{ "displayName":"Log Location Host Manager", "value":""}, "capability": { "displayName": "capability", "value": "monitoring"} } } ] }
<assoc_name>
string should be same as in the database json in step 2. Discover the Tomcat entity using cloud agent (omcli add_entity agent tomcat.json.
) -
"omc_uses"
association should be automatically created between Tomcat and the database entity.
Update the App Servers and Database entity using tag from monitoring Service
omcli cmd
. Here is a sample
json:{ "entities":[
{
"name":"Sample_DB",
"type":"omc_sample_db",
"displayName":"Sample_DB",
"timezoneRegion":"PDT",
"credentialRefs":["SQLCreds"],
"properties":{
"host_name":{"displayName":"MachineName","value":"sample.test.com"},
"port":{"displayName":"OraclePort","value":"1111"},
"protocol":{"displayName":"Protocol","value":"TCP"},
"sid":{"displayName":"SID","value":"orcl12c"},
"capability": {"displayName": "capability","value": "monitoring"}
},
"tags": {
"assoc_dest:<assoc_name>" : "",
"assoc_dest:<assoc_name2>" : "",
"key1" : "value1"
}
}
]}
Use
the omcli update_entity agent db.json
command to upload the new
tags from the entity json to Oracle Management Cloud.
Define Locations for Synthetic Tests
An administrator defines locations from where synthetic tests will be run.
-
Install Firefox browser on the machine where the cloud agent is installed:
- Oracle Linux 6: Firefox version 45
- Oracle Linux 7: Firefox version 61-66
Note:
Firefox is the only supported browser. Other Firefox versions including Beta versions are unsupported.You can check if Firefox is present on the cloud agent machine by running the command
firefox --version
.Install the relevant Firefox version on the host, and specify the correct path of the Firefox executable while defining a location. To migrate existing tests from Firefox 45 to Firefox 61, see Migrating Synthetic Tests to Firefox 61.
-
Firefox should be part of the
PATH
shell variable of the user used to run the cloud agent. For example, if Firefox executable is available at/scratch/firefox
, then/scratch/firefox
should be part of thePATH
variable. -
Install a Cloud Agent on the machine where the tests will be run. See Deploying Cloud Agents in Deploying and Managing Oracle Management Cloud Agents for instructions.
-
Ensure Perl is installed on the machine running the Cloud Agent.
-
Create an X Server pool, a set of X Servers which will be used to execute the Selenium test.
You can check if an X Server pool exists by running the commandps —ef
. For example, to check if there are any Xvfb X servers running, run following command:ps -ef | grep Xvfb
-
Any X Server can be used, but the recommended X Server is Xvfb. To create an X Server pool using Xvfb, run the following commands:
Every time the above commands are run, an X Server with the specified display port is created. These display ports can be used to specify the X Server pools, while creating a location.Xvfb :1 Xvfb :2 Xvfb :3 Xvfb :4 Xvfb :5
Note:
In case of an error when you run the above command, run this command instead:Xvfb :1 -nolisten inet6
The following is an example on how to setup Xvfb server and auto-start at system boot:-
$ sudo mkdir -p /usr/local/sbin # (if not already present)
-
$ sudo cp xvfb_start.sh xvfb_stop.sh /usr/local/sbin
-
$ sudo chmod 744 /usr/local/sbin/xvfb_start.sh /usr/local/sbin/xvfb_stop.sh
-
$ sudo cp etc_systemd_system_oracle.service /etc/systemd/system/xvfb.service
-
$ sudo systemctl daemon-reload
-
$ sudo systemctl enable xvfb
-
$ sudo systemctl start xvfb
-
$ sudo systemctl status xvfb
-
-
In the file
/etc/hosts
, replace127.0.0.1 localhost.localdomain loghost localhost
with
127.0.0.1 localhost localhost.localdomain loghost
. - The cloud agent should not be installed in a symbolic link directory, when installing the cloud agent the value provided for AGENT_BASE_DIRECTORY parameter should not be a symbolic link.
Migrating Synthetic Tests to Firefox 61
- Install version 61 (or higher) of Firefox on the machine where you will install the Cloud Agent.
- On the same machine, install Cloud Agent version 1.33 or higher.
- Define a Location using this Cloud Agent.
- Once this Location is active in the system, edit your synthetic test/s and add this new location to the test/s.
- Wait for Synthetic Tests to run on this new Location. You can verify this in the Instances tab where you will see data coming from two Locations. You can then edit the test and delete the location which was created using an older version of Firefox.
Configure Errors and Error Messages
-
HTTP response status code that ranges from 400 to 599
-
Exceptions thrown during operations execution
-
SOAP message response with a Fault block
-
OSB error codes
configurationsPerComponentType
to define the error rules. Each rule (exclude/include) is expressed as a key-value pair, where the key defines the error code selection and value defines the list of operations the rule applies to. The value is optional and if not specified, the error code selection applies to all operations of the specified componentTypes.
Here are the rules you can use to configure the errors:
Rule Type | Property | Type | Description |
---|---|---|---|
Component Type | componentTypes |
Array | List of component types the configuration should be applied for. The same configuration can be applied to multiple types. |
Opt-out (Exclude Rules) | excludeReturnCodes |
Map |
Key - an error code in String Value - an array of operation names in String |
excludeReturnCodesRegex |
Map |
Key - Regex pattern for the error code Value - a list of regex patterns for operation names |
|
excludeErrors |
Map |
Key - a string of error type. Error type key has to be exactly the same as the error type shown in Error Detail page. Value - a list of regex patterns for operation names |
|
excludeErrorMessages |
Map |
Key - a regex pattern of an error message Value - a list of regex patterns for operation names |
|
Opt-in (Include Rules) | includeReturnCodes |
Map |
Key - error code in String Value - an array of operation names in String |
includeReturnCodesRegex |
Map |
Key - Regex pattern for the error code Value - a list of regex patterns for operation names |
|
includeErrors |
Map |
Key - a string of error type. Error type key has to be exactly the same as the error type shown in Error Detail page. Value - a list of regex patterns for operation names |
|
includeErrorMessages |
Map |
Key - a regex pattern of an error message Value - a list of regex patterns for operation names |
|
Include First | includeFirst |
boolean | Determines which set of properties the configuration apply first to exclude or include server request instances from being marked as fault. |
Notes on how these error rules work:
-
includeFirst
- If
includeFirst
is false, opt-out rules are applied first in the following order:excludeReturnCodes → excludeReturnCodesRegex → excludeThrowableClasses → excludeThrowableMessages→includeReturnCodes → includeHttpReturnCodesRegex → includeThrowableClasses → includeThrowableMessages
- If
includeFirst
is true, opt-in rules are applied first::includeReturnCodes → includeHttpReturnCodesRegex → includeThrowableClasses → includeThrowableMessages → excludeReturnCodes → excludeReturnCodesRegex → excludeThrowableClasses → excludeThrowableMessages
- If
- Opt-in and Opt-out properties are independent of each other. A server request needs to satisfy only one of those properties in the configuration.
- All operations:For opt-in and opt-out properties, specify an empty list value or a list with an empty string to exclude or include any operation name with a key. For example, if you want agent to not report any error with HTTP 500 return code regardless of its operation name, you would define the following:
excludeReturnCodes : {"HTTP 500" : []} or, excludeReturnCodes : {"HTTP 500" : [""]}
- Look for these values in these APM views:
Server Request Instance page, Error Details tab Operation name Server Request Instance page, Call Tree table -
Operation name
-
Component Type
Error Details pane - Error
- Error code
- Error message
-
- Using Opt-in Properties: Use Opt-in properties if you use regex to opt-out many errors from the default rules but want to allow some cases to be still treated as errors. For example, if you want to exclude HTTP 5XX from the rules except HTTP 500, set the value of
includeFirst
totrue
so that opt-in properties can be applied first in the configuration.{ "type" : "error", "configurationsPerComponentType" : [ { "componentTypes" : ["SERVLET"], "excludeReturnCodes" : {}, "excludeReturnCodesRegex" : {"HTTP 5[0-9][0-9]" : []}, "excludeErrors" : {}, "excludeErrorMessages" : {}, "includeReturnCodes" : {"HTTP 500" : ["/hello/errorConfigTest/throwException (GET)", "/hello/errorConfigTest/throwException (POST)"]}, "includeReturnCodesRegex" : {}, "includeErrors" : {}, "includeErrorMessages" : {}, "includeFirst" : true } ] }
- Two Types with Overlapping PropertiesTwo or more component types can share the same customized rules if you specify all the types:
{ "type" : "error", "configurationsPerComponentType" : [ { "componentTypes" : ["SERVLET", "JAXRS", "SOA"], "excludeReturnCodes" : {}, "excludeReturnCodesRegex" : {}, "excludeErrors" : {"java.lang.RuntimeException" : ["/hello/errorConfigTest/throwException .*"]}, "excludeErrorMessages" : {}, "includeReturnCodes" : {}, "includeReturnCodesRegex" : {}, "includeErrors" : {}, "includeErrorMessages" : {}, "includeFirst" : false } ] }
- One Type with Multiple ConfigurationsOne type can belong to more than one
configurationsPerComponentType
if properties inconfigurationsPerComponentType
do not overlap. This is useful if one type share the same properties as other component types but have one or two property that don't. Make sure there is no duplicate property in two differentconfigurationsPerComponentType
to avoid redundancy.{ "type" : "error", "configurationsPerComponentType" : [ { "componentTypes" : ["SERVLET", "JAXRS", "SOA"], "excludeReturnCodes" : {}, "excludeReturnCodesRegex" : {}, "excludeErrors" : {"java.lang.RuntimeException" : ["/hello/errorConfigTest/throwException .*"]}, "excludeErrorMessages" : {}, "includeReturnCodes" : {}, "includeReturnCodesRegex" : {}, "includeErrors" : {}, "includeErrorMessages" : {}, "includeFirst" : false }, { "componentTypes" : ["SERVLET"], "excludeReturnCodes" : {"HTTP 500" : ["/hello/errorConfigTest/throwException (GET)"]}, "excludeReturnCodesRegex" : {}, "excludeErrors" : {}, "excludeErrorMessages" : {}, "includeReturnCodes" : {}, "includeReturnCodesRegex" : {}, "includeErrors" : {}, "includeErrorMessages" : {}, "includeFirst" : false } ] }
Enable Privacy Settings
Enable Privacy Settings to stop APM from storing personal identifiable information.
- Storing full URLs, not only the domains
- Storing page titles and click names
To enable or disable privacy settings:
- Log into Oracle Management Cloud and click APM.
- In the APM Admin page, click Privacy Settings.
Note that Web Application data will not be affected. Follow instructions on the configuration page to configure IP address reporting and URL related privacy settings based on your reporting requirements. It is strongly recommended to avoid collecting any personally identifiable information.