Product Documentation


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 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(); 
obj.ip_address = ""; 
obj.profile_username = "admin"; 
obj.profile_password = "verysecret"; 
obj.type = "ns"; 
managed_device managed_device_result = managed_device.add(ns_insight_session, obj);

Updating NetScaler Appliance's Logon Credentials

If the login credentials of a NetScaler appliance are updated after it is registered to a NetScaler Insight Center appliance, they have to be updated in the Insight 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].profile_name); 
device_profile obj = result[0]; 
obj.username = "admin"; 
obj.password = "newverysecretpassword"; 
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 with which to filter the virtual server information.
  3. Enable AppFlow on the virtual server.

The appliance starts gathering performance data about 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++) 
    Console.WriteLine("Name: " + result[i].name + ", IP Address: " + result[i].ip_address + ", Type: " + result[i].type + ", Appflow State: " + result[i].appflowlog); 
// Enable appflow on one of the virtual servers 
ns_vserver_appflow_config new_obj = new ns_vserver_appflow_config(); 
new_obj.ns_ip_address = ""; 
new_obj.type = "lb"; 
//Virtual server whose performance data must be gathered = "http_test"; 
new_obj.servicetype = "http"; 
// Policy rule 
new_obj.appflow_policy_rule = "true"; 
// Enable appflow data collection log 
new_obj.appflowlog = "enabled"; 
// Enable client side data collection log 
new_obj.es4nslog = "enabled"; 
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

Updated: 2014-03-24

The class provides the APIs to generate and view reports of applications. You must retrieve the details 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(); 
option_obj.duration = "last_1_month"; 
option_obj.pageno = 1; 
option_obj.pagesize = 25; 
option_obj.args = "app_unit_name:http_test"; 
device.get_with_options(ns_insight_session, option_obj); 
for (int i = 0; i < result.length; i++) 
    Console.WriteLine("Application: " + result[i].name + ", Total requests: " + result[i].total_requests + ", Total bytes: " + result[i].total_bytes  + ", Application response time: " + result[i].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/ folder.