VoIP Probe 3.4. Functions, Parameters & Metrics for integration with HP Business Availability Center via HP Business Process Monitor

Transcription

1 VoIP Probe 3.4 Functions, Parameters & Metrics for integration with HP Business Availability Center via HP Business Process Monitor ADVENAGE GmbH Blumenhagenstr. 10 D Hannover Germany March 2010

2 Contents Contents 1 Introduction General Concept Functions & Parameters adv_voipprobe_init adv_voipprobe_run adv_voipprobe_has_metrics adv_voipprobe_get_metric adv_voipprobe_get_error_info adv_voipprobe_end adv_voipprobe_options_init adv_voipprobe_add_option adv_voipprobe_options_end Metrics Advanced Topics License Logging Tracing SNMP PESQ/MOS Examples SIP call from and to one VoIP Probe Call Case Description Implementation...13 ADVENAGE GmbH Page 2

3 1 Introduction 1 Introduction This document describes the parameters and metrics of VoIP Probe for integration with HP Business Availability Center (BAC) via HP Business Process Monitor (BPM). HP BAC integration of ADVENAGE VoIP Probe via HP BPM affects HP BAC, HP BPM, HP Virtual User Generator (HP VuGen) and ADVENAGE VoIP Probe. ADVENAGE VoIP Probe provides a Dynamic Link Library (DLL) or shared library (on UNIX) allowing accessing the functionality of VoIP Probe Client. This library is used by HP VuGen to develop test scenarios and by HP BPM to run test cases. During test case development, HP VuGen is used to describe the test case in terms of parameters. There are mandatory parameters (such as calling party description, call duration time, and max. probe execution time) and optional parameters (such as called party description, CLI check, rejection of call answering, and DTMF tones to play at particular time intervals.). Some functions are provided by the DLL or shared lib to set-up and initialize a measurement with VoIP Probe. Detailed specifications are provided in separate documents and templates are provided to the convenience of the implementation team. After parameterization has finished, the probe run is started using the run method. Call case execution may take some time. After the call case completed, a number of metrics is accessible via the VoIP Probe API. A normal probe run causes 25+ metrics. Most probably, only a few metrics are relevant for the particular test case. The HP VuGen script allows to choose relevant metrics and to transfer only these ones to BAC. Some templates are provided to give developers a quick start. ADVENAGE GmbH Page 3

4 2 General Concept 2 General Concept VoIP Probe is parameterized and started via function calls from a HP VueGen scipt (type C VUser ). VoIP Probe supports HP Business Availability Center via HP Business Process Monitor and HP VuGen. Support is enabled through a shared library/dll being loaded on request. This file declares VoIP Probe support functions. The usual call flow to use VoIP Probe is: load DLL library "adv_voipprobe.dll". call adv_voipprobe_init with parameters explained below. This returns a pointer to the probe instance. call adv_voipprobe_run to execute measurement. check with adv_voipprobe_has_metrics for metrics. retrieve metrics with adv_voipprobe_get_metric and optionally error information with adv_voipprobe_get_error_info. destroy probe instance with adv_voipprobe_end. optionally use adv_voipprobe_options_init and adv_voipprobe_add_option to hand over additional options, e.g. to enable additional reporting path or enable SNMP support. Supported systems are Windows and Linux. ADVENAGE GmbH Page 4

5 3 Functions & Parameters 3 Functions & Parameters This section describes the functions provided by the VuGen extension adv_voipprobe. They allow to parameterize VoIP Probe, to run the probe and to retrieve metrics from the probe. Functions and parameters are declared in the include file adv_voipprobe.h. It is found on Windows systems in the installation directory of VoIP Probe, usually C:\Program Files\VoIP Probe or on UNIX in /opt/voipprobe. 3.1 adv_voipprobe_init void* adv_voipprobe_init ( char * calling_party, char * called_party, char * phoneno, int call_duration, char * answer_call, char * cli, int timeout, void * options ) Function to create VoIP probe object instance. Parameters handed over define probe behavior. calling_party is ptr to zero terminated C-string defining the calling party (CgP) as URL string. Valid URL strings include: [remote:<host>[:<port>] ]sip://[<login>[:<password>]@]<server>[:<port>] [remote:<host>[:<port>] ]h323://[<login>[:<password>]@]<server>[:<port>] [remote:<host>[:<port>] ]diva://<line device>:<own number> [remote:<host>[:<port>] ]gsm://<com-port>[:<pin>] [remote:<host>[:<port>] ]gsm://imei:<imei>[:<pin>] [remote:<host>[:<port>] ]pstn://<com-port> Additional extensions allow for protocol related additional features. For SIP and H.323 calling parties, the URL string may be extended by /stun=<stunserver>:<port> This enables STUN functionality for the particular party. Ports are optional. If not set, the default ports for the particular protocol will be used. The default SIP port is 5060, the default localport is 5060, the default STUN port is The 'bind=' and 'stun=' part are also optional. If the bind part is omitted, the first LAN interface of the system will be used. The address can also be specified as network part of an IP address, e. g. ' '. The probe searches then for a LAN interface in this network. This is useful if DHCP is used on the probe host. called_party SIP server and STUN server can be given as domain names. In this case a DNS lookup is done to find the correct IP addresses and ports. is ptr to zero terminated C-string defining the called party (CdP) as URL string. Valid URL strings include: [remote:<host>[:<port>] ]sip://[<login>[:<password>]@]<server>[:<port>] [remote:<host>[:<port>] ]h323://[<login>[:<password>]@]<server>[:<port>] ADVENAGE GmbH Page 5

6 3 Functions & Parameters [remote:<host>[:<port>] ]diva://<line device>:<own number> [remote:<host>[:<port>] ]gsm://<com-port>[:<pin>] [remote:<host>[:<port>] ]gsm://imei:<imei>[:<pin>] [remote:<host>[:<port>] ]pstn://<com-port> Additional extensions allow for protocol related additional features. For SIP and H.323 calling parties, the URL string may be extended by /stun=<stunserver>:<port> This enables STUN functionality for the particular party. Ports are optional. If not set, the default ports for the particular protocol will be used. The default SIP port is 5060, the default local port is 5060, the default STUN port is The 'bind=' and 'stun=' part are also optional. If the bind part is omitted, the first LAN interface of the system will be used. The address can also be specified as network part of an IP address, e. g. ' '. The probe searches then for a LAN interface in this network. This is useful if DHCP is used on the probe host. SIP server and STUN server can be given as domain names. In this case a DNS lookup is done to find the correct IP addresses and ports. phoneno is ptr to zero terminated C-string defining the number to dial/call for the calling party. If no phone number is given (empty string or zero pointer), a pure registration cycle is carried out and results are reported. call_duration is the integer value of the requested call duration in seconds. Must be smaller than timeout. answer_call is ptr to zero terminated C-string defining, whether the call shall be answered or not. If the ptr is 0, this means the call shall be answered. If the ptr is!= 0, the string value defines the behavior: "yes" means the call shall be answered. "true" means the call shall be answered. "no" means the call shall not be answered. "false" means the call shall not be answered. cli defines the caller line identification to check for as ptr to zero terminated C- string. If the ptr is 0, this means the CLI shall not be checked. If the ptr is!= 0, the string value defines the CLI to check. The CLI to check may contain wildcards, e.g. "* " matches " " as well as " ". If the CLI is specified and the displayed CLI of the incoming call does not match this parameter, the measurement fails (availability becomes 0). The CLI may contain the following special characters:? means exactly one arbitrary character * means any number (including zero) of arbitrary characters. Example: To check for a certain CLI regardless of the presentation of the national prefix specify * This will match as well as timeout is probe timeout in seconds. Must exceed call_duration. After this time interval, VoIP probe will stop measurement automatically. Typical values are starting with 60 seconds and are ranging to 300 seconds. options is optional pointer to options object instance. shall be set to zero, if not used. handle to VoIP probe object. In case of failures the handle returned may be zero. This handle is to be handed over to adv_voipprobe_run adv_voipprobe_has_metrics ADVENAGE GmbH Page 6

7 3 Functions & Parameters adv_voipprobe_get_metric adv_voipprobe_get_error_info adv_voipprobe_end 3.2 adv_voipprobe_run void adv_voipprobe_run ( void * p ) Function to run VoIP Probe object instance. This function actually carries out VoIP probe measurements in distributed environment. Execution time may be significant and is limited only by timeout parameter to adv_probe_init. p is handle to VoIP probe object obtained before with adv_voipprobe_init. Nothing 3.3 adv_voipprobe_has_metrics int adv_voipprobe_has_metrics ( void * p) Function to check for availability or VoIP Probe metrics. This function queries a VoIP probe object instance for availability of metrics. p is handle to VoIP probe object obtained before with adv_voipprobe_init. 0 if no metrics are available. 1 if metrics are available. 3.4 adv_voipprobe_get_metric double adv_voipprobe_get_metric ( void * p, char* metric_name ) Function to retrieve VoIP Probe metrics. This function queries a VoIP probe object instance for metrics by name. ADVENAGE GmbH Page 7

8 3 Functions & Parameters p metric_name is handle to VoIP probe object obtained before with adv_voipprobe_init. is ptr to zero terminated C-string containing name of the metric to be retrieved. Metric names are provided in the following section. Metric value as double according to further definitions. 3.5 adv_voipprobe_get_error_info char* adv_voipprobe_get_error_info ( void * p ) Function to retrieve error information as string from current VoIP probe object instance. p is handle to VoIP probe object obtained before with adv_voipprobe_init. ptr to zero terminated C-string containing error information message. 3.6 adv_voipprobe_end void adv_voipprobe_end ( void * p ) Function to destroy VoIP probe object instance. p is handle to VoIP probe object to be destroyed and obtained before with adv_voipprobe_init. Nothing 3.7 adv_voipprobe_options_init void* adv_voipprobe_options_init ( char * option_name, char * option_value ) Function to create an options object instance for VoIP Probe. Initial option may be handed over. option_name is ptr to zero terminated C-string containing option name. ADVENAGE GmbH Page 8

9 4 Metrics option_value is ptr to zero terminated C-string containing option value. handle to options object instance. This handle needs to be handed over to adv_voipprobe_add_option adv_voipprobe_options_end adv_voipprobe_init 3.8 adv_voipprobe_add_option void adv_voipprobe_add_option ( void * p, char * option_name, char * option_value ) Function to add additional options to options object instance. p is the handle to the options object instance created with adv_voipprobe_options_init. option_name is ptr to zero terminated C-string containing option name. option_value is ptr to zero terminated C-string containing option value. Nothing 3.9 adv_voipprobe_options_end void adv_voipprobe_options_end ( void * p ) Function to destroy options object instance. p is the handle to the options object instance to be destroyed. Nothing 4 Metrics Metrics measured by VoIP Probe and provided to HP Business Availability Center via HP Business Process Monitor: ADVENAGE GmbH Page 9

10 4 Metrics Name BPM Metric Type Unit Description Name Availability availability Long - Availability of the service can be 0 or 1. 0 means service is not available, 1 means service is available. Result code result_code Long - Result of the measurement. 0 means success. 1 means error (service unavailability). Basically this metric is similar to Availability, but Result Code matches better with BPM/BAC requirements. Registration registration_code Long - Result of the registration. 0 means success, 1 means Code failure. A failed registration does not cause the overall availability to become 0. Registration registration_time Double Seconds Time between first registration request and registration Time confirmation or terminal registration reject. Dial Time dial_time Double Seconds Time between call initiation started at the calling party side and ring indicator received at the called party side. In terms of ISUP this is the time between IAM request and ACM request. In terms of SIP this is the time between the initial INVITE request and the provisional replies Ringing (180) or Session Progress (183). If the called party is not a probe, the calling party determines the initial call setup time as time between INVITE request and reception of the provisional reply 180 or 183 at the calling party side. Alert Time alert_time Double Seconds Time between start of alerting (ringing) and call connection. In terms of ISUP this is the time between ACM and ANM. In terms of SIP this is the time between the provisional replies Ringing (180) or Session Progress and call set up completion (200 OK/ACK). Setup Time setup_time Double Seconds Time required for call initiation. Comprises Dial Time and Alert Time. Call Time call_time Double Seconds Duration of the call, i.e. the time the call is connected. Hang up Time Response Time hangup_time Double Seconds Time required for the hang up to finish. In terms of ISUP this is the time between REL and RLC. In terms of SIP it is the time between BYE and 200 OK. response_time Double Seconds Time elapsed between dialing started and call ended. In ISUP terms this is the time between IAM and RLC. In SIP terms the time between initial INVITE and final BYE/200 OK. It comprises Setup Time, Call Time and Hang Up Time. CLI Ok cli_ok Double 0 or 1 Flag indicating if the expected CLI has been sent to the B party (CdP). 1 means CLI matches expected value, 0 means a CLI mismatch. CLI Ko cli_ko Double 0 or 1 Flag indicating if the expected CLI has been sent to the B party (CdP). 0 means CLI matches expected value, 1 means a CLI mismatch. Inverse CLI Ok value, allows easier triggering of alerts in BAC. MOS CdP mos_cdp Double 0-5 Mean Opinion Score (Voice Quality) Calculated by the called party. Only if receiver is VoIP endpoint. Optional feature, requires separate license. RFC Jitter CdP Maximum Jitter CdP rfc_jitter_cdp Double Seconds Variance of the RTP data packet inter-arrival time according to RFC 3550 in ms for called party. Available for VoIP B tails only. max_jitter_cdp Double Seconds Maximum variance of the RTP data packet inter-arrival time according to RFC 3550 in ms for called party. Available for VoIP B tails only. loss_cdp Double Percent Packet loss in percent for the called party. Available for VoIP B tails only. rtt_cdp Double Seconds Round trip time for RTCP sender reports according to RFC 3550 in ms for called party Packet Loss CdP Round trip time CdP Delay CdP delay_cdp Double Seconds Packet delay measured on RTCP level according to RFC3550 for called party. Available for VoIP to VoIP calls only. MOS CgP mos_cgp Double 0-5 Mean Opinion Score (Voice Quality) Calculated by the calling party. Only if receiver is VoIP endpoint. Optional feature, requires separate license. ADVENAGE GmbH Page 10

11 4 Metrics RFC Jitter CgP Maximum Jitter CgP rfc_jitter_cgp Double Seconds Variance of the RTP data packet inter-arrival time according to RFC 3550 in ms for calling party. Available for VoIP B tails only. max_jitter_cgp Double Seconds Maximum variance of the RTP data packet inter-arrival time according to RFC 3550 in ms for calling party. Available for VoIP B tails only. loss_cgp Double Percent Packet loss in percent for the calling party. Available for VoIP B tails only. rtt_cgp Double Seconds Round trip time for RTCP sender reports according to RFC 3550 in ms for calling party Packet Loss CgP Round trip time CgP Delay CgP delay_cgp Double Seconds Packet delay measured on RTCP level according to RFC3550 for calling party. Available for VoIP to VoIP calls only. The diagram below (Figure 1: Sequence Diagram of Measurement) depicts the metrics in the context of the sequence diagram of a VoIP probe measurement: Figure 1: Sequence Diagram of Measurement The diagram below (Figure 2: Sequence Diagram for Registration) depicts registration of the calling party at the registrar: ADVENAGE GmbH Page 11

12 5 Advanced Topics Figure 2: Sequence Diagram for Registration 5 Advanced Topics 5.1 License VoIP probe requires a license from ADVENAGE to run. The license file can be requested via sales@advenage.com. VoIP Probe is searching for valid license files in the current directory, the directory from which the DLL is loaded (assuming default installation path, this C:\Program Files\VoIP Probe (Windows) or /opt/voipprobe/bin (Linux)), the installation directory of VoIP Probe, or in case of an OVIS installation - the OVIS probes directory. If no valid license could be found, measurements fail with the error information no valid license found and additional information is logged to the log file of VoIP Probe. 5.2 Logging VoIP Probe keeps its own log file supporting log rotation and varying log levels. Log files are written by default to the file C:\Program Files\VoIP Probe\log\voipprobe.log (Windows, assuming default installation paths) or /opt/voipprobe/var/voipprobe.log (Linux, assuming default installation paths). Default log-level is Info (6). It may be changed via the VoIP Probe options. 5.3 Tracing VoIP Probe maintains telco style traces for all calls reporting call events on a per call base. Trace files are created locally and may be transferred to a central repository using FTP or FTPS. Default filename conventions may be overridden by options. 5.4 SNMP Unavailability of the service monitored can be reported by VoIP Probe directly via SNMP as trap to one or several SNMP targets. This feature is enabled via VoIP Probe options. 5.5 PESQ/MOS PESQ/MOS analysis is an optional feature of VoIP Probe. To enable it, a special licenses is necessary. After the license has been installed, PESQ/MOS values are reported automatically. Until the license is installed, PESQ/MOS metrics are always 0.0. ADVENAGE GmbH Page 12

13 6 Examples 6 Examples 6.1 SIP call from and to one VoIP Probe This is one of the examples distributed with VoIP Probe. The VuGen source code for this example is part of the distribution and found in the examples directory Call Case Description This call case is a SIP call from a SIP user agent A to a SIP user agent B over an IP network via a SIP registrar and SIP proxy server. The call case is depicted (in parts) by the figure below: A HP Business Process Monitor is running on a computer system linked to a HP BAC system. The HP BPM runs VoIP Probe with two user agents A and B. First step of the probe operation is to register both user agents with the registrar over an IP network. After the registration completed, A invites B to a call and the call is proceeding until the call duration is exceeded. Afterwards, the call is released, metrics are calculated and reported via BPM to BAC Implementation Typical BPM test-case implementations depend on HP VuGen scripts. The figure below depicts the implementation o this scenario as VuGen script comprising the sections vuser_init, Action and vuser_end. #include "C:/Programme/VoIP Probe/adv_voipprobe.h" vuser_init() { lr_load_dll ("C:/Programme/VoIP Probe/adv_voipprobe.dll"); return 0; } Action() { void * probe; void *options; options = adv_voipprobe_options_init ("loglevel","11"); /* set log level to tracing */ probe = adv_voipprobe_init ( "sip://a:secret@ :5060", /* calling party */ "sip://b:secret@ :5060/bind=:5080", /* called party */ "21", /* phoneno to dial */ 15, /* requested call duration in seconds */ "", /* Answer call?*/ "", /* CLI to check */ 60, /* probe timeout in seconds */ options); if (probe) { adv_voipprobe_run (probe); if (adv_voipprobe_has_metrics(probe) && adv_voipprobe_get_metric (probe,"availability") > 0.0) { lr_set_transaction ("voip_registration_time", adv_voipprobe_get_metric (probe,"registration_time"), LR_PASS); lr_set_transaction ("voip_dial_time", adv_voipprobe_get_metric (probe,"dial_time"), LR_PASS); ADVENAGE GmbH Page 13

14 6 Examples lr_set_transaction ("voip_alert_time", adv_voipprobe_get_metric (probe,"alert_time"), LR_PASS); lr_set_transaction ("voip_setup_time", adv_voipprobe_get_metric (probe,"setup_time"), LR_PASS); lr_set_transaction ("voip_call_time", adv_voipprobe_get_metric (probe,"call_time"), LR_PASS); lr_set_transaction ("voip_hangup_time", adv_voipprobe_get_metric (probe,"hangup_time"), LR_PASS); lr_set_transaction ("voip_response_time", adv_voipprobe_get_metric (probe,"response_time"), LR_PASS); lr_set_transaction ("voip_cli_ko", adv_voipprobe_get_metric (probe,"cli_ko"), LR_PASS); lr_set_transaction ("voip_mos_cdp", adv_voipprobe_get_metric (probe,"mos_cdp"), LR_PASS); lr_set_transaction ("voip_rfc_jitter_cdp", adv_voipprobe_get_metric (probe,"rfc_jitter_cdp"), LR_PASS); lr_set_transaction ("voip_max_jitter_cdp", adv_voipprobe_get_metric (probe,"max_jitter_cdp"), LR_PASS); lr_set_transaction ("voip_loss_cdp", adv_voipprobe_get_metric (probe,"loss_cdp"), LR_PASS); lr_set_transaction ("voip_rtt_cdp", adv_voipprobe_get_metric (probe,"rtt_cdp"), LR_PASS); lr_set_transaction ("voip_delay_cdp", adv_voipprobe_get_metric (probe,"delay_cdp"), LR_PASS); lr_set_transaction ("voip_mos_cgp", adv_voipprobe_get_metric (probe,"mos_cgp"), LR_PASS); lr_set_transaction ("voip_rfc_jitter_cgp", adv_voipprobe_get_metric (probe,"rfc_jitter_cgp"), LR_PASS); lr_set_transaction ("voip_max_jitter_cgp", adv_voipprobe_get_metric (probe,"max_jitter_cgp"), LR_PASS); lr_set_transaction ("voip_loss_cgp", adv_voipprobe_get_metric (probe,"loss_cgp"), LR_PASS); lr_set_transaction ("voip_rtt_cgp", adv_voipprobe_get_metric (probe,"rtt_cgp"), LR_PASS); lr_set_transaction ("voip_delay_cgp", adv_voipprobe_get_metric (probe,"delay_cgp"), LR_PASS); } else { lr_fail_trans_with_error ("VoIP Probe failed: %s", adv_voipprobe_get_error_info (probe)); lr_set_transaction ("voip_response", adv_voipprobe_get_metric (probe,"response_time"), LR_FAIL); } } adv_voipprobe_end (probe); adv_voipprobe_options_end(options); return 0; } vuser_end() { return 0; } This example transfers almost any metrics to BAC. In real-world applications, you will probably focus on a few metric values. ADVENAGE GmbH Page 14