10 Install and Configure APM Node.js Agent
Agent Requirements and Installation Instructions
Prerequisites
-
Any unzip utility.
-
The machine where you install the APM Node.js Agent should be able to establish an HTTPS connection either directly or indirectly (using a proxy server or an Oracle Management Cloud gateway) to Oracle Management Cloud. For more information about Oracle Management Cloud gateway, see Install a Gateway.
-
The HTTPS connection must use TLS 1.2 security protocol.
-
The install user should have read-write access to the directories that host the APM Node.js Agent (<
NODE_HOME/lib/node_modules
>) and to theSTAGE_DIR
(directory where the APM Node.js Agent installer ZIP file is extracted).
Set the NODE_PATH
Variable
Set the NODE_PATH
variable to point to node_modules
:
-
On Linux:
<Node Installation Directory>/lib/node_modules
-
On Windows:
<USER_HOME>\AppData\Roaming\npm\node_modules
Set the Proxy Variables (Optional)
If you are trying to deploy the APM Node.js Agent over a proxy server, then you need to set the proxy variables: http_proxy
and https_proxy
on the host where you are deploying the agents.
-
export http_proxy=http://www-hostname.abc.com:<port>/
-
export https_proxy=http://www-hostname.example.com:<port>/
If you’re using a C shell:
setenv http_proxy “proxy”
Deploy the Gateway (Optional)
-
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, Oracle WebLogic 10.3.6)
Set the Gateway Variables (Optional)
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>"
Download the APM Node.js Agent Software
-
On the Oracle Management Cloud home page, click the Oracle Management Cloud Navigation icon on the top-left corner to view the Management Cloud navigation pane.
-
Select Administration and Agents.
-
On the Oracle Management Cloud Agents page, click the Action Menu on the top right corner of the page and select Download Agents.
The Agent Software Download page is displayed.
-
From the Agent Type drop-down list, select APM Agent.
-
Click APM Node.js Agent.
This downloads the agent software ZIP file to the selected location.
-
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 Manage Registration Keys in Installing and Managing Oracle Management Cloud Agents.
-
Extract the contents of the installer ZIP file to an empty directory (for example,
STAGE_DIR
).
Install and Provision APM Node.js Agent
You can install and provision the APM Node.js Agent from an offline installer that you have received over email.
To install from the emailed ZIP, the provisioning script needs to download the configuration file from Oracle Management Cloud. The DownloadApmNodeAgentConfiguration.sh
script downloads the latest configuration from Oracle Management Cloud and generates the APM Node.js Agent configuration file oracle-apm-config.json
.
Specify these additional options while running the provisioning script:
Option | Description |
---|---|
-tenant-id |
The Oracle Management Cloud tenant name. |
-omc-server-url |
The URL of the Oracle Management Cloud server. Example: https://omchost:port |
Additional Gateway Options on Microsoft Windows
This version of APM Node.js Agent does not support Gateway options over Microsoft Windows.
If you are installing APM Node.js Agent over Microsoft Windows, follow these steps to configure additional gateways:
-
Ensure that the APM Node.js Agent is provisioned with Oracle Management Cloud/primary gateway successfully using the above steps.
-
Verify the installation. See steps below.
-
Manually copy the additional gateway/s certificates into the folder which has the extracted agent zip file.
-
To provision the additional gateway/s certificates, execute the below command:
cp "${CERT_FILE}" "<CERT_FILE_NAME>".der oracle-apm keytool der2pem "<CERT_FILE_NAME>".der "<CERT_FILE_NAME>" oracle-apm update data "<CERT_FILE_NAME>"
-
Navigate to the Node.js application home and execute the below commands to get the value of the current
uploadRoot
:mkdir -p oracle-apm/config oracle-apm config init oracle-apm config get uploadRoot
The value of the currentuploadRoot
is displayed as below. The newuploadRoot
will be displayed with the existing value, and the new URLs, separated by commas.oracle-apm config set uploadRoot <New value for uploadRoot>
-
To confirm that the new value has been updated, run
oracle-apm config get uploadRoot
-
Ensure that the
oracle-apm
directory is created in thenode_modules
directory of your Node installation as below.On Linux:
$NODE_HOME/lib/node_modules
On Windows:
<USER_HOME>\AppData\Roaming\npm\node_modules
-
In the
node_modules
directory withinoracle-apm
, a folder calleddata
is created with the following files:-
oracle-apm-config.json
-
emaas.cer
-
Gateway certificates, if the agent is provisioned with the gateway.
Example:
trustCertGateway.cer
-
If you see this error — npm ERR! code 1 - error
, it is an indication that oracle-apm
agent was not installed previously. You can proceed with the installation.
Verify APM Node.js Agent Installation
Configure APM Node.js Agents
You can use the APM Node.js Agent configuration tool to configure the APM agent in the user's application.
-
Ensure that the APM Node.js Agent is provisioned with Oracle Management Cloud successfully.
-
Navigate to the Node.js application home and confirm that the following directory exists:
<application_home>/oracle-apm/config
.If the directory does not exist then run the following command to create it under the
<application_home>
:mkdir -p oracle-apm/config
.
To initialize the oracle-apm
agent configuration tool in the directory of the Node.js application home, run the following command:
cd <application_home>
oracle-apm config init
As a result, two configuration files will be generated: oracle-apm-config.json
and url-normalizer-pattern.json
under the directory: <application_home>/oracle-apm/config
which is the default configuration directory for the APM Node.js agent.
-
To list the description of all the configuration properties, run the following command:
oracle-apm config listall
-
To list the current values of the configuration properties set in the Node.js application, run the following command:
oracle-apm config list
To check the value of a specific configuration property, run the following command:
oracle-apm config get <config_property_name>
oracle-apm config get injectionType
To update the value of a specific configuration property, replacing the old configuration property value with a new one, run the following command:
oracle-apm config set <config_property_name> <config_property_value>
oracle-apm config set injectionType reference