Workload Management classification of requests in IBM HTTP Server for z/os Powered by Apache

Transcription

1 Workload Management classification of requests in IBM HTTP Server for z/os Powered by Apache WP This document can be found on the web at: Search for document number WP under the category of "TechDocs" Version 1.0 Author: Edward McCarthy IBM Last Updated: 26 January 2011, 20:31 WP WLM classification of requests in Apache HTTP Server on z/os Page 1 of 25

2 Table of Contents 1 WLM CLASSIFICATION OF REQUESTS IN IBM HTTP SERVER FOR Z/OS4 1.1 Introduction Acknowledgements The purpose of this IHS module What is Workload Management ( WLM ) Files supplied with this techdoc How to setup your environment to use this sample module RACF - Access to BPX.WLMSERVER WLM definitions IHS httpd.conf file The new WLM directives for use in the httpd.conf file Relationship between WLM directives and WLM wlmsubsystype wlmcollectionname wlmtranclass wlmdebug Guide to coding the WLM directives in the httpd.conf file The default approach map all requests to one WLM transaction class Mapping two applications to two WLM transaction classes Mapping requests for a specific domain to a WLM transaction classes Relationship of sample URLs to WLM directives Monitoring with RMF RMF MON III WLM Reports Testing our module Compiling the IHS WLM module and other related setup Our environment Directory for the module code Compile the module Configure IHS server Update NameVirtualHost directive Add wlm module to IHS configuration Debug messages JMeter How to run JMeter WLM API Error codes DETAILS ON THE MODWLM SAMPLE MODULE Details how the WLM sample module classifies requests to WLM Standard Apache module coding Hooks used in this module ap_hook_child_init ap_hook_post_read_request ap_hook_fixups ap_hook_handler...21 WP WLM classification of requests in Apache HTTP Server on z/os Page 2 of 25

3 2.3 modwlm processing Process WLM related directives Start child processes 1 to n Child process Hook: child_init Receive request WLM Directive processing Hook: post_read_request Hook: fixups Request processing call back: end_of_request send reply modwlm_child_exit Document Change History...25 WP WLM classification of requests in Apache HTTP Server on z/os Page 3 of 25

4 1 WLM classification of requests in IBM HTTP Server for z/os 1.1 Introduction IBM has previously published two articles on the IBM HTTP Server for z/os powered by Apache, they are: 1. IBM HTTP Server V6.1 - The IBM HTTP Server for z/os Powered by Apache a ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP Extending the IBM HTTP Server for z/os Powered by Apache with custom modules a ibm.com/support/techdocs/atsmastr.nsf/WebIndex/WP This document describes how to classify requests received by IBM HTTP Server for z/os Powered by Apache to a nominated Workload Management transaction class. Ideally before embarking on following the advice in this article, you should have read the above articles and have established a working IBM HTTP Server for z/os Powered by Apache on your z/os LPAR. Any reference to IBM HTTP Server ( IHS ) for the remainder of this document is referring to the IBM HTTP Server for z/os Powered by Apache Acknowledgements The author would like to acknowledge the assistance of the following IBMers who assisted with the development of this techdoc and the associated sample modules: Mike Cox of the Washington Systems Center From the z/os Workload Management area: Ralf Thelen, Robert Vaupel, Stefan Sell From the IHS on z/os team: Eric M Covener, Ralph Adams, Gregory Ames 1.2 The purpose of this IHS module The purpose of this IHS module is to provide a way to associate each request processed by IHS with a Workload Management ( WLM ) enclave. Classifying IHS requests in this manner then allows you to set performance objectives and also to obtain RMF reports that provide details about how the requests are performing such as average response times and CPU used. To achieve this classification of requests, this IHS module provides new directives that WP WLM classification of requests in Apache HTTP Server on z/os Page 4 of 25

5 can be added to the IHS configuration file, which by default is httpd.conf. You use these directives to associate the URL of requests with WLM transaction classes, which in turn is associated with a service class and optionally a report class. You may currently have IHS servers that process requests for a number of applications, but you do not know much CPU is used by each application. By classifying requests for applications into different WLM transaction classes you can produce corresponding WLM reports. These reports show for each interval the following information: 1. number of requests processed 2. average response time 3. amount of CPU used Note if the requests are invoking CGI, the CPU used during the CGI processing is not captured. You can also use RMF MON III to monitor WLM transaction classes in real time. This would be useful to determine if response time targets for an application were being met What is Workload Management ( WLM ) The target audience for this article is those running IBM HTTP Server on z/os who want to classify requests into a WLM transaction class. As such someone working in that environment will more then likely have an understanding of WLM or have access to someone who does. In case this is not true, then the following link provides an introductory point where you can start to gain an understanding the WLM capability of z/os: topic=/com.ibm.zos.zconcepts/zconc_whatiswlm.htm The following is an extract from the above link: In simple terms, WLM has three objectives: To achieve the business goals that are defined by the installation, by automatically assigning sysplex resources to workloads based on their importance and goals. This objective is known as goal achievement. To achieve optimal use of the system resources from the system point of view. This objective is known as throughput. To achieve optimal use of system resources from the point of view of the individual address space. This objective is known as response and turnaround time. A good overview article is also available here: inistrator/10079p1.aspx Files supplied with this techdoc On the link where you download this techdoc from is a link where you can download a WP WLM classification of requests in Apache HTTP Server on z/os Page 5 of 25

6 zip file, which contains the following files: modwlm.c the source code for the sample module httpd.conf the file from our IHS server modwlm.jmx - file to run load test with JMeter ihs-wlm-report.txt sample WLM report error_log.txt sample IHS error log showing debug messages 1.3 How to setup your environment to use this sample module The following describes how to set up your IHS server and WLM environment to use our sample module on your z/os LPAR. There are three items to be setup: 1. RACF 2. WLM definitions 3. httpd.conf file RACF - Access to BPX.WLMSERVER For the IHS server to be able to connect to WLM, the userid the IHS server runs under must be authorised to the RACF resource called BPX.WLMSERVER in the FACILITY class. Only READ access is required WLM definitions To classify IHS requests to some WLM transaction class will require that your WLM environment has suitable definitions. Your z/os environment will already have various WLM service classes and transaction classes for existing workload. You have complete freedom in determining how you want to setup your WLM environment for classifying the IHS requests, and in how simple or detailed you want to make this. You could decide on the very simplest and minimalist approach of just classifying IHS requests to an existing WLM transaction class, though this would mean you would not be able to uniquely identify the IHS processing via RMF WLM reports. The recommended bare minimum to do is to define at least one new WLM transaction class and associated report class, to which all IHS requests would be associated with. However if your IHS server is handling requests for several discrete business areas of your company, you may want to define several WLM transaction classes and associated report classes. The benefit of doing this is that then you can determine how much CPU is being used by each business unit in IHS for chargeback purposes plus also report on and monitor performance of each business unit in IHS. After the next couple of sections about the IHS httpd.conf file and the new WLM directives, we will describe in detail the relationship between WLM setup and the directives. WP WLM classification of requests in Apache HTTP Server on z/os Page 6 of 25

7 1.3.3 IHS httpd.conf file The IHS httpd.conf file is the configuration file that contains numerous lines, called directives, that tell IHS how to act on requests it receives. This IHS module provides new directives that you use to specify what WLM transaction class is to be associated with each request. Again you have complete freedom in how you use these new directives. You can adopt a minimalist approach of mapping all requests to one WLM transaction class. Alternatively you can specify any number of WLM directives to map various requests to any number of WLM transaction classes The new WLM directives for use in the httpd.conf file Our module provides four new directives to be used in the IHS httpd.conf file. The four new directives are: wlmsubsystype wlmcollectionname wlmtranclass wlmdebug To classify requests you need to add these directives to the httpd.conf file of the IHS server. More details on how to use these directives will be explained shortly. For the module to be able to successfully classify requests the values you set on these WLM directives must match to values defined in your WLM settings. You can use any values that suit your environment. The next section describes how these directives are used Relationship between WLM directives and WLM We thought the best way to explain the relationship between the WLM directives in your IHS httpd.conf file and your WLM environment and how you need to set this up would be to explain how we setup our environment when we developed and tested this new IHS module. The following diagram shows from our system how the values we specified for the WLM directives in out IHS httpd.conf file corresponded to values specified in the WLM ISPF panels: WP WLM classification of requests in Apache HTTP Server on z/os Page 7 of 25

8 What the above diagram shows is how the values specified in the WLM directives in the IHS httpd.conf file correspond to values defined in the WLM ISPF panels. On your own z/os system, you could use the same values we used or use whatever values suit your requirements wlmsubsystype As shown in the above diagram the value specified for wlmsubsystype must correspond to a SubSystem Type value defined in the WLM ISPF panels. In our example we used the CB value which is the one designated for WebSphere Application Server as it was already defined on our system. You could use the same on your system or another of your choosing. This directive can only appear once in the httpd.conf file. Keep in mind that a single STC can only have one connection to WLM, and in our code we establish this connection during startup of a child IHS process. There is no point in being able to specify multiple wlmsubsystype directives. If you specify this directive more then once you will get an error message in the proc.errors file similar to that shown below, plus the server will not start. BROWSE /u/edmcar/myihs/logs/proc.errors Line 000 WP WLM classification of requests in Apache HTTP Server on z/os Page 8 of 25

9 Command ===> ********************************* Top of Data **************** Syntax error on line 849 of /u/edmcar/myihs/conf/httpd.conf: wlmsubsystype not allowed here wlmcollectionname As shown in the above diagram the value specified for wlmcollectionname must correspond to the value defined under the Name heading in the Qualifier part of the WLM ISPF panels, with the Type field set to a value of CN. This directive must appear at least once in the httpd.conf file. You can set the value of this directive to NA, which tells the IHS WLM module not to set the WLM Collection name when creating the enclave wlmtranclass As shown in the above diagram the value specified for wlmtranclass must correspond to the value defined under the Name heading in the Qualifier part of the WLM ISPF panels, with the Type field set to a value of TC. This directive must appear at least once in the httpd.conf file wlmdebug Setting the wlmdebug directive to the value on will result in the module writing out various debug messages to the IHS error log. Note this directive can only be specified once in the httpd.conf file. The default is no debug messages are written Guide to coding the WLM directives in the httpd.conf file IHS is based on Apache, and provides great flexibility in how you code the directives in the httpd.conf file. We cannot hope to cover every possible configuration option in IHS, but what we can do is work through the example directives we used in our httpd.conf file when developing this module The default approach map all requests to one WLM transaction class The simplest, and in essence the default approach, is to map all requests to one WLM transaction class. To do this you only need to add these lines at the bottom of your IHS httpd.conf file: # Default WLM Transaction Class wlmsubsystype CB wlmcollectionname IHS wlmtranclass IHSDEFLT wlmdebug on The above directives results in all requests running in a WLM enclave associated with the WLM transaction class of IHSDEFLT. WP WLM classification of requests in Apache HTTP Server on z/os Page 9 of 25

10 Refer back to the diagram in the section titled Relationship between WLM directives and WLM to see how the above values on the directives map to values defined in the WLM panels Mapping two applications to two WLM transaction classes You may want to assign different WLM transaction classes to requests for different applications. We did just this in our setup by adding the following directives: # Default Virtual Host for site <VirtualHost *:9080> <LocationMatch "/wlmsample/appabc/(extra special)/data"> wlmtranclass IHSABCG1 </LocationMatch> <LocationMatch "/wlmsample/appxyz/(extra special)/data"> wlmtranclass IHSXYZG1 </LocationMatch> </VirtualHost> The above directives define a virtual host for port Within that we define two LocationMatch directives, one for requests for application appabc and one for requests for application appxyz. Within each of these LocationMatch directives we then defined wlmtranclass directives with different WLM transaction class names. Refer back to the diagram in the section titled Relationship between WLM directives and WLM to see how the above values on the directives map to values defined in the WLM panels. The result of the above set of directives is that requests for appabc run in WLM enclaves associated with WLM transaction class IHSABCG1, while requests for appxyz run in WLM enclaves associated with WLM transaction class IHSXYZG1. Notice however that we did not code any WlmCollectionName directives. The IHS WLM module requires a valid WLM Collection name to use to create the WLM enclave, so where has it obtained this value? The answer is that by not coding this directive in the above set of directives, the result was that the value coded for the default WlmCollectionName directive, namely IHS was used. It was in essence inherited from the wlmcollectionname directive we coded at the default level Mapping requests for a specific domain to a WLM transaction classes You may want to assign different WLM transaction classes to requests that are for a combination of a specific domain name and application. We did just this in our setup by adding the following directives: <VirtualHost *:9080> ServerName w3.wsc1.itso.com WP WLM classification of requests in Apache HTTP Server on z/os Page 10 of 25

11 <LocationMatch "/wlmsample/appabc"> wlmcollectionname IHSMGT wlmtranclass IHSABCP1 </LocationMatch> wlmcollectionname NA wlmtranclass IHSWSCG1 </VirtualHost> The above directives define a virtual host for port 9080, but by adding the ServerName directive, the effect is that the above set of directives only apply for requests that have w3.wsac1.itso.com in the URL as the domain name. Within that we defined a LocationMatch directive for requests for application appabc. Within the LocationMatch directive we then defined a wlmcollectionname and wlmtranclass directive. We also defined a wlmcollectionname and wlmtransclass directive outside of the LocationMatch directive. Refer back to the diagram in the section titled Relationship between WLM directives and WLM to see how the above values on the directives map to values defined in the WLM panels. The result of the above set of directives is that requests for appabc run in WLM enclaves associated with WLM transaction class IHSABCP1. Because the IHSABCP1 WLM transaction class was defined under the WLM collection name of IHSMGT, we needed to add a corresponding wlmcollectionname directive with that value. For any other requests that are not for application appabc, but have domain name of w3.wsac1.itso.com in the URL, then will run in WLM enclaves associated with WLM transaction class IHSWSCG1. Because the IHSWACG1 WLM transaction class was defined at level 1 in WLM, there is no corresponding WLM collection name. Thus we set the wlmcollectionname directive to NA, which tells the IHS WLM module to not set any WLM Collection Name when creating the enclave Relationship of sample URLs to WLM directives The following diagram shows how different sample URLs we used to test our module mapped to the different WLM directives we specified in our httpd.conf file: WP WLM classification of requests in Apache HTTP Server on z/os Page 11 of 25

12 1.3.8 Monitoring with RMF Having setup our IHS server and WLM environment to classify requests we set up JMeter to run a load test of our URLs. We did this as we wanted to verify that we could view information about the requests via RMF MON III and also obtain WLM reports. A file called modwlm.jmx is supplied with this techdoc if you want to use it to try and run the same URL s we used on your system. Details about how to use JMeter are supplied later in this document RMF MON III After we ran a load test for a few mins we accessed RMF MON III and were able to see information about the five WLM transaction classes used by our sample as shown below: WP WLM classification of requests in Apache HTTP Server on z/os Page 12 of 25

13 WLM Reports We then ran a JCL batch job to produce WLM reports for the five WLM transaction classes. We viewed the job output and found reports for each transaction class. A complete report is supplied with this techdoc in a file called ihs-wlm-report.txt, part of this report is shown below: From this report you can determine for the interval: Information Value CPU consumed average response time second Requests processed 250 requests per second rate 2.06 Percent of general CPU used 0.07 You can then determine the average CPU used per request by calculating: CPU consumed / requests processed / 250 = seconds Testing our module In chapter two of this document we will explain how we set up our module so that if a request started with wlmsample we had the module reply with a simple HTML page that displayed what WLM values had been used to classify the request. For example sending this request: produced this output in the browser: WP WLM classification of requests in Apache HTTP Server on z/os Page 13 of 25

14 1.4 Compiling the IHS WLM module and other related setup In this section we describe how to compile the IHS WLM module and what other changes you need to make to the IHS httpd.conf file Our environment The environment we used was a z/os v1.10 LPAR. The IHS server we used ran as a started task called WEBSRV listening on port Our IHS configuration was located at /u/edmcar/myihs. We used this directory to store the IHS module: /u/edmcar/modwlm. We will use these values when showing examples in the following sections Directory for the module code On our system we created this directory: /u/edmcar/modwlm We stored the source code modwlm.c in this directory. You should create a similar directory in a location suitable for your system Compile the module The module includes the following files which contain WLM related code: WP WLM classification of requests in Apache HTTP Server on z/os Page 14 of 25

15 server.h wlm.h On our z/os LPAR these files were located in the directory /usr/include/sys. We issued this command to add this directory to the _CC_INCDIRS environment variable: export _CC_INCDIRS="/usr/include /usr/lpp/ioclib/include /usr/include/sys" From the /u/edmcar/modwlm directory we issued this command: /u/edmcar/myihs/bin/apxs -c modwlm.c which produced this output: /u/edmcar/myihs/build/libtool --mode=compile cc -Wc,XPLINK,lp64 -Wl,XPLINK,lp6 4 -O3 -U_NO_PROTO -DPTHREAD_ATTR_SETDETACHSTATE_ARG2_ADDR -DPTHREAD_SETS_ERRNO -DPTHREAD_DETACH_ARG1_ADDR -DSIGPROCMASK_SETS_THREAD_MASK -DTCP_NODELAY=1 -I/u/edmcar/myIhs/include -I/u/edmcar/myIhs/include -I/u/edmcar/myIhs/include - Wc,DLL,expo -c -o modwlm.lo modwlm.c && touch modwlm.slo libtoolexe: cc -Wc,DLL,EXPORTALL -Wc,XPLINK,lp64 -Wl,XPLINK,lp64 -O3 -U_NO_PROTO -DPTHREAD_ATTR_SETDETACHSTATE_ARG2_ADDR -DPTHREAD_SETS_ERRNO -DPTHREAD_DETACH_ARG1_ADDR -DSIGPROCMASK_SETS_THREAD_MASK -DTCP_NODELAY=1 -I/u/edmcar/myIhs/include -I/u/edmcar/myIhs/include -I/u/edmcar/myIhs/include -Wc,DLL,expo -c -o modwlm.o modwlm.c WARNING CCN3280./modWlm.c:228 Function argument assignment between types "char*" and "unsigned long long*" is not allowed. WARNING CCN3196./modWlm.c:376 Initialization between types "char*" and "int*" is not allowed. WARNING CCN3280./modWlm.c:380 Function argument assignment between types "const char*" and "int*" is not allowed. WARNING CCN3068./modWlm.c:446 Operation between types "char*" and "const char*" is not allowed. WARNING CCN3068./modWlm.c:447 Operation between types "char*" and "const char*" is not allowed. FSUM3065 The COMPILE step ended with return code 4. libtoolexe: echo timestamp >modwlm.lo /u/edmcar/myihs/build/shlibtool --mode=link cc -Wc,XPLINK,lp64 -Wl,XPLINK,lp64 -O3 -U_NO_PROTO -DPTHREAD_ATTR_SETDETACHSTATE_ARG2_ADDR -DPTHREAD_SETS_ERRNO -DPTHREAD_DETACH_ARG1_ADDR -DSIGPROCMASK_SETS_THREAD_MASK -DTCP_NODELAY=1 -o modwlm.la -rpath /u/edmcar/myihs/modules -module -avoid-version -export-dynamic --coredll=/u/edmcar/myihs/lib/apachecore.dll modwlm.lo libtoolexe: cc -Wl,DLL -o modwlm.so -Wc,XPLINK,lp64 -l,xplink,lp64 WP WLM classification of requests in Apache HTTP Server on z/os Page 15 of 25

16 -O3 -U_NO_PROTO -DPTHREAD_ATTR_SETDETACHSTATE_ARG2_ADDR -DPTHREAD_SETS_ERRNO -DPTHREAD_DETACH_ARG1_ADDR -DSIGPROCMASK_SETS_THREAD_MASK -DTCP_NODELAY=1 modwlm.o /u/edmcar/myihs/lib/apachecore.x Configure IHS server Set up an IHS server on your z/os LPAR if you do not already have one Update NameVirtualHost directive As we wanted to show requests being classified to different WLM transaction classes based on different virtual host names we needed to update the default NameVirtualHost directive from this: to #NameVirtualHost * NameVirtualHost * Add wlm module to IHS configuration To have the IHS server use our module, we searched the httpd.conf file for the following string: #LoadModule deflate_module modules/mod_deflate.so and inserted the following line after it: LoadModule modwlm_module /u/edmcar/modwlm/modwlm.so Debug messages If you enable debug in the module, then you will get trace messages written to the IHS error log. On our system this was located at: /u/edmcar/myihs/logs/error_log. Below is a sample of the messages written. Each message also has a prefix showing the job name of the child IHS STC process and the thread id that the request ran in, though this is not shown here. A file called error_log.txt is supplied with this techdoc showing the complete messages. in modwlm_child_init: ConnectWorkMgr Token allocated: in merge dir: add->wlmtranclass: IHSABCP1 in merge dir: base->wlmtranclass: IHSWSCG1 in merge dir: new->wlmtranclass: IHSABCP1 in merge dir: add->wlmtranclass: IHSABCP1 in merge dir: base->wlmtranclass: IHSWSCG1 in merge dir: new->wlmtranclass: IHSABCP1 hook fixup: wlm_conntoken value: hook fixup: handling request: /wlmsample/appabc/specialmanagementlink hook fixup: start time: Wed Jan 12 05:25: WP WLM classification of requests in Apache HTTP Server on z/os Page 16 of 25

17 hook fixup: wlm subsystem value: CB hook fixup: wlm collection name value: IHSMGT hook fixup: wlm tran class value: IHSABCP1 hook fixup: wlm ConnToken:..: hook fixup: server_classify_create create ok at addr..: hook fixup: value of _SERVER_CLASSIFY_CONNTKN used: hook fixup: _SERVER_CLASSIFY_TRANSACTION_CLASS set to: IHSABCP1 hook fixup: _SERVER_CLASSIFY_COLLECTION set to: IHSMGT hook fixup: CreateWorkUnit succeeded: wlmetok_w1=76, wlmetok_w2=63695, hook fixup: JoinWorkUnit RC:..: 0 end_of_request: handling request: /wlmsample/appabc/specialmanagementlink end_of_request: wlmtokenptr info: wlmetok_w1=76, wlmetok_w2=63695, end_of_request: wlm LeaveWorkUnit RC:..: 0 end_of_request: wlm DeleteWorkUnit RC:..: 0 in modwlm_child_exit: DisconnectServer RC: 0 in modwlm_child_exit: DisconnectServer RC: JMeter JMeter is an open source tool that can be used to generate load onto any target server. Load generation scripts can be graphically built in JMeter and then saved to a file, typically with a jmx suffix. Download JMeter from the Apache web site for JMeter. The version used in association with this tech doc was downloaded from: Unzip the zip file to a directory, there is no product installer to run How to run JMeter From a DOS prompt, change to the directory where JMeter is located and then to the bin sub-directory. Type in jmeter and press Enter and the initial JMeter window similar to that shown below will display: WP WLM classification of requests in Apache HTTP Server on z/os Page 17 of 25

18 Then select File -> Open and use the file dialog box to locate the supplied jmx file. You will need to modify the HTTP Request defaults entries to reflect the TCPIP address and domain names on your system WLM API Error codes The sample module issues a number of WLM API s. If you try this module on your own system you may get unexpected errors. To help determine the cause of the error you can set the wlmdebug directive to on to have the module write trace messages. If any of the WLM APIs fail, then in the trace messages you may well see an error message similar to this: EDC5170I An error was encountered with WLM. (errno2=0x033a0857) The useful part of this message is the last four digits of the errno2 code, in the case the 0857 value, which is a reason code. To find out what this means, you need to look up the reason code in the z/os manuals. The problem is that the code uses C WLM APIs, and the z/os documentation only provides reason codes for the Assembler Macro s. You thus need to know which Assembler Macros corresponds to the C WLM APIs used in the module. Fortunately the article titled C Language Interfaces for Workload Management Services at the following link shows which Assembler APIs Macros correspond to the C WLM APIs: topic=/com.ibm.zos.r11.ieaw200/cwrp.htm In this case the above error message occurred when the JoinWorkUnit API was used. The above link showed that this API maps to the IWMEJOIN macro. The above link has a link to a description of this macro, from where you can find this link to the reason codes for the IWMEJOIN macro: topic=/com.ibm.zos.r11.ieaw200/iea2w2a0236.htm The 0857 code is explained on this link as follows: WP WLM classification of requests in Apache HTTP Server on z/os Page 18 of 25

19 Another way to find the error reason codes is to download the manual z/os V1R11.0 MVS Programming Workload Management Services SA from this link: You can then just do a global search for the 4 digit reason code. WP WLM classification of requests in Apache HTTP Server on z/os Page 19 of 25

20 2 Details on the modwlm sample module This section provides more details about how the modwlm sample module available with this article performs the task of classifying requests to WLM. 2.1 Details how the WLM sample module classifies requests to WLM Standard Apache module coding In our module we have the following code which is used to provide the glue between the IBM HTTP Server and the custom module, so that the IBM HTTP Server can find out what functions in the module can be invoked and when to invoke them. module AP_MODULE_DECLARE_DATA modwlm_module = { STANDARD20_MODULE_STUFF, wlmtranclass_create_dir_config, /* per-dir config creator */ merge_expires_dir_configs, NULL, NULL, wlmtranclass_cmds, /* Function to specify our directives */ }; modwlm_register_hooks, /* callback for registering hooks */ The line with wlmtranclass_create_dir_config informs IHS that this function is to be called when IHS is initial stages of starting up. This function is used to pre-initialize default variables for directives that this module uses. The line with merge_expires_dir_configs informs IHS that this function is to be called when IHS starts to process a request. This function is used to determine what directive value is to be used. The line with wlmtranclass_cmds informs IHS that this function is to be called when IHS is initial stage of starting up. This function is used to tell IHS what directives in the httpd.conf file that this module uses and the corresponding function within the module that IHS is to call when IHS detects one of these directives. This module uses four directives: 1. wlmsubsystype 2. wlmcollectionname 3. wlmtranclass 4. wlmdebug The following line of code shows that for the wlmtranclass directive, IHS is to invoke the wlmstoretranclass function: AP_INIT_TAKE1("wlmTranClass", wlmstoretranclass, NULL, OR_ALL,"WLM Transaction Class"), WP WLM classification of requests in Apache HTTP Server on z/os Page 20 of 25

21 These functions save the specified value in a structure in the module. The line with modwlm_register_hooks informs IHS that this function is to be called when IHS is initial stages of starting up. This function is used to register function names for various Apache hooks. 2.2 Hooks used in this module Four standard Apache hooks are used in our module. The hooks are registered by these lines of code: ap_hook_post_read_request(modwlm_post_read_request, NULL, NULL, APR_HOOK_MIDDLE); ap_hook_child_init(modwlm_child_init, NULL, NULL, APR_HOOK_MIDDLE); ap_hook_fixups(modwlm_fixup, NULL, NULL, APR_HOOK_LAST); ap_hook_handler(modwlm_handler, NULL, NULL, APR_HOOK_LAST); ap_hook_child_init This hook in implemented by the function modwlm_child_init. This hook is called when the parent IHS process starts a child process. It is used to call the WLM APIs to create a connection to WLM ap_hook_post_read_request This hook in implemented by the function modwlm_post_read_request This hook is called after IHS has completed reading in a request but before it starts actioning the request. In this function we register a function called end_of_request to be invoked by IHS when the IHS has completed the request ap_hook_fixups This hook in implemented by the function modwlm_fixup. This hook is called by IHS after the post_read_request hook. It is used to create a WLM enclave for this request ap_hook_handler This hook in implemented by the function modwlm_handler. This hook is called by IHS for each request and can be used to process the request. In our module we use this hook to trap for specific requests and send back a simple HTML page showing information about what WLM related values have been used for the request. 2.3 modwlm processing The following diagram provides an overview of how IHS, the sample WLM module and the WLM API s work together to classify requests: WP WLM classification of requests in Apache HTTP Server on z/os Page 21 of 25

22 IHS main process Process WLM related directives Start child processes 1 to n 1 2 IHS child process 1 3 IHS child process n 3 Hook: child_init Receive request Create connection to WLM WLM directive processing Hook: post_read_request 7 - register end_of_request call back Hook: fixup Create a Classify Area - set fields Create work unit Join work unit 6 Hook: child_init Receive request Create connection to WLM WLM directive processing Hook: post_read_request 7 - register end_of_request call back Hook: fixup Create a Classify Area - set fields Create work unit Join work unit 6 Request processing 9 Request processing 9 Call back: end_of_request 10 Call back: end_of_request 10 Leave work unit Leave work unit Delete work unit Delete work unit Send reply 11 Send reply 11 The sequence of events is explained in the following sub-sections Process WLM related directives When IHS is started, a single STC is created and during this startup our module is loaded. The WLM directives in the httpd.conf file are processed by our module Start child processes 1 to n Once IHS has completed startup it starts 1 to n children processes, each one a STC Child process 1 Each of these child processes is a STC and it is these child processes that will process requests received by IHS Hook: child_init During the initialization of the child process the child_init hook is called. This hook is used to issue WLM APIs to connect to WLM. This is nothing like a TCPIP connection, it more akin to the child process STC registering to WLM. In the modwlm_child_init function we use this line to register the child process to WLM: WP WLM classification of requests in Apache HTTP Server on z/os Page 22 of 25

23 wlm_myconntoken=connectworkmgr(wlm_subsystype, jobname); The ConnectWorkMgr WLM API returns a token value which is stored in a global variable in the module. Each child process runs as a STC, and it is a WLM rule that each STC can only have one WLM connection. Note that each child process will issue the above WLM API call and thus each child process has its own WLM connection token Receive request Once the child process has completed startup it is then able to receive requests WLM Directive processing For each request received IHS performs some processing related to the WLM directives. If IHS determines that the request does not match any VirtualHost or Location Match directives then this means that the default value of the wlmtranclass directive applies to this request and that no additional processing of directives is required. If the request does match a VirtualHost or LocationMatch directive, and these contain wlmtranclass directives, then IHS invokes the merge_expires_dir_configs function from our module. The purpose of the merge_expires_dir_configs function is to determine what wlmtranclass directive will be used. The value used depends on how you code this function. In our case we wanted to use the wlmtranclass directive that matches the request as per the way we have coded our directives. This is achieved by this and similar lines: new->wlmtranclass = (add->wlmtranclass!= NULL)? add->wlmtranclass : base->wlmtranclass; Hook: post_read_request The post_read_request hook is then invoked by IHS. In this hook we register that the end_of_request function is to be called when IHS has finished processing the request Hook: fixups IHS will then invoke the fixups hook. We use this hook to issue WLM APIs to create an enclave for our request. In this hook we use this line to obtain what WLM related directives apply to this request: cfg = (wlmtranclasstable *) ap_get_module_config(r->per_dir_config, &modwlm_module); Next this code creates a WLM server classify data structure: sct_ptr = server_classify_create(); We then call the server_classify WLM API to set three fields in the server classify data structure using these lines of code: rc= server_classify(sct_ptr, WP WLM classification of requests in Apache HTTP Server on z/os Page 23 of 25

24 rc= server_classify(sct_ptr, rc= server_classify(sct_ptr, _SERVER_CLASSIFY_CONNTKN, (char*)&(wlm_conntoken)); _SERVER_CLASSIFY_TRANSACTION_CLASS, cfg->wlmtranclass); _SERVER_CLASSIFY_COLLECTION, cfg->wlmcollectionname); We then create a WLM enclave by using this code: rc=createworkunit(&(md->wlmtoken_ptr), sct_ptr, &stcktime, wlmworkunitfuncname); We then join the current request being processed to this WLM enclave with this code: rc=joinworkunit(&(md->wlmtoken_ptr)); After completing this last WLM API call the result is that we have classified the request to a WLM transaction class and created an enclave Request processing IHS now processes the request as per directives in the httpd.conf file. In our code we have also registered the hook called ap_hook_handler to a function called modwlm_handler. In this hook we use an if test so that our hook only handles requests to help demonstrate this module. When the if test matches, the code generates HTML to return to the caller to show information about how the request has been classified such as WLM transaction class call back: end_of_request Once IHS has completed processing of the request but before it sends back the reply, it will call the end_of_request function in our module. The code then uses this line of code to leave the WLM enclave: rc=leaveworkunit(&(mydata->wlmtoken_ptr)); and this line of code to delete the WLM work unit that was created for this request: rc=deleteworkunit(&(mydata->wlmtoken_ptr)); send reply IHS then sends the rely for this request back to the caller modwlm_child_exit Not shown in the diagram is the function called modwlm_child_exit. This function is registered to be called during termination of a child IHS process by this line in the WP WLM classification of requests in Apache HTTP Server on z/os Page 24 of 25

25 modwlm_child_init function: apr_pool_cleanup_register(ppool, pserver, modwlm_child_exit, modwlm_child_exit); When a child IHS process terminates, the modwlm_child_exit function is called and we use this line to disconnect the STC from WLM, in effect deregistering it. rc=disconnectserver(&(wlm_conntoken)); 2.4 Document Change History January 26, 2011 Original Document --- End of Document --- WP WLM classification of requests in Apache HTTP Server on z/os Page 25 of 25