NServiceBus has always supported centralized audit and error handling by allowing you to specify centralized queues where successfully and failed messages ends up. NServiceBus will guarantee that each message you send/publish will end up in one of those queues, hopefully the audit queue:). Earlier versions of NServiceBus had some rudimentary support for managing errors but for audit messages it was up to you as a user to make something useful with all that data. This has now changed with the introduction of ServiceInsight.

ServiceInsight gives you a graphical view of your messages flows, insight into why a given message has failed and also a way to issue retries for those messages. Since queues are not really that great for longtime storage of data we needed a way to process all those message in order to make it easier to query and manipulate them from the UI. We also decided to not limit access to just our own tools but instead make all data and operations on it available to you via a REST'ish api.

The api is still early days but we hope to keep on expanding it to help you build management extensions for NServiceBus for your tool of choice.

Official documentation is coming soon but I don't expect much to change from what's mentioned below.

Installing the backend

The api backend is installed automatically when you run the NServiceBus or the ServiceInsight installers. The backend is just a regular NServiceBus host that gets installed as a windows service. Once that is done it will continuously import messages from your audit and error queues and making the data available over http. By default the api will respond on http://localhost:33333/api but the installers will allow you to tweak the uri to your liking. If you forgot where it got installed you can always consult the following regkey:

HKEY_LOCAL_MACHINE\SOFTWARE\ParticularSoftware\ServiceBus\Management

Once installed the endpoint will import and index all error and audit messages.

Where did my errors go?

The management endpoint will import all errors into our internal storage and leave a copy in a queue called {name or your error q}.log so in your case it will most likely be in error.log.

This means that you can still run tool like QueueExplorer, ReturnToSourceQueue.exe etc to manage your errors in the same way as before if you don't have access to ServiceInsight.

Supported API calls

The API is heavily inspired by the GitHub api guidelines for urls, paging, sorting etc

At the time of writing the following calls are supported:

GET /audit   - lists all messages successfully processed

GET /endpoints/:name/audit  - lists all messages successfully processed for the given endpoint

GET /errors   - lists all failed messages
GET /endpoints/:name/errors  - lists all failed messages for the given endpoint

GET /messages/:id - Gets the given message

GET /messages/search/:criteria - Does a free text search with the given lucene query

GET /endpoints - Lists all the known endpoints

GET /endpoints/:name/messages - Lists all messages (including failed ones) for the given endpoint

GET /conversations/:id- Gets all message for the given conversation id. (I'll talk more about conversations in a follow up post)

In terms of updates we only support one at the moment:

POST /errors/:id/retry  - Issues as retry for the given message. Returns Http Accepted  (202) if successful since the actual retry is performed async.

 

Security

The is no explicit security in place at the moment and the service is expected to run on a secured server that only authorized personnel has access to.

Lets see it in action

I've created a few ScriptCs scripts to show the usage of some of the above calls.

The full repo can be found here:
https://github.com/andreasohlund/NServiceBus.ScriptCs
Latest unstable Management API:
http://builds.nservicebus.com/viewLog.html?buildId=4651&tab=artifacts&buildTypeId=bt42

Please take it for a spin and tell me what you think!

You can use the Video store sample that comes with NServiceBus to generate some test data if you don't have a v4 system up and running!

 

What is missing?

Which tools would you build NServiceBus plugins for?

Comments are most welcome!

 

Limitations:

* The first drop only supports the MSMQ transport but support for the others is our top priority so expect support for all other transports in the very near future