Enable Business Transaction Correlation with SAP JCo

This section explains how to enable business transaction correlation for Java applications which communicate with SAP systems using SAP JCo library.

• Supported JCo versions: SAPJCo2, SAPJco3
• Supported SAP Java Resource Adapter (JRA)
• Minimum Java agent version: 4.3.8.x
• Known compatibility issue with Java Agent versions 4.5.5 to 4.5.8, fixed in 4.5.9
• Known compatibility issue with Java Agent versions 4.5.18 and newer, fixed in JCo extension 20.5.0 or newer

JCo Instrumentation Architecture

In the current version, the instrumentation of JCo RFC calls is done by a Java agent extension (SDK plug-in).

The following diagram describes the high-level architecture of the JCo instrumentation.

• Java application uses SAP JCo library to call RFC-enabled function modules in the SAP NetWeaver system.
• Java agent intercepts the RFC exit calls using the JCo extension.
• JCo extension sends the correlation information to the ABAP agent, which can start and stop continuing business transactions.

Install Java Agent and JCo extension

Use the generic procedure for Java Agent installation and continue with the following steps to see the RFC calls from Java to the SAP systems: 

1. Install Java Agent within SAP components by following the standard installation procedure described in Install the Java Agent.
2. Extract the ABAP Agent zip file, APPD-SAP-<version>.zip.
3. Copy the content of the APPD-SAP-<version>/AppServerAgent-JCo-plugin-<version>/ directory to [JavaAgentPath]/ver[JavaAgentVersion]/sdk-plugins/ directory.
4. Enable the unsigned extensions in the Java startup script using the allow.unsigned.sdk.extension.jars=true parameter.

If you are using SAP Application servers, the following tools can also help you add the Java Agent into the run time:

1. SAP NetWeaver Administrator 
2. AS Java Config Tool

Configuring Java Agent using SAP NetWeaver Administrator: 

1. Open the SAP NetWeaver Application Server Java web portal.
2. Click SAP NetWeaver Administrator >> Configuration >> Infrastructure >> Java System Properties >> Additional VM Parameters.
   1. Add a VM parameter for the unsigned SDK extensions, -Dallow.unsigned.sdk.extension.jars=true.
   2. Add a VM parameter -Dappdynamics.bciengine.should.implement.new.interfaces=false
   3. Add a VM parameter for the Java Agent, javaagent:<agent_home>/javaagent.jar.
   4. Click Save. 
3. Restart SAP server.

Configuring Java Agent using AS Java Config Tool: 

1. Open the SAP NetWeaver Application Server Java web portal.
2. Select the instance in AS Java Config Tool and click VM Parameters >> Additional. 
   1. Add a VM parameter for the unsigned SDK extensions, -Dallow.unsigned.sdk.extension.jars=true.
   2. Add a VM parameter -Dappdynamics.bciengine.should.implement.new.interfaces=false
   3. Add a VM parameter for the Java Agent, javaagent:<agent_home>/javaagent.jar.
   4. Click File, Apply Changes. 
3. Restart SAP server.

Logging in Debug Mode

1. Connect to the controller and navigate to Tiers & Nodes. 
2. Select the desired java node that needs to enable debug mode. 
3. Select Agents and click Request Agent Log File. 
4. Select Output from Specific logger, at a set level, for a fixed duration
   1. Logger Name: com.singularity
   2. Logger Level: Debug
   3. Duration (minutes): at least 10
      
      
5. Click Request Agent Log Files 
6. When the status turns successful, click Download.

Recommended

Start debug mode and attach logs to support tickets.

Authorizations

The following SAP users should be assigned to authorization role /DVD/APPD_JAVA:

• SAP users that call RFC from Java 
• SAP users used by RFC destinations 

See Cisco AppDynamics Authorizations for more details.

Start Business Transactions at JCo Server

To start a Business Transaction during JCo Server call, configure the following Java Agent POJO rule.

Continue Business Transactions at JCo Server

To be able to continue from an upstream Business Transaction on JCo Server, its necessary to modify your ABAP code on the system that calls the JCo Server. See Instrument custom ABAP code. 

For this to work correctly, the Java system must be restarted after the first installation of JCo plugin version 4.5.2002 or later.

SAP PI / PO (7.4) AS Java

The following table lists supported SAP PI / PO 7.4. Java Channels:

To view the outgoing SAP PI exitcalls, the BT must start or continue on SAP PI inbound channel using either Java Agent auto-detection or POJO rule.

RFC Blacklist and Whitelist

You can exclude or include RFC exitcalls from Java agent to ABAP agent using RFC blacklist and RFC whitelist functionality. To use blacklist or/and whitelist, add the jco-rules.xml file in the same directory as SAP_JCO_iSDK.jar.

RFC Blacklist

Specify function modules (FM) for which additional RFC calls are not performed. This means that a business transaction from Java Agent will not continue in a downstream ABAP agent (no Top 5 ABAP or SQL statements, ...).

To add a FM into blacklist add: <exclude type="fm">FUNCTION_MODULE</exclude> into jco-rules.xml file (Replace FUNCTION_MODULE with concrete function module name or pattern).

When blacklist is empty, no FM is excluded.

Additionally, you can globally disable correlation for stateless calls by adding (changing):

<exclude type="stateless">true</exclude>

As of release 25.2.0 correlation for stateless calls is disabled by default, and the rule "<exclude type="stateless">true</exclude>" is already present in delivered jco-rules.xml file.

RFC Whitelist

Specify function modules (FM) for which additional RFC calls will be performed. This means that a business transaction from Java Agent will continue in a downstream ABAP agent (as usual).

To add a FM into whitelist add: <include type="fm">FUNCTION_MODULE</include> into jco-rules.xml file (Replace FUNCTION_MODULE with concrete function module name or pattern).

When a whitelist is empty - all FMs are included. When whitelist contains a list of FMs, only the listed FMs are included.

Note

If the function module name is in both whitelist and blacklist, then the blacklist rule has a higher priority and therefore FM will be blacklisted.

Ensure that there is not more than one exclude element with type="stateless".