Get Started With Seagence

Getting started with Seagence is very easy.

  1. Create a Seagence account
  2. Connect your application
  3. That’s it (when defects occur Seagence will alert)
Pattern

Register and Download

Seagence works with Java 8 and above, Tomcat/Wildfly/Undertow/Jetty/Weblogic.

1) Click “START FOR FREE” button at the top right corner
2) Register on app.seagence.com
3) Login with new user name/password
    Note user name which you will need at a later step
4) After successful login, go to Admin tab, click “Download SGAgent” and download SGAgent.jar

5) In the same Admin tab, click “Show API Token” and copy displayed API Token.
6) Follow instructions below

Connect your Application

Step1: Copy the downloaded SGAgent.jar file into a directory of your choice.

Step2: Create an empty properties file sgagent.properties in the same directory where SGAgent.jar is copied. Then copy the below properties into the file.

machineName=[Assign a name to machine/node where your application is running]
userName=[User name you provided at the time of registration]
seagenceWebURL=https://app.seagence.com/SeagenceWeb
containerName=[Tomcat | Weblogic | Jetty | Undertow | use Undertow for Wildfly as well]

apiToken=[API Token copied from Admin tab]

Contents of a sample sgagent.properties file are below.

machineName=foonode
userName=foouser
seagenceWebURL=https://app.seagence.com/SeagenceWeb
containerName=Tomcat
apiToken=wvLI-jTUv-Atlh-ASPb-zDLe

Step3: Attach SGAgent to your application

Use below JVM options to attach SGAgent.jar to your application.

For Tomcat, Weblogic, Jetty add this to JAVA_OPTS.
-javaagent:path-to-SGAgent.jar=”propertyfile=path-to-sgagent.properties”

For Undertow, add this in standalone.bat.
-javaagent:path-to-SGAgent.jar=”propertyfile=path-to-sgagent.properties” -Djboss.modules.system.pkgs=com.sg.agent

Example for Tomcat: -javaagent:C:/seagence/SGAgent.jar=”propertyfile=C:/seagence/sgagent.properties”

With that setup completes. Bring your application up and start using. SGAgent will post collected monitoring data to SeagenceWeb in the background.

 
Pattern

Get a feeling of how Seagence works

Having SGAgent attached, let’s see how Seagence works. For this we will do a small exercise in Dev environment. Select a simple GET (or POST) operation that invokes some business function in your application. Something like one that fetches data from DB or any other simple GET operation (select a simple operation because you will need to invoke this operation a 100 times for Seagence to collect enough sample. In production you will have huge number of users using the application, so sample collection is not a problem in production).

The best way to get the hang of how Seagence works is by introducing a defect in the selected GET operation and see how Seagence finds it. We introduce the defect in dev environment only and will remove it after the exercise. To do that add below code either in your Controller class or any other class (before business rules/logic starts executing when the GET operation is invoked) as shown below.

Note: For the sake of argument can it be said that you introduced this defect unknowingly while fixing another defect. And when Seagence finds it, can it be said that Seagece found an unknown defect?

Define a static field variable

     public static int counter = 0;

and then add these below lines at the start of the method body of Controller class or other class where business logic starts executing.

     counter++;
     if(counter == 10 || counter == 20 || counter == 30 || counter == 40 || counter == 50 || counter == 60 || counter == 70 || counter == 80 || counter == 90 || counter == 100) {
          throw new NullPointerException();
     }

There is no rocket science here, we are just telling the selected GET operation to fail few times. Now invoke the operation few more than 100 times and we know that few of those invocations will fail.

Now that Seagence collected enough sample it is time to create the baseline. Seagence automatically creates incremental baseline at regular interval. The default interval is 12hr. Instead of waiting that long, you create the baseline by login into SeagenceWeb, go to Baseline tab and click “Create Baseline”. At this time you will receive alert for failed invocations (one alert per failure cluster, with a count of failures. A cluster is a group of similar invocations), so now check your inbox. Also check Clusters tab on SeagenceWeb for more debug information.

Alert not received? Check if enough sample is collected. Click “Data” link in Baseline tab which will list amount of sample collected per endpoint. Is the sample size greater than 100 for our GET operation? If not invoke the operation few more times, create Baseline again and see that alert is sent for failed invocations.

You will find more debug information on SeagenceWeb, under Clusters tab.

You still have not received alert? You might need some help, please post your question to info@seagence.com.

 

Now let's dive little deeper

The earlier defect we introduced either results in HTTP error 500 or in uncaught exception. Other monitoring solutions can also detect such failures easily. However Seagence can also find much difficult defects, for example the ones caused by swallowed exceptions. Now we will swallow the exception and see how Seagence works. To keep things simple let’s start afresh. Go to Admin tab on SeagenceWeb and delete all sample by clicking “Delete Data”.

If you swallow the exception like below


   try {
     counter++;
     if(counter == 10 || counter == 30 || counter == 40 || counter == 50 || counter == 60 || counter == 70 || counter == 80 || counter == 90) {
          throw new NullPointerException();
     }
   } catch(Exception exc){}

it will have no impact on your operation and the invocation will continue successfully. So allow the exception to make some impact on the invocation by jumping few instructions so that it fails and then swallow it like below.

   try {
     counter++;
     if(counter == 10 || counter == 30 || counter == 40 || counter == 50 || counter == 60 || counter == 70 || counter == 80 || counter == 90) {
          throw new NullPointerException();
     }
     ...
     ...
     ...
   } catch(Exception exc){}

Now invoke the GET operation 100 times like earlier and see that Seagence finds defects caused by swallowed exceptions as well including root cause. For technical support please post your questions to info@seagence.com.

Pattern

Say no to setting alert rules, thresholds and configuring exceptions

All this while notice that you have not input anything to Seagence like

1) Event is first seen – an alert rule setting
2) An event is seen more than {value} times in {frequency} – a threshold setting
3) A suspicious exception seen during an endpoint invocation – a suspicious exception configuration

Irrespective of any of this input, Seagence finds all failures and defects (even in the absence of HTTP status error codes and error pages) including failures due to gracefully handled exceptions, swallowed exceptions etc., with root cause in real time as they occur in production.