Start for free

Get things off the ground with Seagence's free plan, and when you're ready to expand usage you can simply pay as you go.


Download

Download SGAgent-9.0.jar
Currently Seagence works with Java8 and above, Tomcat 8.5,9.0/Wildfly/Undertow

1) Click "Download Now" link below
2) Register on www.appgence.com
3) Login with new user name/password
    Note user name which you will need at a later step.
4) After successful login, download agent file from Admin tab
5) Follow "Getting Started" instructions below


Getting Started

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

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

name=[Choose a new name to machine/node where your application is running]
userName=[User name you provided at the time of registration]
seagenceWebURL=https://www.appgence.com:8443/SeagenceWeb
excludeURL=.*.png|.*.css|.*.js|.*.woff2|.*.woff|.*.gif|.*.jpeg|.*.jpg|.*.xml|.*.txt|.*.ico [Leave it as is]
containerName=[Tomcat or Undertow, use Undertow for Wildfly as well]

Contents of a sample sgagent.properties file are below.

name=foonode
userName=foouser
seagenceWebURL=https://www.appgence.com:8443/SeagenceWeb
excludeURL=.*.png|.*.css|.*.js|.*.woff2|.*.woff|.*.gif|.*.jpeg|.*.jpg|.*.xml|.*.txt|.*.ico
containerName=Tomcat

Step3: Attach SGAgent to your application

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

For Tomcat, add this either in catalina.bat or setEnv.bat.
-Xbootclasspath/a:"path-to-SGAgent-9.0.jar" -javaagent:path-to-SGAgent-9.0.jar="propertyfile=path-to-sgagent.properties"

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

Example for Tomcat: -Xbootclasspath/a:"C:/seagence/SGAgent-9.0.jar" -javaagent:C:/seagence/SGAgent-9.0.jar="propertyfile=C:/seagence/sgagent.properties"

With that setup completes. Make sure your applicatin is up and running. If you access your application now SGAgent will post collected monitoring data to SeagenceWeb in the background.


Get a feeling of how Seagence works

Having SGAgent attached, lets see how Seagence works. Seagence uses ML so it need to crunch lot of data to make accurate decisions. Let's do a small exercise. Select a simple GET operation 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 number of users doing this, so sample collection is not a problem there).

The best way to get the hang of how Seagence works is by introducing a defect (yes but in dev only, you know it) in the seleccted GET operation and see how Seagence finds it. To do that add below code either in your Controllder class or any other class (where business rules/logic starts executing when the GET operation is invoked) as shown below.

Define a static field variable

     public static int counter = 0;

and then add these below lines at the start of the method body.

     counter++;
     if(counter == 10 || counter == 30 || counter == 40 || counter == 50 || counter == 60 || counter == 70 || counter == 80 || counter == 90) {
          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 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 creates incremental baseline at regular interval. The default interval is 1hr. Instead of waiting that long, you create the baseline by login into SeagenceWeb, go into Baseline tab and click "Create Baseline" link. 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 both your inbox and Clusters tab on SeagenceWeb.

Alert not received? Check if enough sample is collected. Click "Data" link in Baseline tab which will list amount of sample collected per operation. 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.

Thinking this is not realtime? Realtime alerting starts after first baseline is created. Now invoke the GET operation to fail again (you need to restart your app for the GET operation to fail again because now counter > 100) and see realtime alert delivered to your inbox.

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

You still have not received alert? You might need some help, please post a question in the forum.


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. If you have any questions, please post them on the forum.


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 is 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.


Performance tuning

Seagence by default

1) collects all stacktrace elements of an exception
2) monitors all endpoints
3) monitors entire code base
4) collects all exceptions thrown

1) Tuning "collects all stacktrace elements of an exception"

Large applications usually use lot of dependent libraries and hence their stack traces are also long. Because most stacktraces contain same elements at the start of the stack, Seagence can be instructed to collect only few top elements with collectStackTrace parameter. Using this parameter to collect only few top stack elements, a lot of overhead can be reduced.

collectStackTrace=0 : Means no stack trace is collected, only exception type and exception message are collected
collectStackTrace=1 : This is default and collects complete stack trace including exception type and exception message
collectStackTrace=2 : Top 25 stack elements are collected including exception type and exception message
collectStackTrace=50% : Half of the stack elements are collected including exception type and exception message
collectStackTrace=[any positive number other than 0, 1, 2] : Means that many stack elements are collected including exception type and exception message

2) Tuning "monitors all endpoints"

Seagence by default intercepts all endpoints including endpoints of static resources like images, html, js, css etc. If you are serving these resources from the application being monitored and wish not to monitor them to reduce overhead you can tell Seagence to not intercept access to them using excludeURL parameter. excludeURL takes a regex value.

An example excludeURL is here
excludeURL=.*.png|.*.css|.*.js|.*.woff2|.*.woff|.*.gif|.*.jpeg|.*.jpg|.*.xml|.*.txt|.*.ico

3) Tuning "monitors entire code base"

Seagence by default monitors entire application code base. The good part about Seagence's unique Execution Path technology is that it doesn't require entire code base to be monitored. It still works efficiantly by monitoring only partial application code. By monitoring as low as 20% of your code base you can reduce overhead by 5 times. You use incl (include) / excl (exclude) parameters to tell Seagence what packages to include and exclude from monitoring. However what is importent here is to make sure that the monitored packages/classes are spread evenly across request/transaction execution. You can do that by selecting few packages/classes from web layer, few from controller layer, few from service and data access layer.

Irrespective of what packages/classes are being monitored, all exceptions and errors will be collected and recorded.

4) Tuning "collects all exceptions thrown"

Seagence by default collects all exceptions/errors thrown. If you thik there is some noisy exceptions that don't cause any problem you can tell Seagence to stop collecting them using excludeExceptions parameter.

An example use below
excludeExceptions=javax.naming.NameNotFoundException;java.lang.ClassNotFoundException;java.lang.NoSuchMethodException