Use Azure Local storage for MQ .NET client tracing - ibm-messaging/mq-azure GitHub Wiki

Starting MQ v8.0.0.2, MQ .NET client assembly can be bundled and installed with your application on production machines. There is no requirement of installing full MQ client on production systems. In such environment MQ .NET client supports only the managed mode transport. The other two, ‘bindings’ and ‘unmanaged’ mode transports are not supported as these require native libraries which are available only in a full MQ client installation. While packaging an application, only amqmdnet.dll assembly will need to be included in the package. No other assemblies are required.

MQ .NET applications can be both desktop as well as web (ASP .NET) applications running on Azure PaaS environments.

Trace and error log files help in analyzing problems either in application or IBM MQ .NET client. In an environment where full IBM MQ Client is installed, strmqtrc and endmqtrc commands can be used to collect traces. However in environment where just the IBM MQ .NET client (i.e. amqmdnet.dll) assembly is deployed with the application, tracing is controlled using a configuration file called mqtrace.config. The path where mqtrace.config file is located can be specified using MQTRACECONFIGFILEPATH property in the application configuration (app.config) file. If this property is not specified, then the mqtrace.config file can be placed in the applications directory.

Sample app.config property showing path for mqtrace.config file.

<appSettings>
    <add key="MQTRACECONFIGFILEPATH" value="C:\MyApp"/>
</appSettings>

The mqtrace.config file is a simple Xml file that describes how tracing is controlled. An example is here:

<?xml version="1.0" encoding="utf-8"?>
  <traceSettings>
    <MQTRACELEVEL>2</MQTRACELEVEL>
    <MQTRACEPATH>C:\MyApp\MQTrace\</MQTRACEPATH>
    <MQERRORPATH>C:\MyApp\MQTrace\</MQERRORPATH>
  </traceSettings>

The value of MQTRACELEVEL controls enabling/disabling of trace. A value of 2 enables the trace and 0 disables it. The other two, MQTRACEPATH and MQERRORPATH point to the path where MQ .NET trace and error logs will be created.

While it is easy to configure and enable/disable tracing on desktop applications, it’s tricky on Azure PaaS environment where WebRole and WorkRole applications are run. Unlike desktop applications, Azure WebRole applications will have a very restricted access to file system. They will have access to folder and sub-folders where the application is deployed. They may not have access to C or D drive of the machine. Also the applications will not know the folder name or drive on which they will be deployed on Azure. Hence it is not possible to configure mqtrace.config properties as is done for desktop applications. So how do we capture MQ trace in a WebRole or WorkerRole applications?

Azure Local Storage comes in handy here.

An Azure local storage resource is a reserved directory in the file system of the virtual machine in which an instance of a role is running. Code running in the instance can access the local storage resource when it needs to write to or read from a file. For example, a local storage resource can be used to cache data that may need to be accessed again while the service is running in Windows Azure. A local storage resource is declared in the service definition file. You can declare any number of local storage resources for a role. Each local storage resource is reserved for every instance of that role. The minimum amount of disk space that you can allocate for a local storage resource is 1 MB. The maximum amount that you can allocate for any given local resource depends on the size of the virtual machine that is specified for the role. Each virtual machine size has a corresponding total storage allocation, and the total space allocated for all local storage resources declared for a role cannot exceed the maximum size allotted for that virtual machine size. More on Azure Local Storage here.

This article describes how to configure a MQ .NET WebRole application to write trace files to an Azure Local storage.

###Define Azure Local Storage: The first step is to declare a local storage through the service definition (ServiceDefinition.csdef) file of your project. Add LocalResource and LocalStorage section for WebRole as described below. The snippet below creates local storage called “MQTrace” with a maximum size of 1000 megabytes in C drive.

<WebRole name="MyMQWebRole" vmsize="Small">
  <Runtime executionContext ="elevated" />
    <LocalResources>
      <LocalStorage name="MQTrace" cleanOnRoleRecycle="false" sizeInMB="1000" />
    </LocalResources>

The local storage gets created under the C:\Resource\Directory folder with cloud service deployment id, for example:

C:\Resources\Directory\<deployment id of cloud service>.<web role name>.<storage name>\ folder. 

For example if your deployment id is 7711223344abcd334434533235666544 then the local storage will be created as:

C:\Resources\Directory\7711223344abcd334434533235666544.MyMQWebRole.MQTrace

You must also note that the web application must run in an elevated context to access file system. To run an application in elevated context, add the following property for the application in ServiceDefinition.csdef file.

<Runtime executionContext ="elevated" />

The second step is to create a batch file to copy mqtrace.config file to local storage we created above. Create a batch file with below contents and add the file into your project. Make sure to set the “Copy to Output Directory” property to either “Copy if newer” or “Copy always”.

REM   Copy the mqtrace.config file
copy mqtrace.config %PathToStartupStorage%\mqtrace.config
REM   Exit the batch file with ERRORLEVEL 0.
EXIT /b 0

The next step is to add a start-up task in ServiceDefinition.csdef file as shown below. During web application start, this task gets executed. As part of the start-up task we execute the batch file we created above. The batch file copies mqtrace.config from application directory to local storage.

<Startup>
  <Task commandLine="copytrccfg.cmd" executionContext="limited" taskType="simple">
    <Environment>
      <Variable name="PathToStartupStorage">
        <RoleInstanceValue xpath="/RoleEnvironment/CurrentInstance/LocalResources/LocalResource[@name='MQTrace']/@path" />
      </Variable>
    </Environment>
  </Task>
</Startup>

The fourth step is to create mqtrace.config file and add it to project. Add the following contents to mqtrace.config. Provide the path to local storage we created above.

<?xml version="1.0" encoding="utf-8"?>
  <traceSettings>
     <MQTRACELEVEL>2</MQTRACELEVEL>    
     <MQTRACEPATH>C:\Resources\Directory\7711223344abcd334434533235666544.MyMQWebRole.MQTrace\</MQTRACEPATH>
     <MQERRORPATH>C:\Resources\Directory\7711223344abcd334434533235666544.MyMQWebRole.MQTrace\</MQERRORPATH>
  </traceSettings>

Ensure that for this file also the “Copy to Output Directory” property is set to either “Copy if newer” or “Copy always”.

Next step is to compile your application and publish. During deployment, local storage will be created and the mqtrace.config file will be copied to local storage. Since in the above sample, MQTRACELEVEL property value has been set to 2, tracing will start immediately. You can now log on to WebRole’s virtual machine instance and change the MQTRACELEVEL property to turn off/on tracing.