Product Documentation

Java SDK

May 04, 2017

You can use NetScaler Insight Center NITRO APIs to programmatically register a NetScaler appliance with the NetScaler Insight Center virtual appliance, gather performance data, and generate a report on this data. You can also troubleshoot NITRO operations by using the nitro_exception class.

Logging on to the NetScaler Insight Center Appliance

The first step toward using NITRO is to establish a session with the NetScaler Insight Center virtual appliance and then authenticate the session by using the administrator's credentials.

On the client system, create an object of the com.citrix.insight.nitro.service.nitro_service class by specifying the IP address of the NetScaler Insight Center virtual appliance and the protocol for connecting to the virtual appliance (HTTP or HTTPS). You then use this object to log on to the appliance.

Note: You cannot log on to a NetScaler Insight Center virtual appliance unless you have a user account on the virtual appliance. The configuration operations that you perform are limited by the administrative roles assigned to your account.

The following sample code establishes an HTTPs session with a NetScaler Insight Center virtual appliance with IP address

//Specify the NetScaler Insight appliance IP address and protocol 
nitro_service ns_insight_session = new nitro_service("","https"); 
//Specify the login credentials 
Note: You must use the nitro_service object in all further NITRO operations on the appliance.
Note: By default, the connection to the appliance expires after 30 minutes of inactivity. You can modify the timeout period by specifying a new timeout period (in seconds) in the login method. For example, to modify the timeout period to 60 minutes:

Registering a NetScaler Appliance

The com.citrix.insight.nitro.resource.config.mps.managed_device class provides APIs to register a NetScaler appliance with the NetScaler Insight Center virtual appliance. You must specify the NetScaler IP (NSIP) address, the user name, and the password of the NetScaler appliance.

The following sample code registers a NetScaler appliance with IP address

managed_device obj = new managed_device(); 
managed_device managed_device_result = managed_device.add(ns_insight_session, obj);

Updating a NetScaler Appliance's Login Credentials

If the login credentials of a NetScaler appliance are updated after it is registered to a NetScaler Insight Center virtual appliance, they have to be updated on the virtual appliance.

The following sample code updates the credentials of a NetScaler appliance:
managed_device device[] = managed_device.get(ns_insight_session); 
device_profile result[] = device_profile.get_filtered(ns_insight_session,"name:"+ device[1].get_profile_name()); 
device_profile obj = result[0]; 
device_profile.update(ns_insight_session, obj);

Gathering Performance Data about an Application

To gather performance data from applications (virtual servers) available on NetScaler appliances that are registered with the NetScaler Insight Center appliance, you must:

  1. Identify the application (virtual server) from which you want to collect information.
  2. Specify the expression on which the virtual server information must be filtered.
  3. Enable AppFlow on that application.

The appliance starts gathering performance data for the application. To display the performance data, see Generating Performance Reports.

The following sample code gets the list of all the available load balancing virtual servers that are available on the NetScaler appliance and enables appflow on a load balancing virtual server named http_test:

// Get the list of all load balancing virtual servers 
String filter = "ns_ip_address:,type:lb"; 
ns_vserver_appflow_config result[] = ns_vserver_appflow_config.get_filtered(client, filter); 
for (int i = 0; i < result.length; i++) 
    System.out.println("Name: " + result[i].get_name() + ", IP Address: " + result[i].get_ip_address() + ", Type: " + result[i].get_type()+ ", Appflow State: " + result[i].get_appflowlog()); 
// Enable appflow on one of the virtual servers 
ns_vserver_appflow_config new_obj = new ns_vserver_appflow_config(); 
//Virtual server whose performance data must be gathered 
// Policy rule 
// Enable appflow data collection log 
// Enable client side data collection log 
ns_vserver_appflow_config ns_vserver_appflow_config_result = ns_vserver_appflow_config.add(client, new_obj);
Note: To stop gathering data, disable AppFlow on the application.

Generating Performance Reports

The class provides the APIs to generate and view reports about applications. You must retrieve the details of the application and specify the period for which you want the details.

The following sample code generates a report for a load balancing virtual server named http_test:

device device_obj = new device(); 
options option_obj =  new options(); 
device.get_with_options(ns_insight_session, option_obj); 
for (int i = 0; i < result.length; i++) 
    System.out.println("Application: " + result[i].get_name() + ", Total requests: " + result[i].get_total_requests() + ", Total bytes: " + result[i].get_total_bytes()  + ", Application response time: " + result[i].get_application_response_time()); 

Exception Handling

The status of a NITRO request is captured in the com.citrix.insight.nitro.exception.nitro_exception class. This class provides the following details about the exception:

  • Session ID. The session in which the exception occurred.
  • Error code. The status of the NITRO request. An error code of 0 indicates that the NITRO request is successful. A non-zero error code indicates an error in processing the NITRO request.
  • Error message. A brief description of the exception.
Note: For a list of error codes, see the errorlisting.html file available in the <NITRO_SDK_HOME>/doc/api_reference folder.