1. Installation & Configuration
Installation & Configuration
inspectIT Workshops
Leinfelden-Echterdingen, August 2014
NovaTec Consulting GmbH
Leinfelden-Echterdingen, München, Frankfurt/Main, Berlin, Jeddah / Saudi Arabia

2. DVD Store Demo application
Installation
DVD Store Demo application
We need an application to monitor
Unpack the .zip containing the demo application
Start JBoss by running startJBoss.bat or startJBoss.sh
Prove it’s working:
Buy one movie in the store 
Note that we did not yet stared the application with the inspectIT Agent
Download the inspectIT configuration folder (config.zip) and unpack it

3.
Installation
2 options
Run installer JAR that will install all components on one machine
Download and unpack component by component
Download:
(only latest)
ftp://ntftp.novatec-gmbh.de/inspectit/releases/ (all available)
Please no whitespace in the installation path
For workshop you can run the installers from the USB
Install all three components
Start the CMR
Start the UI
Confirm that everybody have CMR available
Explain that is possible to connect to many repositories (2 ports explanation)
Explain the CMR properties, buffer size, etc

4. Installation Components For Workshop: In real life
Installation
Components
For Workshop:
All 3 components on same machine
In real life
Application with inspectIT Agent on one server
inspectIT CMR on another server
inspectIT UI on your laptop/dev machine
Install and start the CMR & UI
For workshop you can run the installers from the USB
Install all three components
Start the CMR
Start the UI
Confirm that everybody have CMR available
Explain that is possible to connect to many repositories (2 ports explanation)
Explain the CMR properties, buffer size, etc

5. Start DVD Store with inspectIT Agent
Installation
Start DVD Store with inspectIT Agent
Application to be monitored must include following JVM parameters for monitoring
Point the configuration to the already downloaded configuration folder
How to add these parameters depend on the application server
JBoss
Alter the run.bat or run.sh files in the [JBOSS_ROOT]/bin
Point to the default configuration folder that comes with inspectIT Agent
(Re)start the JBoss
-javaagent:/path/to/inspectit-agent.jar -Xbootclasspath/p:/path/to/inspectit-agent.jar -Dinspectit.config:/path/to/folder/containing/config/file
Start DVD with inspectIT
Make sure UI shows the Agent
Explain Show / Hide inactive agents, agent status and other agent related stuff
Explain instrumentation browser
Execute few requests on the DVD Store
Make them see initial data. I think by default they would only see SQLs, maybe also HTTP
Make them see platform sensor data like CPU, Memory, etc
Additional UI basics
Repository manager view
Data explorer view
Different editors - Timer, SQL, Invocation sequences, HTTP, Exceptions (just to understand what will appear where)
-- Linux –-
export JAVA_OPTS="needed_inspectit_params ${JAVA_OPTS}"
-- Windows –-
set JAVA_OPTS=needed_inspectit_params %JAVA_OPTS%

6. Configuration
Basics
Configuration file must be called inspectit-agent.cfg
Additional configuration files can be included with
Every time you change the configuration file(s) you must restart the application/server
$include /other/file.cfg

7. Repository definition & strategies
Configuration
Repository definition & strategies
Repository definition
Defines where to send monitoring data
Port 9070 is default port CMR listens for the data sent by an agent
Defines name of the agent
## repository <IP> <port> <Agent Name>
#############################################
repository localhost 9070 MyDvdStore
- Change name of the agent to something you like more than inspectIT

8. Configuration Sensor definitions Platform sensors Method sensors
Configuration
Sensor definitions
Platform sensors
Definition makes it active
Method sensors
Definition makes it available for assignment
Defines name of the sensor and properties
Exception sensor
Special type does not define name, just properties
Use enhanced mode with care
platform-sensor-type info.novatec.inspectit.agent.sensor.platform.CpuInformation
method-sensor-type timer info.novatec.inspectit.agent.sensor.method.timer.TimerSensor MAX stringLength=100
Documentation has detailed information on each sensor type and it’s properties
String length only reasonable to change, explain what it is
Set no limit on jdbc sensors – we want to see extra long SQLs as well
Set exception sensor to enhanced
exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor mode=simple stringLength=500

9. Method sensor assignment
Configuration
Method sensor assignment
Direct
Specify class name, method & parameters completely
Wildcards
Can be used on class name, method name or parameter
* substitutes any character
sensor timer novatec.SubTest msg // any msg method in the specified class
sensor timer novatec.SubTest msg(java.lang.String,int) // just with given params
sensor timer novatec.* msg(int) // all classes in package that have msg(int)
sensor timer novatec.SubTest msg(*String) // wildcard in parameters also possible

10. Method sensor assignment
Configuration
Method sensor assignment
Exercises
Basic – Question 1 & 2

11. Method sensor assignment
Configuration
Method sensor assignment
Filtering
Modifiers
Only method(s) with specific modifier(s)
Annotation
If annotation is on class level, then all methods in classes that have annotation
If annotation is on method level, then only methods having it
Filtering can be combined with wildcards, interface/superclass, etc.
sensor timer novatec.SubTest * modifiers=pub,prot // only public & protected methods of given class
sensor timer novatec.* modifiers=pub // all public methods of classes in novatec // package that are annotated with Stateless

12. Method sensor assignment
Configuration
Method sensor assignment
Exercises
Basic – Question 1 & 2
Basic – Question 3

13. Method sensor assignment
Configuration
Method sensor assignment
Interface
Instrument specified method of the class that implements given interface
Superclasses
Instrument specified method of the class that extends given super-class
Only methods defined in the sub-class will be instrumented
Advantages
Fewer configuration lines
Automatically pick up new implementations of existing interface/super-class
sensor timer novatec.ITest * interface=true // all methods of all classes implementing ITest
sensor timer novatec.* * interface=true // all method of all classes that implement any // interface in the novatec. package
sensor timer novatec.AbstractTest * superclass=true // all methods of all classes that extend the // AbstractTest class

14. Method sensor assignment
Configuration
Method sensor assignment
Exercises
Basic – Question 1 & 2
Basic – Question 3
Advanced – Questions 1 & 2

15. Method sensor assignment
Configuration
Method sensor assignment
Some sensor have additional options that can be specified in assignment
Timer sensor
Charting – saves duration info of a method to database, so it can be displayed in graph
charting=true
Context capturing
p=0;parameter1; (captures the first parameter of the method and provide its value as contextual name "parameter1")
r=myResult; (captures the return value and provide its value as contextual name “myResult")
Invocation sensor
Min duration – only send invocation to CMR if it’s duration is higher than defined
minDuration=100 (only send invocations that last longer than 100ms)
sensor timer novatec.SubTest msg(java.lang.String) p=0;message;
Sensor timer novatec.SubTest getSize r=size;

16. Method sensor assignment
Configuration
Method sensor assignment
Never instrument!
Methods like toString, equals & hashCode
Getters and setters
Any method that is executed often and it’s expected to be executed in nanoseconds
What to instrument (from my experience)
Database calls
Services, DAOs
Method that perform some work (execute, perform, calculate, transform, load, etc..) 
- To much overhead

17. Exception sensor assignment
Configuration
Exception sensor assignment
Simple, just define exception class to catch
Wildcards also possible
No super-class definition possible
exception-sensor java.lang.NullPointerException
exception-sensor my.app.*

18. Configuration Common technologies
We provide the configuration for the common technologies
No need to define how to monitor SQLs, HTTPs, etc
Plus easy to instrument some well-know technologies like EJBs, Web services, etc
Configuration files located in the common folder (can be included in the main config file)
Warning!
Be careful when using this, since it can instrument too much
Always try to give the package prefix of the application you want to monitor

19. Configuration Exclude classes
Sometimes some classes should be excluded from instrumentation
There is a default exclude-classes.cfg file, this can be extended if needed:
exclude-class info.novatec.inspectit.*
exclude-class $Proxy*
exclude-class com.sun.*$Proxy*
exclude-class sun.*
exclude-class java.lang.ThreadLocal
exclude-class java.lang.ref.Reference
exclude-class *_WLStubexclude-class *[]

20. Configuration
Sensor assignment
Let’s do some exercises 

21. Instrumentation of DVD Store
Configuration
Instrumentation of DVD Store
Change inspectIT configuration directory setting in the JBoss start-up script
Use default configuration directory supplied with the inspectIT agent
[agent_root]/config
Edit the inspectit-agent.cfg file in the mentioned directory and add instrumentations (next slide)
Several parts, after each part restart plus prove changes!
Change confirmed with instrumentation browser
 Additionally prove they can see new data

22. Instrumentation of DVD Store
Configuration
Instrumentation of DVD Store
Perform following instrumentations:
Common
Include common config for HTTP requests monitoring (check what file defines)
Include common config for SQL parameters monitoring (check what file defines)
Timer sensor
all methods of classes in com.jboss.dvd package that are annotated with javax.ejb.Stateless and javax.ejb.Stateful
all public methods of org.apache.catalina.core.ApplicationDispatcher
execute method of the com.sun.faces.lifecycle.Phase (this is abstract class)
set charting=true for all assignments
Exceptions
all exceptions in the com.jboss.dvd package
any java exception(s) of your wish
Context capturing (optional)
catch the first parameter of the com.jboss.dvd.seam.FullTextSearchAction.searchTitleAndDescriptionWithOneWord 
catch return of the com.jboss.dvd.seam.CheckoutAction.submitOrder , but catch the field trackingNumber of the returned Order 
Several parts, after each part restart plus prove changes!
Change confirmed with instrumentation browser
 Additionally prove they can see new data

23. - We lead IT-Projects to Success -
- We lead IT-Projects to Success -
Thank you very much for your kind attention!
NovaTec Consulting GmbH
Headquarters
Dieselstr. 18/1
D Leinfelden-Echterdingen
Phone:
Fax:
Internet:
Frankfurt/Main Office
Friedrich-Ebert-Anlage 36
D Frankfurt am Main
München Office
Landsberger Straße 439
D München
Jeddah Office
P.O. Box
Jeddah 21333, Saudi Arabia
Berlin Office
Potsdamer Platz 11
D Berlin