Debugging your Wowza Module from Eclipse

When you are developing a custom Wowza Streaming EngineĀ® module, you might want to be able to debug your code using Eclipse's feature rich debugger features. This tutorial shows you how to modify the Wowza startup script to enable debugging in the JVM and how to attach the Eclipse's debugger to Wowza. (Did you aready set up your environment to start Wowza module development?)

Java debugging works by first switching the feature on in the JVM, then enabling one of debugger attachment interfaces and finally attaching the debugger to that interface. I'll show you how to do this in this case.

Enabling debug in the JVM under Wowza

Find and edit the Wowza startup script, on Windows this is called startup.bat. You'll need to find the line where the JVM is effectively launched, and edit according to the below snippet:

This is the original line:

%_EXESERVER% "%_EXECJAVA%" %WMSTUNE_OPTS% %JMXOPTIONS% -Dcom.wowza.wms.runmode="%runmode%" -Dcom.wowza.wms.native.base="win" -Dcom.wowza.wms.ConfigURL="%WMSCONFIG_URL%" -cp %CLASSPATH% com.wowza.wms.bootstrap.Bootstrap start 

Change this by adding the -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044 parameters:

%_EXESERVER% "%_EXECJAVA%" %WMSTUNE_OPTS% %JMXOPTIONS% -Dcom.wowza.wms.runmode="%runmode%" -Dcom.wowza.wms.native.base="win" -Dcom.wowza.wms.ConfigURL="%WMSCONFIG_URL%" -cp %CLASSPATH% -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044 com.wowza.wms.bootstrap.Bootstrap start

-Xdebug switches debug mode on in the JVM, the other arguments set the debugger as a server, which won't suspend the JVM on startup, but which is going to be listening on port 1044 for incoming debuggers.

Now start your Wowza server with this, and you should see this in the logs:

Listening for transport dt_socket at address: 1044
Configure logging: file:///w:/wowza-4.0.3/conf/
INFO server server-start Wowza Streaming Engine 4 Developer Edition (Expires: dec. 24, 2014) 4.0.3 build10989 -
INFO server comment - Server License Key: EDEV4-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Create a Debug configuration in Eclipse

Right-click on the HelloWowza project in the Package Explorer view and select Debug As.. > Debug Configurations..

Debug Wowza Module

On the opened dialog, create a new "Remote Java Application" type debug configuration, by choosing this from the lefthandside list and click on the small icon with a blank sheet and a small plus sign. The Connection Type should be "Standard (Socket Attach)" and Host should be "localhost" and port should be 1044. (Actually you can remote debug your remote Wowza server too, if you like, not only localhost). Click "Debug" when you're done.

Debug Wowza Configuration

Navigate to the "Debug Perspective", unless it opened up automatically, when the debugger attached successfully.

Debug Perspective

Now you should see that the Eclipse debugger is attached to the JVM which runs Wowza Streaming Engine. You should see the threads inside all running.

Debugging Wowza Module

Now insert a breakpoing into any code line by double-clicking on the left margin. In this case I inserted one on line 26, which is in onAppStart. I chose this, as when I start pushing my live stream from Flash Media Live Encoder, I know that my application will be started automatically by Wowza and so the debugger should stop the show at my breakpoint. I started the stream and the magic happened, as you can see on the above screenshot, the debugging just works.. :-)

From this point, you can leverage conditonal breakpoints or anything that you like to develop your custom Wowza module. Read this if you are interested in setting up Eclipse for Wowza module development.


Hi i'm trying to use your wranch
but it give the following error

MESSAGE: Connection refused

STACKTRACE: Connection refused
at Method)
at com.mysql.jdbc.StandardSocketFactory.connect(
at com.mysql.jdbc.MysqlIO.(
at com.mysql.jdbc.Connection.createNewIO(
at com.mysql.jdbc.Connection.(
at com.mysql.jdbc.NonRegisteringDriver.connect(
at org.apache.tomcat.jdbc.pool.PooledConnection.connectUsingDriver(

please advice me to sort this out

Hi Lavan, I checked your stacktrace and it looks like Wrench is trying to connect to the database to perform some SQL queries, but your database refuses the connection. So on Wrench/config side things are good so far, you need to verify if the user you have for Wrench is allowed to connect from Wowza's host, or if the password is correct, or if there is any network blocking / firewall issue. Reach out to me via email if you need more help. Regards!

when i try to debug the hello wowza module the this gives error that "Launching wowza encountered a problem.
Failed to connect Remote VM.Connection refused"

Hi, do you see the "Listening for transport dt_socket at address: 1044" message in the logs when Wowza boots?

I am having the same issue as Ajay Kumar. I would like to ask if that socket address is just for your case or it is a default value.If it must be changed please note it.
Thank your

Hi karim, you can pick any free port, I just happened to use that one.

Write new comment