How StackHunter Works

Overview

StackHunter comes in two parts: a client (or agent) and a server.

The Client

The client piece sits in each of your applications to relay exceptions and diagnostic info to the server. The client is packaged as a jar you add to your WEB-INF/lib or classpath. The jar contains a servlet filter which initializes the exception capture hooks and helps collect contextual data when exceptions are thrown.

Log Integration

One of StackHunter's exception capture hooks is through integration with your logging framework. StackHunter currently supports Log4J and Logback. The integration is done automatically when StackHunter loads, however there are a couple things to remember.

  1. StackHunter only records exceptions logged with the two argument methods: log.info(message, exception).
  2. StackHunter only records exceptions logged at INFO level or higher. Exceptions logged at the DEBUG and TRACE levels are ignored.

Not in a Servlet Container?

If you're not running in a servlet container, you can log exceptions using the API directly:

com.stackhunter.client.StackHunter.logException(Throwable)

Or, by using Log4J or Logback, after initializing the API:

com.stackhunter.client.StackHunter.init()

Learn how to use Stack Hunter in a non-servlet clients

The server

The server receives and stores exceptions from your applications, via the clients, and presents them through its web interface. If an outgoing SMTP server has been configured, the server will send out alerts to any email addresses you've provided.

The server is packaged as a war file you deploy into a servlet container. The server application is self-contained and doesn't require any database or other setup. It's ready to go as soon as you deploy it.

Deployment

You have the option of deploy the server into the same container as one of your applications or in its own container. Both options are supported, but where you host the server ultimately depends on your environment and setup.

Alerting

StackHunter uses an outgoing mail (SMTP) server to send email alerts. If one is not configured, StackHunter will continue to collect and present exceptions, you just won't receive email alerts.

Database

StackHunter uses an embedded H2 database to store exceptions. The database, along with any configuration preferences, will be stored in the $(user.home)/.stackhunter folder.

Example folders:

  • /usr/share/tomcat7/.stackhunter
  • C:\Windows\System32\config\systemprofile\.stackhunter
  • C:\Users\jsmith\.stackhunter

You can see the root folder on the server's General Settings page.