Non servlet client

This guide describes how to use StackHunter in non-servlet clients (desktop apps, batch jobs, command line tools, etc.).

The following techniques can also be used in your web applications at any time. In those scenarios, the exception logs will automatically include the HTTP request details (parameters, cookies, user, etc.).

Configuration

After downloading the application config file, place it in your classpath. It must be in the root of your classpath and not in a package or folder. One place you can put it is alongside your log4j.properties file if you use one.

Log Using The API

The easiest way to send exceptions from your standalone application to StackHunter is using the StackHunter API.

Log Using Log4J

Another easy option to send exceptions to StackHunter is using Log4J.

Just make sure to call StackHunter.init() at least once before you start logging exceptions.

The init() method is thread-safe and safe to call multiple times. It's job is to ensure the StackHunter class is loaded. When that happens, StackHunter will hook into all supported log frameworks it finds.

Log Using Logback

You can also use Logback to send exceptions to StackHunter.

Just make sure to call StackHunter.init() at least once before you start logging exceptions.

The init() method is thread-safe and safe to call multiple times. It's job is to ensure the StackHunter class is loaded. When that happens, StackHunter will hook into all supported log frameworks it finds.

Log Current User

The StackHunter API provides you the option to send your app's current user along with each exception.

Unlike Java web applications, standalone apps have no guaranteed way to retrieve the current username since they may operate on behalf of many users. The user.name system property may work in your case or you may have another way of obtaining this info.

Usernames can be any string value — email, token, ID, etc. — up to 255 characters in length. Anything over this length will be automatically truncated.

Null and empty string usernames are treated as anonymous users and lumped together for reporting purposes.

Log Additional Attributes

The StackHunter API provides a way for you to attach key-value properties to each exception you send.

Adding key-value properties to your exceptions can provide the crucial context needed to reproduce and resolve failures quickly.

The API allows you to add up to 256 separate properties to each exception.

Keys are limited to 128 characters and values to 255 characters in length. Anything over these lengths will be automatically truncated.

Properties Tab

You can view the key-value properties associated with each exception on the properties tab.

Log Additional Attributes Using Thread-Locals

Another way to attach key-value properties to your exception logs is with thread-locals.

Thread-locals allows you to specify key-value properties that are sent with exceptions thrown anywhere in the current thread.

These properties will be attached to your exceptions regardless of how they are sent (API, Log4j, etc.).

Since the thread-local properties stay with each thread for as long as the thread is alive, you may want to explicitly remove them using StackHunter.clearThreadLocals() at key moments, such as when a user logs in or out.

The clearThreadLocals() method should not be called in web apps as the servlet filter already does this for you.

Contact Us

Other ways to reach us: eMAIL, Twitter