Friday, January 10, 2014

Narayana Transaction Analyser 1.0.0.Alpha1

In a previous post I introduced the Narayana Transaction Analyser (NTA). In that post I focused on the high-level goals of the project and provided some insight into where we hope to take this tooling. In this post I will focus on what features we have today in the 1.0.0.Alpha1 release and how to get started. I'll also close with an overview of what we hope to add in the coming releases.

Overview of Features in 1.0.0.Alpha1

The main set of features in this release are as follows:
  • A simple getting started experience. Drop the .ear file into WildFly or EAP 6.2.0's deployments directory and click "start" in the Transaction Analyser's console, to begin analysis.
  • Detailed information on JTA transactions. This includes the outcome of the transaction; which resources were enlisted and how they behaved.
  • Demonstrator application. You may want to try out this tooling, but you don't currently have a misbehaving application to try it with. This demonstrator allows you to trigger various successful and unsuccessful transaction scenarios, on-demand.

Getting Started

Currently NTA supports WildFly 8.0.0.CR1 and EAP 6.2.0 onwards. To install and enable NTA do the following:

  1. Download NTA from here.
  2. Copy the nta-full.ear file to $JBOSS_HOME/standalone/deployments/
  3. Start the application server, if not already started.
  4. Visit the console here: http://localhost:8080/nta
  5. Click start in the top-right of the console to enable analysis.

If you want to simulate some failing transactions, simply deploy our demo application and trigger some scenarios:
  1. Download the demo.war from here.
  2. Copy the demo.war file to $JBOSS_HOME/standalone/deployments/
  3. Visit the demo application here: http://localhost:8080/txdemo
  4. You will see a list of four scenarios. Click on invoke for the scenario of interest.
  5. Switch to the NTA console and observe the details of the transaction.
  6. Click on the transaction ID link to view more details of the transaction.

Example detecting a timeout

In this section I'll show how a timed-out transaction can be detected. I'll also use this as an opportunity to highlight some of the additional information that can be viewed with the tool.

Visit the console and click 'start' to begin analysis.

Open the demo application and  click on "Invoke" for the "2) Transaction Timeout" scenario. After two seconds, an alert will pop-up displaying the (failed) outcome of the transaction. 

Now switch back to the NTA console. You will see a single transaction listed. Notice that the status is 'TIMEOUT' and that the duration was a little over 1 second. This is understandable as the scenario set the transaction timeout to 1 second, whilst the business logic took 2 seconds to complete before attempting to commit the transaction.

Clicking on the TransactionID of the timed-out transaction takes you to a details page. Here we can see:

1) Transaction Information. This area provides high-level details about the transaction, such as the outcome (timeout, in this case), details of the duration and start/stop time as well as a note on wether it was distributed.

2) Enlisted Participants. This area lists information on all the participants enlisted in the transaction and how they behaved. In this example, the transaction was timed-out before the two phase protocol was begun. Therefore, the participants were never asked to prepare. The console reports the Vote as UNKNOWN. This text is a bit misleading and will be improved (see: NTA-39).

3) Event Timeline. This area provides a list of interesting events that occurred during the transaction. In this example we can see when the transaction was begun and then what participants were enlisted. The ABORT event occurs in response to the transaction timeout. This will be improved to make it clearer that the transaction was aborted here due to timeout (see: NTA-40).

Clicking on the other scenarios and observing the outcome in NTA is left as an exercise to the reader.

Upcoming Features

We are community-driven in prioritising features, so please provide feedback on the Narayana forums after you've tried the tool. The current set of features planned for the next few releases are as follows:

1) Distributed Transaction support. Alex Creasy (the intern who developed the prototype) has implemented support for analysing distributed (JTS) transactions. With the 1.0.0.Alpha1 release manual setup is required. In the Alpha2 release we hope to polish this process making it a lot simpler to use.

2) Plugin support. Alex also implemented support for simple plugins that detect common transactional issues. This feature requires a little polish and is currently un-documented. We hope to resolve this in the Alpha2 or Alpha3 release.

3) Closer integration with the WildFly and JBoss ecosystem. Currently NTA is a standalone tool. Over the coming releases we aim to align and integrate this tooling more closely with the existing tooling provided by WildFly and JBoss EAP. We are currently seeking community input on how best to achieve this.

4) Import/export of data. This allows the gathered data to be transferred to a third party who's helping to diagnose an issue. For example, when requesting support via a forum post or support ticket. This is currently targeted for the Alpha2 or Alpha3 release.

We also have lots of other features planned. For a more complete list (and up-to-date roadmap), visit the NTA Jira instance.

Getting Involved

What to do if NTA doesn't display what you expect

NTA is currently Alpha quality, so it's possible that it won't always display the correct information. If you suspect this to be the case it would be great to hear from you, so that we can fix the issue. In this case, you should create a post on the Narayana forum. It would be great if you could provide a screen-shot of what NTA is displaying, as well as the server log file (if it's not too large). NTA parses this log file, so we should be able to compare this to the screen-shot when figuring out the problem. We can also use NTA to parse this log file making it easy to reproduce your issue.

Introducing the "Narayana Transaction Analyser"

In this post I'll interview Paul Robinson, who is the project lead of the new "Narayana Tranasaction Analyser" project. In the interview we'll aim to provide an introduction to the tool and help you get a feel for how it could help you as an application developer.

Tom: Can you provide some background for the tool?

Paul: Back when I was a JBoss Transactions consultant, my clients and I often found it difficult to discover the cause of failing transactions. Since then I've felt that it would be great to have tooling that tells me everything about all the transactions ran in my application server. With this information I would be able to see exactly why my transactions are not behaving as I would like. I could also use this information to understand more about my architecture, by displaying a high level topology of servers and transactional resources involved in my transaction.

Last summer we hired Alex Creasy as an Intern to work on a prototype of this tool. From his excellent work the "Narayana Transaction Analyser" was born. Since Alex completed his prototype, we have promoted it to a project under the 'Narayana' umbrella and produced our first release. Today, I'd like to focus on providing an overview of what we aim to achieve with this tool. I'll follow up with a subsequent post, focusing on what features we have in the recent 1.0.0.Alpha1 release and how to get started.

Tom: What are the goals of this tool?

Paul: The main requirement of the Transaction Analyser is to make it significantly simpler to diagnose transaction-related problems. As well as providing detailed information on every transaction, the tool can also be loaded with a suite of plugins that diagnose common issues. It should also be possible to export this data. This exported data can then be uploaded alongside a support ticket or forum posting, giving the person providing the assistance more data to work with. 

Tom: When would I use this tool?

Paul: In general, the tool should be enabled when you are experiencing some transaction-related issues and you require more information. You need to be mindful of when this tool is enabled as gathering this data does impose an overhead on the system. Think of this tool as being similar to a performance profiler, like JProfiler. You just enable this tool when you detect an issue that requires more investigation.

Tom: Sounds interesting, can you give me some examples of what I could use this for?

Paul: The following list should give you a feel for what type of issues the tool can investigate.

Many of your transactions are rolling back, and you don't know why.

This often occurs when a timeout is triggered due to business logic taking too long to complete. The tool lists all transactions that were rolled back due to timeout. The tool may also be able to provide details on what the business logic was doing, making it easier to track down the root cause. For example, any JPA queries ran within the transaction could be displayed.

You have a distributed transaction crossing many servers, and you're finding it difficult to correlate the many log files. 

The tool is distributed-transaction aware and groups together all the data from a single transaction that spans multiple servers. Currently the focus is on supporting JTS, but gathering data on Web Service and REST transactions is possible.

You have a heuristic transaction, but you don't know which resource misbehaved. 

The tool shows all resources enlisted in the transaction and provides details on how they behaved in the transaction. It is relatively simple to see which resource didn't behave as instructed.

A transaction appears to have 'hung', but you don't know why. 

This often occurs due to deadlock when trying to obtain a lock on some resource. This is the type of issue that often requires expert knowledge to track down and requires a good understanding of the log output. However, this process can be automated by this tool; notifying the user when the problem is detected. As well as notifying the user, the tool can also link to some useful documentation explaining how to fix the problem.

Someone is assisting you with an issue and they would like some more details. 

Providing this person with a dump from this tool will provide them with a wealth of information, hopefully making it easier for them to assist you. After fixing the problem, a plugin could be developed so that the issue is automatically detected whenever anyone else experiences that issue in the future.

Tom: How do I try it?

Paul: We recently released NTA 1.0.0.Alpha1. In this blog post I walk through the current feature set and how to get the tool up-and-running.

Thursday, October 17, 2013

The Narayana project visualized by Gource

We just ran the excellent Gource tool over the Narayana repo and generated this rather neat visualization of our contributions over the last few years.
Software projects are displayed by Gource as an animated tree with the root directory of the project at its centre. Directories appear as branches with files as leaves. Developers can be seen working on the tree at the times they contributed to the project.

If you want to see your avatar on the video next time we generate one, please do consider adding a contribution over here:

Tuesday, October 1, 2013

HPTS 2013

I was at HPTS 2013 a week or so ago. It's probably the one conference that I always try to get to no matter what. I've included my presentation here but you should check out the HPTS site to see all of the others. The site isn't complete yet, as some presenters haven't sent in their decks but we'll be updating it as they come in.

Tuesday, September 17, 2013

Narayana is now JTA 1.2 Compliant

I'm very proud to announce that with Narayana 5.0.0.M3 we are now JTA 1.2 compliant! What's more, with the release of JCA 1.7 in WildFly 8.0.0.Beta1 (WFLY-510), the new application server features are now available.

I'd like to say a big "thank you" to the community members who provided feedback during the design and implementation of this specification. Like most of our larger features, this was discussed over at the Narayana developer forums, giving the community the opportunity to shape the development of these features.

So what's new in JTA 1.2?

JTA 1.2 is considered a 'maintenance release', so the change list is quite small. However, that's not to say that the changes aren't exciting. Here's an overview of the three improvements:

@Transactional. This is the headline feature and brings the ability to place transaction annotations on any CDI managed bean. Prior to this feature, you had to make your class an EJB in order to use transactional annotations.
@TransactionScoped. This feature allows you to associate CDI beans with the scope of a transaction.
The third change clarifies when the container should call 'delistResource' on the transactional resource. This is a minor change and is of less interest to an application developer, so I'm not going to discuss it further here.

Tell me more about @Transactional and @TransactionScoped

The remainder of this post will tell you what you need to know about these new features and provide some examples, showing how they can be used.


This new annotation provides an alternative to javax.ejb.TransactionAttribute that can be placed on CDI managed bean classes and its methods. Prior to this feature, many developers were using EJBs just so that they could use declarative transactions. Now you can make an architectural decision of wether EJB or CDI is the right approach for your application, knowing that you will be able to use declarative transactions with either approach. The remainder of this section will show an example using @Transactional and highlight the differences between @Transactional and the EJB @TransactionAttribute.

public class MyCDIBean {

    public void doSomethingWithoutATransaction() throws Exception

        //Do something that must be done outside of a transaction

    public void doSomething() throws Exception {
//Do something that must be done inside a transaction

The "@Transactional(Transactional.TxType.MANDATORY)" annotation on the class states that, by default, all methods must be invoked within the scope of a JTA transaction. This can be overridden on a per-method basis.

The 'doSomethingWithoutATransaction' method overrides the 'MANDATORY' type with "NEVER". Therefore, this method will fail if it is invoked in the scope of a JTA transaction.

Specifying what Exceptions should cause the transaction to rollback is specified differently with @Transactional. With EJB's @TransactionalAttribute, the developer had to declare on the actual Exception class whether an exception of that type, thrown from a method annotated with @TransactionalAttribute, should cause the active transaction to be marked for 'rollback only'. The problem with this approach was that it could not (easily) be applied to third-party exception implementations and it also applied for all usages of that exception. @Transactional fixes these issues by allowing the developer to specify on a per-method basis, which Exception types (and sub-classes of) should cause a rollback. This is done through the 'rollbackOn' and 'dontRollbackOn' attributes. By default, RuntimeException and its subclasses will cause a rollback.

Another difference to watch out for is the default behaviour when no transaction annotation is provided. With an EJB, the default value of TransactionalAttribute is TRANSACTION_REQUIRED. This means that a new JTA transaction is begun (when calling the method) if one doesn't already exist. This works for EJB as the developer has already opted-in through the use of an EJB annotation (@Stateless, @Statefull, etc). With CDI, a managed bean can have no annotations, thus it is difficult to differentiate between it and a regular POJO. Therefore, the default value for @Transactional is TxType.SUPPORTED. This means that the method will run within a transaction if one exists; otherwise it will run without one. This is essentially how transactions are handled with java POJOs.


With @TransactionScoped brings an additional CDI context to accompany @SessionScoped, @RequestScoped and @ApplicationScoped. Annotating a bean with @SessionScoped ensures that the same instance of the bean is made available for all usages of it within the scope of a http session. This allows the developer to easily share state between multiple requests within a session, whilst also isolating it from other requests in a different session.

@TransactionScoped allows data to be shared between all usages of the bean within a particular transaction, whilst isolating the instance from other accesses of the bean within a different transaction. The TransactionScoped bean instance's lifecycle matches that of the transaction.

The following code shows an example of this in use:

public class MyCDITransactionScopeBean implements Serializable {

    private int value = 0;
    public int getValue() ... 
    public void setValue(int value) ...

MyCDITransactionScopeBean represents the data to be associated with the active transaction. It is simple POJO annotated with @TransactionScoped and also marked as Serializable.

public class SomeClass {

    MyCDITransactionScopeBean myBean;

MyCDITransactionScopeBean can then be injected into other classes that need to use it.

Go and give it a try!

Just download the latest version of WildFly and start deploying code. We don't yet have any quickstarts for these features, but our Arquillian tests provide a complete example of how to use the functionality.

Wednesday, September 11, 2013

Get involved with Narayana!

If you are interested in getting involved in the open source community we would love to hear from you! We are always looking for new contributors to help out with the broad selection of enhancements and features we are looking to add to our project.
The best approach to take is to have a look at our Jira instance and see if there are any items on there that you would like to see added to the project. Our Jira instance is located over at: where we have all of the dev tasks waiting; from development to build management, and from documentation to JDF style quickstart writing.

Once you have picked out a task you would like to work on, feel free to have a chat with us over in our chatroom hosted on Freenode: then (and if you haven't done so already) you will need to fork one of our projects over on github:
  • For core related, it will be:
  • If its docs it will be:
  • For quickstarts, it will be:
Once you have developed your contribution, first make sure you have signed the JBoss Contributor License Agreement over here:, then raise a Pull Request on our of our repos.
A good pull request has the following qualities:
  • Ideally, each pull request is focused on a single functional area
  • Each commit is clearly labeled with an issue number from Jira
  • Where reasonable, each Jira issue is tackled in a single commit - time to squash!

After you raise a pull request on one of the Narayana repos, one of our team of highly skilled "buildbots" will take a look over it and run our comprehensive test suite against it. The buildbot will keep your pull request up to date with comments as it works its way through the various phases of test and hopefully at the end will be able to indicate a complete build success!
One of the devs will then be able to merge your update and your place in history as a contributor on the project is secured!

Thursday, September 5, 2013

Narayana 5.0.0.M4 and JBoss Transactions 4.17.9.Final released!


It is with great pleasure that I can announce Narayana 5.0.0.M4 has been released and integrated into the WildFly application server master branch! Maven central has been updated with the release, plus the binary zips and docs are now available here:

Source tags are located here:

The release notes are available here:|38dea2e03ccddd2835723190cd876cad2317ad03|lin

Alongside the usual incremental fixes and enhancements, we are also happy to announce that the BlackTie project is now fully merged into the Narayana code base.

This is the penultimate milestone release for Narayana 5. We are intending to release Beta1 in October and the .Final shortly afterwards.

In other news, we recently released 4.17.9.Final of JBoss Transactions containing a few bug fixes, the release notes are over here:|394366ea879c98614444896710bd0831b550e086|lin