a  
 

Configuring application connector settings

   

proiv dashboard  

It is recommended that PPM configuration in the Virtual Machine and Application Connector settings should be configured to use the same PPM server for a named deployment. Failure to do so could result in the performance data being stored in different databases subsequently making it impossible to gain meaningful insight of performance throughout an application.

Analytics Configuration

  1. To set the Analytics configuration, on the Application Connector Settings tab, expand Analytics.
    The configuration page appears with default settings.

  2. Modify the configuration as required. The following table describes the fields that can be configured.

    Field Name

    Description

    Analytics Context Path

    The context path of the Analytics application.

    Host

    The host name of the server from which you can access Analytics application.

    Port

    The port the server hosting the application is listening on. The default port number is 9805.

    Protocol

    Select the protocol (HTTP/HTTPS) that is used to connect to the Analytics application. The default selection is "https".

    Callback Settings

    Host

    The host name of the server that Performance Manager will call back to. You can not change the host as it is read-only field.

    Port

    The port number of the server that Performance Manager will call back to. The default port number is 9802. You can not change the port number as it is read-only field.

Licensing Configuration

  1. To set the Licensing configuration, on the Application Connector Settings tab, expand Licensing.
    The configuration page appears with default settings.

  2. Modify the configuration as required. The following table describes the fields that can be configured.

    Field Name

    Description

    Host

    The host name of the licence server.

    Port

    The port number of the licence server. The Licence Server accepts requests from PROIV components on this port. The default port number is 5439. This can be altered to avoid port clashes.

    Serial Number

    The serial number that controls which licence pool is used. It is a group identifier which uniquely identifies a licence on a server.

    Acquisition Period

    The maximum wait time (in seconds) to acquire a licence on startup. The default value is 30 seconds.

    Retry Period

    The maximum interval (in seconds) between licence acquisition requests. The default value is 2 seconds.

Gateway Configuration

  1. To set the Gateway configuration, on the Application Connector Settings tab, expand Gateway.
    The configuration page appears with default settings.

  2. Modify the configuration as required. The following table describes the fields that can be configured.

    Field Name

    Description

    Listen Port

    The port that the Gateway server listens on for connections. The default port is 9835.

    Maximum Gateway Sessions

    The maximum number of simultaneous connections that the Gateway server can support. This sets a resource limit on the use of this Gateway server. If another attempt is made to use this Gateway server after the limit is reached, the user will get an error message and a message will be put in the general log. This must be greater than 0 and 20 is a good starting value. The default number is 5.

    Virtual Machine Settings

    Port

    The port used to connect to the virtual machine on Windows machine. For Unix platforms, this is the port used by the kernel to connect to the gateway. The default port number is 9833.

    Initial VMs

    The number of Virtual Machines to start up ready for Gateway server connections. This creates a pool of Virtual Machines that are ready and waiting for gateway server connections and this improves the response time at the expense of resources.

    The value must greater than 0 and must be less than the Maximum VMs value. The default number is 1.

    Maximum VMs

    The maximum number of Virtual Machines that this Gateway server allows. This sets a resource limit on the use of this Gateway Server. If another attempt is made to use this Gateway Server after the limit is reached, an error message appears and a message is put in the general log.

    The value must be greater than 0 and is constrained by your number of Gateway Licences. The default value is 5.

    Timeouts

    Startup Timeout

    For Unix platforms, this is the maximum number of seconds to wait for a Virtual Machine to start.  For Windows platforms, this is the maximum number of seconds to wait for a successful connection to be made to a Virtual Machine via the Virtual Machine service. This must be greater than 0. The default time is set to 60 seconds.

    Idle Timeout

    The maximum number of seconds a Virtual Machine can remain idle before the connection is closed. This must be greater than 0. The default value is 60.

    Read Select Timeout

    The number of milliseconds between read selects. Entering a value in this field configures the read_select_timeout parameter, which sets the PROIV Gateway's maximum wait time when it attempts to retrieve (read) data through NIO (Non-blocking I/O) data transfers before timing out and returning a 'Kernel not available' error message.

    The default setting is sufficient for many java-dependent applications that use NIO buffers. However, if other processes are consuming resources that are resulting in frequent read select timeouts, then increasing the value reduces the CPU load (that is, fewer read NIO buffer retries).

    Default value is 10 milliseconds. The maximum value is 1000 milliseconds.

    Response Timeout

    The maximum number of seconds to wait for a response from the Virtual Machine before timing out the operation.

    Note: This needs to be larger than the time taken for the slowest Task in your PROIV application. This must be greater than 0 and the default value is 60.

    Queuing

    Max Queue Size

    The maximum number of queued requests for sessions awaiting a free kernel. When the number of requests exceeds the number of available kernels, you can try increasing the maximum number of available kernels in the Maximum VMs field. This number is constrained by the number of Gateway licences that you have.

    Default is 100.

    Max Queue Wait Time

    The time in milliseconds that a request will be queued before getting a 'Virtual Machine not available' response. When the message displays, the request is removed from the queue and an error message is sent to the requestor. The default time is set to 1000 milliseconds.

    Environment Variables

    Environment variables are supplied to a Virtual Machine in UNIX environment.

    To add an environment variable, click New.

    1. In the Name box, enter the name for the variable.

    2. In the Value box, enter the value for the variable.

    To remove a variable, click the Delete button next to the variable.

    Pre Arguments

    The list of arguments to issue prior to the Virtual Machine start command in UNIX environment.

    1. Click New to add a value to argument.

    2. Enter the value for the argument.

    To remove an argument, click the Delete button next to the variable.

    Post Arguments

    The list of arguments to issue after the Virtual Machine start command in UNIX environment.

    1. Click New to add a value to argument.

    2. Enter the value for the argument.

    To remove an argument, click the Delete button next to the variable.

    VM Command Path

    The full path to the Virtual Machine execution script in UNIX environment.

    Authentication Model

    The JAVA class to be used for user authentication. "Default" is the selected model.

    When "JAAS" is selected, set values for Login Cache Timeout and Login Cache Size.

    Login Cache Timeout - The number of seconds that an authenticated user name/password will be regarded as valid without retrying the actual authentication. Note: The default time is set to '0' seconds to force each authentication request to be carried out. A good starting value is 3600.

    Login Cache Size - The maximum size of the cache containing authenticated user name/password combinations. Note: The default size is 2048.

Web Services Configuration

  1. To set the Web Services configuration, on the Application Connector Settings tab, expand Web Services.
    The configuration page appears with default settings.

  2. To configure PROIV connector, expand Connectors.
    The PROIV connector appears by default. To add a new connector, click Connectors and then click New.

  3. Click PROIV Connector to view the configuration. The following table describes the fields that can be configured.

    Field Name

    Description

    Name

    An unique name to identify the connector.

    Description

    The description of the connector.

    Enabled

    The slider is turned ON by default, indicates the connector is enabled.

    CODIV

    The company or division code required to access the PROIV application.

    Operator ID

    The operator ID required to access the PROIV application.

    Operator Password

    The operator password required to access the PROIV application.

    Encoding

    The encoding used for data transfers. The default is UTF-8.

  4. To delete a connector, click Connectors and then click Delete button next to the connector that you wanted to delete.
    The connector is deleted.

SOAP Services Configuration

  1. To configure SOAP Services, on the Application Connector Settings tab, expand Web Services and then Soap Services.
    The Demo Web Service appears by default. To add a new SOAP service, click Soap Services and then click New.
    To import an existing SOAP service, click Soap Services and then click Import.

  2. Click Demo Web Service to view the configuration. The following table describes the fields that can be configured.

    Field Name

    Description

    Name

    An unique name to identify the web service.

    Alias

    An alias name.

    Description

    The description of the web service.

    Enabled

    Turn ON the slider to enable the web service. The default value is set to True.

  3. Expand Functions to view the list of existing functions for Demo Web Service. To add a new function, click Functions and then click New. The following table describes the fields that can be configured.

    Connector

    Select PROIV connector to establish a connection between the SOAP web service and an application.

    Name

    An unique name to identify the function.

    Alias

    An alias name.

    Description

    A simple description of the web service.

  4. Click APDEX to view the default values of APDEX settings. The following table describes the fields that can be configured.

    Apdex Enabled

    The slider is turned OFF by default, indicates the APDEX scoring process is disabled. Turn ON the slider to enable APDEX scoring process.

    Satisfactory Duration (ms)

    Satisfactory Duration signifies the longest execution time of a transaction. The default value is 500.

    Tolerable Duration (ms)

    The transaction is considered as tolerable if the response time is greater than Satisfactory Duration but less than or equal to Tolerable Duration.

    Usually, the Tolerable Duration is by default set to a value of two times the Satisfactory Duration. The default value is 1000.

    Sample Period (ms)

    The sample period is the time period over which the APDEX score calculation is performed. The default value is 60000.

    Apdex Target

    Signifies a target or threshold on Apdex score. Apdex Target is a decimal value between zero and one. The higher the Apdex score, the better the system performance. Apdex scores falling below the Apdex Target will generate an alert if configured.

    The target application performance index is calculated as (Satisfied Count + (Tolerating Count/2)) / Total Samples. The default value is 0.8.

    Alert Name

    The alert name that needs to trigger.

  5. Expand Input Parameters.
    The existing parameters are displayed. To add a parameter, click Input Parameters and then click New. The following table describes the fields that can be configured.

    Name

    An unique name to identify the input parameter.

    Alias

    An alias name of the parameter.

    Description

    A simple description of the input parameter.

    Type

    The data type of the parameter, for example String.

    Min Length

    Appears for type 'Array'. Enter the minimum length of the parameter.

    Max Length

    Appears for type 'Array'. Enter the maximum length of the parameter.

  6. Expand Output Parameters.
    The existing reports are displayed. To add a new parameter, click Output Parameters and then click New. The following table describes the fields that can be configured.

    Name

    An unique name to identify the output parameter.

    Alias

    An alias name of the parameter.

    Description

    A simple description of the output parameter.

    Type

    The data type of the parameter, for example String.

    Min Length

    Appears for type 'Array'. Enter the minimum length of the parameter.

    Max Length

    Appears for type 'Array'. Enter the maximum length of the parameter.

Deleting Functions/Parameters - Select the function or parameter you wanted to delete and click Delete.
The function or parameter is deleted without any confirmation dialog.

RESTful Configuration Settings

The following configuration is common and are applicable to all REST services.

Restful Maximum Request Size

The maximum permissible size of the RESTful request object (MB)

Options Require Authorization

Authorization is the verification that the connection attempt is allowed. Should Options requests be protected by authorization

Asynchronous Expire Time

Time in seconds that asynchronous responses will remain available for collection. This configuration will help you to cancel an asynchronous operation after specified duration.

Restful Services

  1. To configure RESTful Web Service configuration, on the Application Connector Settings tab, expand Web Services and then RESTful Services.
    The PROIV Demo Service appears by default. To add a new RESTful service, click RESTful Services and then click New.
    To import an existing RESTful service, click RESTful Services and then click Import.

  2. Click RESTful Service to view the configuration. The following table describes the fields that can be configured for PROIV Demo Service or a new RESTful service.

    RESTful Web Service Definition

    ID

    An internal identifier of web service.

    Name

    An unique name that identifies the RESTful Service.
    Note: The name can be any text. However, you cannot have two services with the same name. If you save a service that has the same name as a service already saved on the server then its name will be changed to have [n] at the end (where n is a number).

    Description

    The description of the web service.

    Enabled

    The slider is turned ON to indicate that the service is enabled. If this is not set then the service is not available.

    Connector

    Select the required service connector from the list of the connectors defined in the Web Services. In case you have no connectors defined you will not be able to select a connector for the service. Refer to Connector Configuration for more information.

    CORS

    Abbreviation for Cross-Origin Resource Sharing. This is a mechanism that allows a restricted resource on a web page to be requested from another domain outside the domain from which the resource originated. The CORS field also holds the comma separated list of origins that are acceptable to the service. If you want to accept requests with no origin, then the CORS field must be empty (that is, CORS is turned off).

    The CORS field holds a list of origins and if the field contains at least one origin (* is counted as an origin) then the request must contain an ?Origin? header that matches one of the origins in the field. If it does not, then the request will be rejected with an error status (403 ? Forbidden).

    An origin can be either a protocol/host/port triple or a GUID (Globally Unique Identifier). If the origin is triple (most likely) then it can be defined in the CORS field as a full triple, without the protocol or without the port. The host must always be fully defined and no wild cards are allowed in the host name.

    An origin defined in the CORS field without a protocol will use whatever protocols are defined for the service.
    Note: A PROIV Restful service only supports the http or https protocols; so origins defined with other protocols will never match.

    The protocol defined for a service always overrides any protocol defined in an origin in the CORS field when looking for a match. For example, an origin of ?http://myhost.com:80? will never match if the service does not have the http protocol enabled even if the origin supplied in the request is identical.

    An origin defined in the CORS field without a port will use the default port defined for the service to do a match. For http that is ?80? and for https that is ?443?.

    It is acceptable to define an origin in the CORS field with just a host name. In this case it will attempt to match request origins using all the protocols defined for the service and the default port defined for the protocol.
    For more information on CORS, refer to https://www.w3.org/TR/cors/

    Exposed Headers

    The expose header name for the service to expose in response to any CORS service request; in case of multiple expose headers, separate the headers with a comma. The exposed headers will be returned in the response header ?Access-Control-Expose-Headers? for CORS simple requests. Currently, the PROIV REST code does not use any exposed headers for the service; however, by using expose headers - any calls to the service will let the caller know what headers are being used so this should only be used to expose ?public? information. There is no verification for these headers so their presence or absence will not cause any error status.

    Max Age

    The number of seconds that a CORS pre-flight request can cache its results before it needs to repeat the pre-flight request. This number is returned in the response header ?Access-Control-Max-Age? for a pre-flight request.

    Protocol

    The protocol used for the service can be HTTP, HTTPS or both but you must have at least one protocol selected.

    Request Headers

    The request header name for the service to accept; in case of multiple headers, separate the headers with a comma. A request header name defines a name that the service will accept in the request header called 'Access-Control-Request-Headers' for a CORS pre-flight request. The request headers that were accepted will be returned in the response header ?Access-Control-Allow-Headers? for the CORS pre-flight request.

    A service does not need to use any headers, hence the field can be left blank but if a CORS pre-flight request does specify headers in the ?Access-Control-Request-Headers? header, then these must be defined in this field or an error status will be returned as stated in the Failed Status Responses.

    Note The ?Authorization? header used by the PROIV REST server is automatically included in the list of acceptable request headers so does not need to be defined here.

    Credential Support

    Signifies that the service supports user credentials (security id/secret/task based authentication).

    Turn ON the slider to enable the credential support and configure security details.

    Security Id

    The security id. Setting the security id enables HTTP access security on the service. The server sends the text in this field to the client requesting the service and the client needs to respond with the security secret specified in the next field.

    Secret

    The secret text that the HTTP client needs to respond with if there is a security id. If there is no security id then this field is ignored.

  3.  Expand Paths and then click New to add a path. Use the following table to configure the values.

    Paths

    A service can have any number of paths defined.

    Path

    Enter the name of the path. The path is the last part of a URL that will be recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. When you create a new path it behaves as ?undefined? value and this is not a valid value and so gets highlighted by turning pink. A path can be deleted by clicking on the ? image to the right of the path. A path contents can be hidden and shown by clicking on the up or down arrow image on the right of the path.

    Method

    By default, a list of methods (Post, Put, Get and Delete) along with its corresponding task is displayed.

    Each path can have up to four methods (Post, Put, Get and Delete) and you can not have duplicate methods in a path. A path must have at least one method so one will be automatically created when you create a new path.

    You can create a new method for a path by clicking on the Paths and then click New. A method can be deleted by clicking on the Delete button to the right of the method, but as there must be at least one method you can not delete a method if it is the only method in the path. The method contents can be hidden and shown by clicking on the up or down arrow image on the right of the method.

    Expand Methods and configure the methods as per the description mentioned in the table.

    Post

    To configure a POST method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement.

    To configure APDEX settings for Post method, click APDEX and then refer to the APDEX section.

    Put

    To configure a PUT method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement.

    To configure APDEX settings for Put method, click APDEX and then refer to the APDEX section.

    Get

    To configure a GET method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement.

    To configure APDEX settings for Get method, click APDEX and then refer to the APDEX section.

    Delete

    To configure a DELETE method, refer to Configuration parameters of a Method section. You can add any number of parameters and responses as per your business requirement.

    To configure APDEX settings for Delete method, click APDEX and then refer to the APDEX section.

  4. Set the configuration for the selected method using the following table:

    Task

    A RESTful service needs a PRIOV task to perform the service action and each method may have a separate task. You can also use the same task on multiple methods or paths.

    Enter the task name that is available in the PROIV defined by the service connector.

    Description

    Text that describes this service, path, and method.

    Body

    Signifies the body schema for this service path and method.

    You can define the body data for a service method which requires request body data when it is called. Only methods of type ?post? or ?put? can define a request body. This body field defines a JSON schema for the request body content and the schema will be used by the test panel and the client generation tool to provide some checking that the request body has the correct structure before a call to the service is performed.

    For more information, click PROIV Demo Service and look at the values that are configured for the methods.

    Content-type

    Select the content of the method. Examples are text/plain, application/json, and application/xml.

    Response

    A service method may define the acceptable responses for a service call. You can create as many responses as you want and you do not have to define any responses.

    Status Code

    A response is defined by its HTTP status code which is a number (For example, 200 is the OK status). You can create a new response by clicking on the New button. A response can be deleted by clicking on the Delete button to the right in the list.

    A response status consists of a description (any text) and a response body schema. The schema field defines a JSON schema in the same way as the request body.

    Parameters

    A service method requires parameters when it is called. To add a new parameter for a method, click Parameters and then click New.
    A parameter contains a
    Name and Description.

    Parameters with the same name can be defined but only unique names are sent to the service so only one of the parameters with the same name can be used. The order of the parameters has no significance. Note: You need not to define parameters for a method.

  5. Click APDEX to view the default values of APDEX settings. Use the following table to modify the values.

    Apdex Enabled

    The slider is turned OFF by default, it indicates that the APDEX scoring process is disabled.

    Satisfactory Duration (ms)

    Satisfactory Duration signifies the longest execution time of a transaction. The default value is 500.

    Tolerable Duration (ms)

    The transaction is considered as tolerable if the response time is greater than Satisfactory Duration but less than or equal to Tolerable Duration.

    Usually, the Tolerable Duration is by default set to a value of two times the Satisfactory Duration. The default value is 1000.

    Sample Period (ms)

    The Sample period is the time period over which the APDEX score calculation is performed. The default value is 60000.

    Apdex Target

    Signifies a target or threshold on Apdex score. Apdex Target is a decimal value between zero and one. The higher the Apdex score, the better the system performance. Apdex scores falling below the Apdex Target will generate an alert if configured.

    The target application performance index is calculated as (Satisfied Count + (Tolerating Count/2)) / Total Samples. The default value is 0.8

    Alert Name

    Select the alert name that needs to trigger. In case, you do not want any alert, select "No Alert".

APDEX Alerts Configuration

  1. To configure Apdex Alerts, on the Application Connector Settings tab, expand Apdex Alerts.
    The default alerts are displayed. These have been supplied as examples of email and URL alerts. However, to create a new alert, click New.

  2. To view details of an alert, click on the Alert name. Use the following table to configure values for alert.

    Name

    Enter the name of the alert.

    Alert Frequency

    Allows specification of a "back off" period. If subsequent breaches of APDEX target occur within this period, the alert is suppressed.

    Alert Type

    Select Email to send an e-mail communication message or URL as alert type.

  3. Configure the fields based on the alert type, do either of the following:

    • For an e-mail alert, configure the fields using the following table.

      Server Hostname/IP

      The hostname or IP address of a server configured to send SMTP traffic.

      SMTP Port Number

      The SMTP port number for outgoing e-mail transmission.

      Username

      The username, if SMTP server requires authentication.

      Password

      The password, if SMTP server requires authentication.

      From

      The e-mail address of the sender.

      To

      The e-mail addresses where alert notification is to be sent.

      Subject

      The subject line of e-mail; summary of the purpose of the e-mail communication.

      Body

      The content of the e-mail message. Note: Tags - The default Email and URL alerts are created with a set of tags. These tags are replaced with actual values during runtime. The tags are ${apdex.service} ? service name, ${apdex.method} ? method in the service, ${apdex.required} ? APDEX target, ${apdex.actual} ? APDEX actual score, and ${apdex.difference} ? the difference between the target and actual APDEX values.

    • For an URL alert, configure the fields using the following table:

      URL

      The URL in the same format specified in a default URL alert.

      Method

      Select the method. (PUT, POST,GET)

  4. Click Submit.
    The configuration is saved.

Related Topics

Dashboard Overview

Comment on this topic

Topic ID: 830001

Table of Contents

Index

Glossary

-Search-

Back