Install and Configure APM Node.js Agent

10 Install and Configure APM Node.js Agent

Topics:

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 the STAGE_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.

If you are using a Bash shell:

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)

A gateway is not a mandatory component while deploying Oracle 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, Oracle WebLogic 10.3.6)

For instructions on how to deploy the gateway, see Installing a Gateway in Installing and Managing Oracle Management Cloud Agents.

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

Navigate to the directory where you downloaded the APM Node.js Agent software (STAGE_DIR).

Execute the APM Node.js Agent installer.

OS	Example
On Linux:	`chmod +x ProvisionApmNodeAgent.sh ./ProvisionApmNodeAgent.sh`
On Windows:	`ProvisionApmNodeAgent.cmd`

The APM Node.js Agent installer prompts for the registration key. Provide the registration key and press Enter. The APM Node.js Agent gets installed.

For a list of options supported by the APM Node.js Agent provisioning script use:

Example:

OS	To get help
On Linux:	`./ProvisionApmNodeAgent.sh -help`
On Windows:	`ProvisionApmNodeAgent.cmd /?`

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:

OS	To override the default hostname
On Linux:	`./ProvisionApmNodeAgent.sh -h <hostname>`
On Windows:	`ProvisionApmNodeAgent.cmd /h <hostname>`

hostname will be one of the identity parameters of APM Node.js Agent which will be visible on the Oracle Management Cloud Application Performance Monitoring UI.

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.

./ProvisionApmNodeAgent.sh [-ph <proxy host>][-pp <proxy port>][-pt <proxy token>]

Proxy Option	Description
`-ph`	The proxy server host name. This is an optional parameter. Example: `-ph myproxyhost.example.com`
`-pp`	The proxy server port number. This is an optional parameter. Example: `-pp 80`
`-pt`	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 installing and provisioning the APM Node.js Agent with a gateway, use these additional values.

./ProvisionApmNodeAgent.sh [-gateway-host <gateway host>] [ -gateway-port <gateway port>] -additional-gateways <additional gateways>

Gateway Option	Description
`-gateway-host`	The gateway host through which the APM Node.js Agent communicates with the Oracle Management Cloud server. Example: `-gateway-host mygateway.example.com`
`-gateway-port`	The gateway agent port number. This is an optional parameter. Example: `-gateway-port 4459`
`-additional-gateways`	Comma separated list of gateway URLs. Example: `-additional-gateways https://mygateway2.example.com:1896,https://mygateway3.example.com:1897`

Also see Additional Gateway Options on Microsoft Windows

If you are installing APM Node.js Agent using a silent installation (unattended) option, use the following command:.

/ProvisionApmNodeAgent.sh -regkey-file <regkey file> [-tenant-id <tenant name>] -no-prompt

Silent Installation Option	Description
`-regkey-file <regkey file>`	The registration key information where `<regkey file>` is the filename of the registration key file.
`-tenant-id <tenant name>`	The tenant id information where `<tenant name>` is the tenant name.
`-no-prompt`	No user interaction is required.

Provision APM Node.js Agent with Offline Installer

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 current uploadRoot is displayed as below. The new uploadRoot 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
```

Verify the Installation:

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
In the node_modules directory within oracle-apm, a folder called data 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

Troubleshooting

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

To verify if the installation of Oracle Application Performance Monitoring is successful:

Examine 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 Oracle Application Performance Monitoring Web UI.
Look 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):
- ```
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.
Look 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}

Check 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:...

Use the Oracle Application Performance Monitoring Web Console

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.

Prerequisites

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.

Initialize the agent configuration tool

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.

List the configuration properties

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
```

Check a specific configuration property value

To check the value of a specific configuration property, run the following command:

oracle-apm config get <config_property_name>

Example:

oracle-apm config get injectionType

Update a specific configuration property value

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>

Example:

oracle-apm config set injectionType reference

Enable APM Node.js Agent

To enable APM Node.js Agent, the following line must be inserted as the first line in the monitored application's main module:

require('oracle-apm');