The fourth and, for now, final topic of the black box series brings us to Perl. For people interested in the first part, generated code, please click here, for the second part, Python, please click here and for the third part, VBScript, please click here.

Perl was the first of the ADK wrappers created for the series, but due to time constraints I didn’t manage to clean it up for distribution until now. Perl is used for many different purposes, ranging from web services to batch jobs. If you want to get insight into which methods are called, how long they take, the argument values, how the requests span over several tiers and more, you need to instrument the Perl application using the native ADK. The solution described below is very similar to the Python and VBScript implementations, where a piece of Perl code is communicating to the Dynatrace AppMon native libraries.

Everyone who has followed the previous posts of the series will recognize the below example code as I’ve tried to keep the code similar between the different languages. The code below is the complete application and while it isn’t doing much, it will be able to show how to start the agent, how to create new PurePaths, capture function timings, arguments and more.

The handleRequest subroutine is the entry point of the application and it prints out whatever argument you pass to it. It could be visualized as a web request handler, which is executed once with every web request. The handleRequest function calls the executeQuery function three times with different arguments, simulating a function executing database queries.

If we execute the above application, we get the following result:

Handling request index.htm
Executing query SELECT * FROM my_tbl WHERE id=0
Executing query SELECT * FROM my_tbl WHERE id=1
Executing query SELECT * FROM my_tbl WHERE id=2

To communicate with the native ADK, the wrapper module uses a Perl functionality called XS (eXternal Subroutine). All of the code required to call the native ADK, as well as the sample application, can be downloaded from here.

The first thing we need to do is include the wrapper using use Dynatrace;
Once the wrapper is included it is time to initialize the agent. The call required to do that is Dynatrace::init(); The initialization only needs to be executed once per process, so normally you would call that during the startup of the process. The init function will set up the connection to the AppMon collector and start monitoring the process. If you want to change the default agent name, collector address or path to the agent library, the subroutines setAgentLibrary, setAgentName and/or setServer can be called before the initialize. Just like in the Python wrapper there is no need to call the uninitialize when the application is shutting down, that is taken care of by using the END subroutine.

Once the agent is injected we will also need to add instrumentation into the code to, for example, start PurePaths and capture timings. The three calls used for this is Dynatrace::enter, Dynatrace::start_purepath and Dynatrace::leave.

The start_purepath and enter subroutines require one argument, an array with the arguments to capture. It’s easiest to pass in @_. The name of the subroutine, line number and file name will be captured automatically.

This is how the application looks like after adding the required lines:

By executing this application we receive the following PurePath in AppMon.

As you can see the instrumentation has captured the function names, arguments and the CPU/IO breakdown. By looking at the details of the top node we can see that it also recorded the line number and full path to the file.

Just like the Python implementation one of the possible hurdles when instrumenting a Perl application is forking. The native ADK is added into each process, so if your code spawns a new process for each and every request, you might want to look into letting each process handle at least a few thousand requests before terminating. The ADK does start up very quickly, but it is not recommended that the overhead of starting the agent is part of every single request.

The code can be downloaded from here. If you want to change the code, implement additional ADK functions, or build it for some other reason, you can rebuild the wrapper using the following commands:
perl Makefile.PL
make install

That concludes the “Inside the Black Box” series for now. I hope you enjoyed reading about how to extend your monitoring footprint, and how Dynatrace expert services have helped customers with special requests.

Break open the black box and get in control of your applications, even if they are created in Perl!