Developing and deploying a custom Java probe in BI Platform 4.0: Tutorial & Sample
Considerations before you get started
- For large productive landscapes it’s recommended that you upgrade your BI Platform to SP4 Patch 12, SP6 Patch 1, or SP7. Several corrections were made to improve stability and performance of the Monitoring Service (Adaptive Processing Server). See note 1833881.
- Create a dedicated Adaptive Processing Server to run your Monitoring Services. Best practice is to run no more than two dedicated Monitoring Services (two APS instances) as they work in a Active/Passive cluster. For details on creating a dedicated Adaptive Processing Server, refer to Best Practices for SAPBO BI 4.0 Adaptive Processing Servers
- If you plan to keep historical details about the success or failure of your custom probe, you will need to enable the trending database. For details, see the BI Platform 4.0 Administrator’s Guide.
Health Probe, Diagnostic Probe, or Hybrid Probe
It is important to understand the different types of probes that can be created as they each have different requirements and serve a slightly different function. Additionally, when you are ready to register your probe with BI Platform 4.0, you will need to define the type of probe so that the monitoring service will understand how to execute the probe.
- A health probe generates metrics of data types such as integer, Boolean, or string. An example of a health probe is the default CMS Logon/Logoff probe which checks that a user may successfully logon/logoff the Central Management Server.
- A diagnostic probe generates reports containing current system information. An example of a diagnostic probes is the default Stop/Start server probe. This probe checks all the servers, records the state of each server, restarts the servers and collects information about servers again.
- A hybrid probe functions as both a health probe and a diagnostic probe
Source code walk-through
import java.util.Locale;
import java.util.Map;
import java.net.Socket;
import com.businessobjects.sdk.monitoring.plugin.desktop.probe.IProbeInfoObject;
import com.businessobjects.sdk.monitoring.probe.AbstractProbe;
import com.businessobjects.sdk.monitoring.probe.DiagnosticProbeResult;
import com.businessobjects.sdk.monitoring.probe.HealthProbeResult;
import com.businessobjects.sdk.monitoring.probe.IDiagnosticProbe;
import com.businessobjects.sdk.monitoring.probe.IDiagnosticProbeResult;
import com.businessobjects.sdk.monitoring.probe.IHealthProbe;
import com.businessobjects.sdk.monitoring.probe.IHealthProbeResult;
import com.businessobjects.sdk.monitoring.probe.common.ProbeLocHandler;
import com.businessobjects.sdk.monitoring.probe.common.ProbeLocKeys;
import com.crystaldecisions.sdk.exception.SDKException;
import com.crystaldecisions.sdk.exception.ServerExceptionCode;
import com.crystaldecisions.sdk.framework.IEnterpriseSession;
import com.crystaldecisions.sdk.occa.infostore.IInfoObjects;
import com.crystaldecisions.sdk.occa.infostore.IInfoStore;
import com.crystaldecisions.sdk.occa.infostore.internal.InfoStoreFactory;
import com.crystaldecisions.sdk.occa.security.internal.ISecuritySession;
Step #3 – Your class must be a subclass of AbstractProbe and it must also implement the IHealthProbe interface so that it will inherit the required methods and objects needed for a probe
public class probeHTTP extends AbstractProbe implements IHealthProbe
{
Step #4 – Initialize a new IProbeInfoObject and invoke the constructors of IProbeInfoObject. You will need this object to get access to the input parameters later.
public IProbeInfoObject probeObject = null;
public probeHTTP(IProbeInfoObject probeInfoObject)
{
super(probeInfoObject);
probeObject = probeInfoObject;
}
Step #5 – You must create an executeHealthProbe method which returns IHealthProbeResult for a health probe. For a diagnostic probe, it must return IDiagnosticProbeResult. Notice that when the probe is executed, the Enterprise session is passed in by the Probe Scheduling Service (Adaptive Job Server). You can use this Enterprise session to access the CMS Infostore so that you can perform actions on the BI Platform (such as query the CMS repository for metrics, start servers, change settings, etc).
public IHealthProbeResult executeHealthProbe(IEnterpriseSession session)
{
HealthProbeResult probeResult = new HealthProbeResult(getProbeInfoObject());
Socket socket = null;
boolean available = false;
Step #6 – To parameterize your probe you need to create a new java.util.Map object. Call getInputParameters( ) to create a map of the probe parameters that have been selected by the administrator in the Central Management Console (see Step #4). In this example, there are two parameters (Web Server Host Name, Port Number)
Map<String,Object> inputParams = null;
try
{
inputParams = probeObject.getInputParameters();
}
catch(Exception e)
{
System.err.println(e);
e.printStackTrace();
}
String hostname = (String) inputParams.get(“hostname”);
String portnum = (String) inputParams.get(“portnum”);
int portnumint = Integer.parseInt(portnum);
Step #7 – This example attempts to create a connection to the specified host and port number. If it succeeds, our probe executes probeSucceeded( ). If it fails, an exception is thrown and the probe executes probeFailed( ). The probeResult specifies to the Probe Scheduling Service if the health probe itself was a success or failure.
try
{
//String, int
socket = new Socket(hostname, portnumint);
probeResult.probeSucceeded();
}
catch (Exception e)
{
probeResult.probeFailed();
}
return probeResult;
Compile and register your probe
- Add the required jar files to your CLASSPATH. I have attached my CLASSPATH to this document as an example (classpath.txt). The BI 4.0 Java SDK libraries are located in the directory <BOBJ_HOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib.
- Compile your Java class and export it from Eclipse as a jar file.
- Create a folder named probes in the directory <BOBJHOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib.
- Add your custom jar and it’s dependencies to the new probe directory.
- Restart the Monitoring Service (Adaptive Processing Server) and Probe Scheduling Service (Adaptive Job Server)
- Repeat steps 3,4, and 5 for each node running the Monitoring Service and Probe Scheduling Service
- Register your custom probe as per the BI4 Java SDK Developer’s Guide or via the Central Management Console > Monitoring Application.
- During registration, specify the class name including the package name as com.businessobjects.monitoring.probe.yourClassName.
- Configure the input parameters to match the name and data type as defined in the java.util.Map in your source code.
- For an example, refer to Image A
Image A
Schedule the custom probe
- In the Central Management Console browse to Monitoring > Probe tab and locate your new probe.
- Right click on the probe and choose properties then check your input parameters (Image B)
- Schedule the probe to Run Now and see the results (Image C and Image D)
Image B
Image C
Image D
Good work Toby ... the HTTP test is a good example but what real life applications of this can we think of?
Thanks for the comment Jim.
This is meant to be more of an example (or template) for you to make your own probe.
However, this could be used to monitor the availability of the webservers in your cluster. Deploy one probe for each webserver and set a watch to send an alert if the probe fails. You could also use this to monitor the listening port for any process, not just webserver since it is using a simple TCP socket connection to test the availabilty of a listening port, not testing HTTP specifically (like the InfoView probe does for example)
Thanks for the write up, it's nice to finally see some official documentation on this process. Unfortunately I ran into a slight problem with the probe deployment:
The procProbe jar file is signed so adding .class files to the jar results in intermittent java.lang.SecurityException failures across the probes held within that package. To resolve this I had to remove the signatures from the manifest file of jars containing classes with overlapping packages for com.businessobjects.monitoring.probe i.e. procProbe.jar, probe-CR.jar and probe-Webi.jar
This does make me wonder whether the proposed deployment process for custom java probes is just a ‘hack’ that’s been employed to cater for a shortfall with the class loading mechanism for custom java probes?
Do you know if there are any plans to tidy/simplify this deployment process? Ideally the entire deployment of a custom probe should be handled through the CMC i.e. specify the classpath and upload our own bundled jar.
Hi James,
Thanks for your comment. I will answer your questions inline:
The procProbe jar file is signed so adding .class files to the jar results in intermittent java.lang.SecurityException failures across the probes held within that package. To resolve this I had to remove the signatures from the manifest file of jars containing classes with overlapping packages for com.businessobjects.monitoring.probe i.e. procProbe.jar, probe-CR.jar and probe-Webi.jar
[Toby Johnston] Interesting, I did not run into this problem. See below.
This does make me wonder whether the proposed deployment process for custom java probes is just a ‘hack’ that’s been employed to cater for a shortfall with the class loading mechanism for custom java probes?
[Toby Johnston] It is indeed a workaround to make things work in the short term. See below again 🙂
Do you know if there are any plans to tidy/simplify this deployment process? Ideally the entire deployment of a custom probe should be handled through the CMC i.e. specify the classpath and upload our own bundled jar.
[Toby Johnston] Actually, you can indeed use your own jar file instead of procProbe.jar. To do this, create a folder named probes in the directory <BOBJHOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib. Add your custom jar and it's dependencies to this directory. Then register your probe as normal in the CMC. I will be updating this documentation soon to use this deployment method instead.
If you have more questions, please let me know!
Thanks
Toby
You might be able to replicate the security exception by scheduling your custom probe along with the default (signed probes) at regular intervals e.g. every couple minutes. Effectively you need to attempt to load signed and unsigned classes (in the same package) at the same time.
Regarding the jar deployment.....I went down this route originally but failed to get it to work. It could be I didn't use the com.businessobjects.monitoring.probe package. I'll have to retest but I know I ran into issues and then came across SAP Note: 1835599
Look forward to the update.
Cheers
James
Hi James,
There was a typo in the guide, it said Probes instead of probes. It isnt necessary to name your package com.businessobjects.monitoring.probe package however you need to make sure your jar has the folder structure that matches your package. For example com.toby.probe would be com/toby/probe/probe.class.
I'm currently on the road teaching BI4 Elite Enablement but will update this as soon as possible.
Thanks
Toby
Hi Toby,
The above scenario is well visible if you try to add more dependent JAR in manifest file Class-Path attribute . Otherwise everything is working fine. I think it happens because SHA1-Digest-Manifest: property getting invalidated with change in manifest file.
I think it is better to add James info also in note.
Thank You Lot For This Amazing Note.
Thanks,
shibin
Fore more info
Understanding Signing and Verification (The Java&trade; Tutorials &gt; Deployment &gt; Pa…
Hi Shibin,
I meant to change this a while ago but I have since fixed the document. You should export your probe to JAR file from Eclipse. Then add it to the custom probes directory. Refer to the refreshed article.
Thanks
Toby
Hi Toby,
Thank for fast reply.
Thanks,
Shibin
Very interesting !
Thanks for that document.
Regards
Hi Toby,
We have a requirement to monitor user Logins of CMC.
We have assistant Admin group who can login to CMC if main Administrator is not available.
With default BI Launchpad probe we can monitor user Logins of BI Launchpad.
In the same way can we monitor CMC logins?
I Just tried to change the url base from http://BOserver:8080/BOE/BI to http://BOserver:8080/BOE/CMC in BI Launch Pad probe Properties.
After that I ran the probe but its failing.
Could you please let me know if there is any work around or is there any way we achieve this.
Thanks in Advance
Kumar
Hey Kumar,
Probe's aren't really used to monitor a particular user's logon. Instead, Probes are used to simulate a user's logon in order to test if that webapp or service is available. If the probe fails, then it means there is a system outage and usually an alert will be configured to email the administrator.
If you want to monitor user logons to the CMC and keep a record of this access, I would recommend checking the auditing database for this. I believe you should be able to filter based on which application the user logged on to the CMS with.
I'll check on this specific detail and get back to you.
If this is not what you are after and I am misunderstanding you then please let me know
Thanks
Toby
Thank you very much Toby for your response.
The requirement is once assistant admin login to CMC, needs to be send an email alert immediately saying that particular user logged to CMC application at particular time from Particular system including capture the IP address of his machine from where he logged into CMC.Capture IP address is not mandatory.
Thanks,
Kumar
Hi Kumar,
You could accomplish this by creating a probe that runs as a recurring schedule at an interval of your choosing. In the probe, query the audit database and determine which users have logged onto the CMC and then send email alert if any CMC logons were detected
I had a look at the auditing database schema and I think you will be able to tell which logon events are triggered by the CMC by filtering on the field ADS_AUDITEE.Application_Type_ID. I havent specifically tested this but looking at the schema it looks possible to understand where the logon came from.
ADS_AUDITEE.Application_Type_ID Character (64)
The application-type CUID for the client that triggered the event. For server events, the ID of the service-type will be recorded.
I hope it helps get you in the right direction 🙂
Thanks
Toby
Check page 1023 in the BI Platform Admin Guide for more info on the Auditing database
http://help.sap.com/businessobject/product_guides/sbo41/en/sbo41sp2_bip_admin_en.pdf
Hi Toby,
Thanks for your inputs.
Can you please let me know where Can I find BI Launchpad probe code.
I would like to create probe for CMC with similar functionality of BI Launchpad probe.
Thanks,
Kumar
Hi Toby,
nice post, I am trying do develop my own set of probes for various different purposes. My question is a bit more an enhancement of this topic - under BI 4.X it is possible to monitor/communicate with the application via JMX/RMI protocol. When I connected BI 4 environemnt to JConsole I saw that the default probes (available out of the box) are also available among the MBeans and you can actually work with them like sending their output to monitoring application, etc. Now, if I create my own probe - will the new custom probe be also available in JConsole or in other words - is the BI4 application going to create corresponding MBean for my custom probe depending on its type (factory pattern, etc.)?
Thanks.
Erik.
Hi Erik,
Yes this is definitely possible. In the case of Solution Manager, Introscope actually connects and retrieves metrics from the Monitoring Service via JMX in the exact same way. Also, if you check under CMC-->Applications-->Monitoring you will find the customizable JMX URL which is designed for custom monitoring applications to connect and retrieve metrics.
Regarding your question, yes when you create a new custom probe, it creates a new mbean which would then appear in your JMX directory similar to the other probes.
Cheers
Toby
Hi Toby,
thanks for the answer. I know about the Introscope Agent and Solution Manager - for my current purposes it is a bit an overkill but they are definitely the enterprise solutions to go with 🙂 To avoid agony and hopelessness with noclassdeffounderror or Adaptive Job server problem when running custom probes I recommend the following note - http://service.sap.com/sap/support/notes/1835599, especially point 1 was the crucial one for me.
Erik.
Hey Erik,
Yes, I wrote that note too so I am familiar with it 🙂
Cheers
Toby
Hi Toby,
OK, I would assume so:) If I may get back to the JMX functions - it seems there is one critical gap in those - I have no ability to "tell" the MBeans factory to create custom attributes and operations for parameters which I want them to return. For example a diagnostic probe should have a textual output which I am not able to pass to any higher monitoring tool without creating my custom attribute and respective getter in the particular MBean. Is there a way to create own attributes and operations [for example by creating getters in the probe which would be picked up by MBean factory and reflected in the bean itself]? If not, it would be very disappointing,..
Erik.
Hi Erik,
Sorry I'm short on time at the moment and can't test this right now but have you tried connecting JConsole to the JVM of the Monitoring APS? In JConsole, click on the MBeans tab and you can use this as a reference for understanding the names of the MBeans and what type of values they return.
I've got some JMX code for another application I've been working on, when I have a moment I'll try to adapt this and see if I can get it working for APS.
Regards
Toby
Not sure if you saw this but you can also use your own custom jar file (not procProbe.jar). See below:
To do this, create a folder named probes in the directory <BOBJHOME>\SAP BusinessObjects Enterprise XI 4.0\java\lib. Add your custom jar and it's dependencies to this directory. Then register your probe as normal in the CMC.
Hi Toby,
thanks for the answers. Anyway, I think I perhaps wasn't exact before and caused some misunderstanding. What I actually wanted to say is that I am not able to define my own attributes for the MBeans. In other words - lets say I have a custom probe which is of type Hybrid and it indeed returns some value via StringBuffer which is displayable in CMC > Monitoring > Probes > Select History of the probe > Left click on the Run result. However, no matter how hard I tried, the MBean created by BO platform for my probe (or any other probe) contains always only 2 attributes (passed and executiontime) AND 3 Operations (getAttribute, refresh and managedEntityId). This is very limited because all I can return is basically true or false, without any values.
In conclusion, if I want to monitor some exact attribute of the application via my custom probe in the same way like the pre-programmed return values for any APS (approximately 30) I can't get access to these values and pass them forward to the monitoring tool because there is apparently no interface/implementation which would handle these.
Erik.
Hi Erik,
Sorry, I see what you are saying now. It may be some time but I will look into this when I go to refresh the custom probe documentation. I may run it past the product owner and see if another method could be added for custom attributes on the MBean.
In the meantime, it may be possible for you to store this information in the CMS database as a custom InfoObject. Not sure if that really helps you or not but if it does I can provide some sample code on how to do that.
Thanks
Toby
Hi Toby,
great, thanks. If you can check it that would be perfect. Also knowing how to save my custom value to CMS database could be useful.
Erik.
Hi Erik,
I sent you a pm with a code sample
Thanks
Toby
Hi Toby,
any update on custom attributes in probes?
Thanks;) Erik.
Hi Toby,
We have a requirement to refresh the Dashboard daily before our Business use them because we want to maintain the cache and reduce the delay/performance issues as our servers are refreshed every weekend. We are trying to create a Probe for Dashboard and schedule it daily before our Business start.
Can you help/guide us to develop the Probe for Dashboard, we will create a ticket where we can log the work procedure.
Regards,
SJ
Hi SJ,
This is something that I think would be worth doing however at the moment I have some other projects which require my full attention. This may be possible to do for me in the next month or two.
I would refer to the BI Platform API guide and samples, and then use my provided sample as a basis. Then just update the existing method (TCP connection to Tomcat) with a call to view the dashboard.
I'll post back again on SCN with a sample when I get to it.
Regards
Toby
Hi Toby,
Thanks for replying back, sure I will wait and in the meantime will also try to work on it.
Regards,
SJ
Hi Toby,
Did you get a chance to look into our requirement?
Regards,
SJ
Hi Toby,
Any luck in creating the Probe for Dashboard?
Regards,
SJ
Hi Toby,
Is there a way we can have a probe restart tomcat service? What i am trying to do is, we usually get a lot of concurrent users logging in and not logging out, but before they are timed out our users get messages that they cant login and then i always have to restart tomcat to clean all the sessions to start fresh.
This is my question's link:
I want to be able to create a watch that will count my concurrent users then set that to lets say 100 and then create an alert which will then fire the probe to restart the tomcat. Is there a way? Thanks
Sure, you could do this.
Check out the following post I found via google. It has a sample API for restarting Tomcat
java - Connect to remote server and start/stop the Tomcat that&#39;s running on that particular server using Ant? - …
Thanks Toby for your Reply
SJ
Toby, this is very useful, thanks.
Do you have examples of passing back virtual metrics? I've figured out how to do it from a scrip-based probe, but not from a Java probe. I've found IHealthProbeResult.setProbeMetrics(), but it doesn't appear to work as I'd expect.
Hi Toby,
Do you still have the sample code that was originally attached to this blog post?
Hi Toby,
I too am hoping to find the sample code that was originally attached to this blog post, along with your example classpath used to compile the code.
Thanks!
Dave Hays