Troubleshoot APM Java Agent Deployment

Users may encounter different errors during APM Java agent deployment. Some common causes and actions are listed in this section.

Check network connectivity using AgentConnect

Check network connectivity using AgentConnect

Cause: Cannot connect to OCI APM upload endpoint.

Action: Use AgentConnect to troubleshoot network connectivity.

AgentConnect

AgentConnect is a utility that is used to test connectivity between the host running the APM agent and the OCI APM upload endpoint. It can diagnose different issues such as, SSL certificate problems, FIPS issues, PKI issues, proxy problems and many more.

AgentConnect is useful when some network tools, such as ping, curl or wget, are not available and/or not part of the environment. For example, some Docker or Kubernetes environments don't have the ping utility available.

Requirement: JDK available in the PATH or defined by the JAVA_HOME environment variable.
Location: After the deployment of the APM Agent, you can find AgentConnect under the oracle-apm-agent/bin directory.
Run AgentConnect: To invoke AgentConnect, use the following:
- For Windows: AgentConnect.bat
- For Linux: AgentConnect.sh
Example:
```
C:\apm\oracle-apm-agent\bin>AgentConnect.bat
```
When you invoke AgentConnect with no parameters, like the above example, it uses the AgentConfig.properties file to read all the configuration details.

If you want to override any of the properties in the AgentConfig.properties file, then you can do it from the command line.
AgentConnect help: To display all the help options available from the command line, invoke AgentConnect using the-hargument to display the command help. For example:
```
C:\apm\oracle-apm-agent\bin> AgentConnect -h
```

AgentConnect Output Examples:

AgentConnect Result: PASSED

See below an example when there's no network connectivity problems:

C:\apm\oracle-apm-agent\bin>AgentConnect.bat

The output looks similar to the following:

Using JAVA_HOME: "c:\java\jdk1.8.0_351"

Reading config file 'C:\apm\oracle-apm-agent\config\1.10\AgentConfig.properties'
java version "1.8.0_351" 
Java(TM) SE Runtime Environment (build 1.8.0_351-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.351-b10, mixed mode)

Testing 'https://aaabbbbcccc.apm-agt.us-phoenix-1.oci.oc-test.com/20200101/opentelemetry/v1/metrics'
    with datakey 'TTTTTEEEEEEMMMMGV4SIPDRJWI'   
    using JDK HttpURLConnection 

HTTP Server Response:
HTTP/1.1 200 OK
Strict-Transport-Security: max-age=31536000; includeSubDomains;
Connection: keep-alive
Content-Length: 0
opc-request-id: /DA962BB6C59E3E845EA503755ABB48C6/EFF6778EDE89E511072E05E2DD15FBFD
Date: Fri, 19 May 2023 14:38:25 GMT

===========================
AgentConnect Result: PASSED
===========================

At the end of the above output, you see the message: AgentConnect Result: PASSED which indicates that there's no connectivity problems between the host where the APM Java agent is running and the OCI APM upload endpoint. If there are problems, contact Oracle Support.

AgentConnect Result: FAILED

See below an example when there's network connectivity issues. In this example, the OCI APM upload endpoint value: https://endpoint.apm-agt.us-phoenix-1.oci.oc-test.com/ is passed as an argument when invoking AgentConnect:

C:\apm\oracle-apm-agent\bin> AgentConnect https://endpoint.apm-agt.us-phoenix-1.oci.oc-test.com/

The output looks similar to the following:

Using JAVA_HOME: "c:\java\jdk1.8.0_351" 
java version "1.8.0_351"
Java(TM) SE Runtime Environment (build 1.8.0_351-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.351-b10, mixed mode)

Testing 'https://endpoint.apm-agt.us-phoenix-1.oci.oc-test.com/20200101/opentelemetry/v1/metrics'
   using JDK HttpURLConnection

HTTP Server Cert Info:
Cipher Suite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  0) Cert Type: X.509
     Hash Code: 561797842
     Public Key Algorithm: RSA
     Public Key Format: X.509
     X509 Issuer: CN=DigiCert Global G2 TLS RSA SHA256 2020CA1, O=DigiCert Inc, C=US
     X509 Subject:CN=*.apm-agt.us-phoenix-1.oci.oc-test.com, O=Oracle Corporation, L=Redwood City, ST=California,      C=US
     X509 Signature Algorithm Name: SHA256withRSA 
     X509 Signature Algorithm OID: 1.2.840.113549.1.1.11
     X509 Start Date: Sun Jun   0517:00:00PDT 2022
     X509 End Date: Tue Jun 0616:59:59PDT 2023
     X509 PublicKey: Sun RSA publickey, 2048bits
     X509 Version: 3
  1) Cert Type: X.509
     Hash Code: -38378014
     Public Key Algorithm: RSA
     Public Key Format: X.509
     X509 Issuer: CN=DigiCert Global Root G2, OU=www.digicert.com, O=DigiCert Inc,      C=US
     X509 Subject: CN=DigiCert Global G2 TLS RSA SHA256 2020CA1, O=DigiCert Inc, C=US
     X509 Signature Algorithm Name: SHA256withRSA
     X509 Signature Algorithm OID: 1.2.840.113549.1.1.11
     X509 Start Date: Wed Sep 23 17:00:00 PDT 2020
     X509 End Date: Mon Sep 23 16:59:59 PDT 2030
     X509 PublicKey: Sun RSA publickey, 2048 bits
     X509 Version: 3

HTTP Server Response:
HTTP/1.1404 Not Found
Strict-Transport-Security: max-age=31536000; includeSubDomains;
Connection: keep-alive
Content-Length: 146
Date: Fri,19 May 2023 14:59:41 GMT
Content-Type: text/html

<html>
<head><title>404Not Found</title></head>
<body>
<center><h1>404Not Found</h1></center>
<hr><center>nginx</center>
</body>
</html> 

===========================
AgentConnect Result: FAILED
===========================

At the end of the above output, you see the message: AgentConnect Result: FAILED which indicates that there's network connectivity problems. The output includes the full HTTP headers and body, as well as information in the certificate(s) sent by the server. Contact Oracle Support for assistance.

Oracle Cloud Infrastructure Documentation