Getting Started Guide

Recommended software Java8, Tomcat 8.5 contains 3 files in lib folder and a getting started document.

1) lib/SGAgent_Tomcat.jar
2) lib/SeagenceWeb.war
3) lib/SGLogAgent.jar

SGAgent_Tomcat.jar : This is java agent, runs with your applicatin.
SGLogAgent.jar : This is log agent and runs as a separate process on the same machine as your application.
SeagenceWeb.war : This is SeagenceWeb (SeagenceEngine) runs in a web server. It should be deployed on a separate machine of it's own. If you are testing/evaluating deploy on a separate web server on the same machine as your application.

Note1: Seagence will require an SMTP server to be able to send email alerts. You can use your own SMTP server or use free Google SMTP server. If you use free Google SMTP server, you will need a gmail id with password(as email sender). If you use your own SMTP server, you will need smtp host, port and email id with password. Have these details handy for setup.
Note2: All your data and sensitive information will stay on your machine only.
Note3: Currently Seagence has Agent/Connector for Tomcat only. Others will soon be available for download.

Step1: Create a directory called seagence and unzip the contents of into seagence directory.
step2: Create a directory called weblogstore inside seagence
step3: Create another directory called logstore inside seagence

Step4: Deploy SeagenceWeb (SeagenceEngine)

Deploy SeagenceWeb.war in any web server of your liking (Be sure not to deploy in the webserver where your application will be running). Use below JVM options

-DlogStore=.../seagence/weblogstore -DfailureReportingType=4

Note4: failureReportingType=4 will report failures every 15 minutes in default setting.

Example:-DlogStore=C:/seagence/weblogstore -DfailureReportingType=4

Now start web server to deploy SeagenceWeb.war.

a) Open a browser window and goto http://host:port/SeagenceWeb
b) Click Sign Up
c) Fill out the form to create a seagence user
Customer Name = Your company name
Customer Email = Email id where alerts will be delivered to
User Name = seagence log in name
Password = seagence log in password
d) Click Sign Up
e) Click Sign In
f) Log in using seagence user that you just created in step c
g) Click Sign In
h) Click Admin tab
i) In "Application Instances" screen, enter a name in the text box. This becomes host name running your application. Remember that you will need this in next steps.
j) Click Save
k) Click SMTP Tab
l) Choose either Free Google SMTP server or your own SMTP server
m) If you choose Free Google SMTP server, you will need to enter sender gmail id and it's password. (For evaluation purpose, you can create a new gmail account.)
n) If you choose Another SMTP server, you will need to enter your smtp server host, smtp server port, sender email id and it's password.
o) Click submit

With this SeagenceWeb is setup.

Step5: Deploy your application in Tomcat

Before starting your application, attach seagence agent (SGAgent_Tomcat.jar) to your application using below JVM option

-Xbootclasspath/a:".../seagence/lib/SGAgent_Tomcat.jar" -javaagent:.../seagence/lib/SGAgent_Tomcat.jar="logStore=.../seagence/logstore name=application-host-name excludeURL=.*.png|.*.css|.*.js|.*.woff2|.*.woff|.*.gif|.*.jpeg|.*.jpg|.*.xml|.*.txt|.*.ico"

application-host-name is what you provided in Step4 -> i

Example: -Xbootclasspath/a:"C:/seagence/lib/SGAgent_Tomcat.jar" -javaagent:C:/seagence/lib/SGAgent_Tomcat.jar="logStore=C:/seagence/logstore name=amazon_host excludeURL=.*.png|.*.css|.*.js|.*.woff2|.*.woff|.*.gif|.*.jpeg|.*.jpg|.*.xml|.*.txt|.*.ico"

Note5: Use excludeURL (a regular experession) to exclude monitoring of access to static resources like images, js/css files etc that seldom fail. This will lessen overhead on the application.

Step6: Start seagence-log agent

On command prompt change directory to .../seagence/lib and execute below command

java -jar SGLogAgent.jar user-name application-host-name .../seagence/logstore seagence-engine-url

Where user-name is what you provided in Step4->c
application-host-name is what you provided in Step4->i

Example:java -jar SGLogAgent.jar amazon_user amazon_host C:/seagence/logstore http://localhost:8080/SeagenceWeb
With that Seagence setup is done.

Get a feeling of how Seagence works

Note6: Know that Seagence is a Machine Learning solution that need to crunch a lot of data to make failure identification accurately. Seagence works best in production environments where data availability is not a problem. In production, Seagence runs in silent mode until enough data is collected. Once enough data is collected Seagence will extract meaning, switch into monitoring mode and start identifying failures.

The best way to get the hang of how Seagence works is by introducing a defect in your code and see how Seagence finds it. Now introduce a code break in your code either in Controllder class or Service class or any other place as you like as shown below.

Define a static field variable

     public static int counter = 0;

and then somewhere in your controller method or service method (for example fetchAccount or findProfile), add these below lines

     if(counter == 10 || counter == 23 || counter == 43 || counter == 52 || counter == 73 || counter == 100) {
          throw new NullPointerException();

Now build and deploy your application.

Effectively we are telling the applicatin/method to fail when the if condition satisfies. As you can understand this will fail 6 times when invoked >100 times. Now make sure that above function is invoked atleast 100 times while using applicatin front end/browser (100 is the minimum sample size needed for Seagence ML algorithm).

Once above step is done.

a) Log in to SeagenceWeb at http://host:port/SeagenceWeb
b) Click Knowledge tab
c) Click "Build Knowledge" link and wait for SeagenceEngine to complete it's analysis. SeagenceEngine completes when you see "Knowledge build task has completed." message in the SeagenceWeb log. This step is not needed in production. Seagence will perform this step automatically when enough data is available.
d) Now sign in to your inbox and see that alert is raised. In the alert you will see the URL (corresponding to the function) that has failed, stacktrace causing the failure and number of times that URL has failed. "This is the core of Seagence, failure and rootcause identification".
e) Browse through "Dashboard" and "Clusters" tabs. On Dashboard you can find/search/filter all requests (failures and successes) and debug information. On Clusters tab, you will find requests grouped by URL/request.

More info about how to use SeagenceWeb is here.
More info about how to use Seagence and it's settings is here.