hivemind-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Jakarta-hivemind Wiki] Update of "JmxDoc" by AchimHuegen
Date Tue, 17 May 2005 16:20:05 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jakarta-hivemind Wiki" for change
notification.

The following page has been changed by AchimHuegen:
http://wiki.apache.org/jakarta-hivemind/JmxDoc

The comment on the change is:
JMX library included in Hivemind 1.1

------------------------------------------------------------------------------
- AchimHuegen, Feb 26 2005
+ deleted
  
- This page describes HiveMinds support for the Java Management Extension (JMX).
- JMX support is not currently available in the official 1.1 alpha release but hopefully
- will be included soon.
- 
- = How to get started =
- 
- For the impatient ones, that just want to get up anything to play with 
- here are some [#QuickStart quick start instructions].
- For a more complete introduction read on [#Intro here]
- 
- [[Anchor(QuickStart)]]
- == J2SE 1.4 / Tomcat 5.0.x - Quickstart ==
- 
- Add these lines to your (web) application's hivemind descriptor:
- 
- {{{
-   <contribution configuration-id="hivemind.EagerLoad">
-     <load service-id="hivemind.management.MBeanRegistry"/>
-   </contribution>
- 
-   <contribution configuration-id="hivemind.management.MBeans">
- 	<mbean service-id="hivemind.management.connector.HttpAdaptorMBean" start-method="start"
/>
- 	<mbean service-id="hivemind.management.log4j.LogManagementMBean" />
-   </contribution>
- 
-   <contribution configuration-id="hivemind.management.log4j.ManagedLog4jLoggers">
-   	<logger name="hivemind.*" />
-   </contribution>	  
- 
- }}}
- 
- Ensure that mx4j.jar, mx4j-tools.jar (mx4j 2.x) and log4j.jar are included in the classpath
of your application. Start your application/tomcat and enter http://localhost:9000 in your
browser. Read on [#QuickStartResults here]
- 
- == J2SE 1.5 - Quickstart ==
- 
- J2SE 1.5 already includes jmx support and brings along a management console (jconsole).
- Add these lines to your application's hivemind descriptor:
- 
- {{{
-   <contribution configuration-id="hivemind.EagerLoad">
-     <load service-id="hivemind.management.MBeanRegistry"/>
-   </contribution>
- 
-   <contribution configuration-id="hivemind.management.MBeans">
- 	<mbean service-id="hivemind.management.log4j.LogManagementMBean" />
-   </contribution>
- 
-   <contribution configuration-id="hivemind.management.log4j.ManagedLog4jLoggers">
-   	<logger name="hivemind.*" />
-   </contribution>	  
- 
- }}}
- 
- Ensure that mx4j.jar (mx4j 2.x) and log4j.jar are included in the classpath of your application.
Start the application with -Dcom.sun.management.jmxremote
- 
- {{{
- java -Dcom.sun.management.jmxremote ...
- }}} 
- 
- start jconsole and connect to the local application.
- 
- [[Anchor(QuickStartResults)]]
- == Quick start results ==
- 
- What you get from the quick start is the ability to manage the Log4j loggers used by the
hivemind framework. Look for MBeans in the "hivemind" domain of type "logger". 
- For example: hivemind:module=hivemind,type=logger,id=BuilderFactory.
- 
- You can change the log level (priority) and add appenders without restarting 
- the application.
- 
- [[Anchor(Intro)]]
- = Tutorial =
- 
- This chapter describes more detailed how to build jmx support into your hivemind application.
- Actually it's just plug and play. There are a lot of default services and settings that
may be sufficient for your use case.
- You will need a MBean server, at least one connector and of course some beans to manage.
- But first:
- 
- == Choose a jmx implementation ==
- 
- As far as I can tell there are three implementations of jmx 1.2 that are freely available.
[http://mx4j.sourceforge.net MX4J], [http://java.sun.com/j2se/1.5.0/ J2SE 1.5] and the [http://java.sun.com/products/JavaManagement/download.html
Sun reference implementation]. I would suggest to use MX4J if you don't have the chance of
using J2SE 1.5.
- 
- Since HiveMind MBeans use MX4J AbstractDynamicMBean as ancestor the mx4j.jar (MX4j 2.x)
is _always_ needed in your classpath. Be sure to put it behind the SUN jars in the classpath
if you use Sun RI!
- 
- === MX4j ===
- 
- Add mx4j.jar, mx4j-tools.jar to the classpath. 
- Add mx4j-remote.jar if you use JSR 160 connectors.
- 
- === J2SE 1.5 ===
- 
- No additional libraries needed.
- 
- === Sun RI ===
- 
- Add jmxri.jar and jmxtools.jar to the classpath.
- 
- == MBean Server ==
- 
- A running MBean Server is needed in your application. Since JMX 1.2 there is a standardized
factory for finding running servers and starting new ones.
- HiveMind first tries to find a running server. This could be provided by an application
server or servlet engine (like Tomcat 5) or your J2SE 1.5 runtime environment. Add these lines
to your module descriptor:
- 
- {{{
-   <contribution configuration-id="hivemind.EagerLoad">
-     <load service-id="hivemind.management.MBeanRegistry"/>
-   </contribution>
- }}}
- 
- Connecting to a running server results in a unified management of infrastructure mbeans
(from tomcat or J2SE 1.5) and your applications mbeans. If no running server has been found,
a new one is started. 
- 
- == Connectors ==
- 
- There are different ways to connect to a jmx enabled application. HiveMind offers preconfigured
support for HTML and JSR 160 connectors. 
- 
- == HTML Connector ==
- 
- The HTTP Connector renders HTML pages for the remote management.
- Setup and configuration are specific to the jmx library you are using (that is J2SE 1.5,
Sun RI, MX4J). 
- 
- === MX4J HTML Connector ===
- 
- Enable the MX4J HTML Connector by including these lines in your descriptor:
- 
- {{{
- <contribution configuration-id="hivemind.management.MBeans">
-    <mbean service-id="hivemind.management.connector.MX4JHttpAdaptorMBean" start-method="start"
/>
- </contribution>
- }}}
- 
- The default HTTP Port is 9000 and can be changed this way:
- 
- {{{
- <contribution configuration-id="hivemind.ApplicationDefaults">
-   <default symbol="management.http.Port" value="9000" />
- </contribution>
- }}}
- 
- Now you can connect to your application using a standard browser pointing to http://localhost:9000.
- 
- === SUN HTML Connector ===
- 
- Enable the SUN HTML Connector by including these lines in your descriptor:
- 
- {{{
- <contribution configuration-id="hivemind.management.MBeans">
-    <mbean service-id="hivemind.management.connector.SunHttpAdaptorMBean" 
-       start-method="start" />
- </contribution>
- }}}
- 
- The port is configured like described for MX4J.
- 
- === J2SE 1.5 and Http Connector ===
- 
- There is no Http Connector provided with J2SE 1.5. But you can combine the MX4J or Sun RI
HTTP Connectors with J2SE 1.5. Just include the xxx-tools.jar in the classpath and setup the
connector like described above.
- 
- == JSR 160 Connector ==
- 
- JSR 160 connectors allow the remote management of the application using any management console
that supports the standard (like JConsole, MC4J).
- The connectors are created by a standardized api so there is no implementation specific
setup like with HTTP Connectors. The standard allows use of different protocols for the remote
management. Most common is a RMI protocol and this is what HiveMind supports in the moment.
- It requires a running RMI Registry. Add these lines:
- 
- {{{
- <contribution configuration-id="hivemind.management.MBeans">
-    <mbean service-id="hivemind.management.connector.NamingServiceMBean" 
-       start-method="start" />
-    <mbean service-id="hivemind.management.connector.JMXConnectorServerMBean" 
-       start-method="start" />
- </contribution>
- }}}
- 
- Now you can connect to the application with jconsole or MC4J using this url:
- service:jmx:rmi://localhost/jndi/rmi://localhost:1099/jmx.
- 
- You can change RMI port and url:
- {{{
- <contribution configuration-id="hivemind.ApplicationDefaults">
-   <default symbol="management.namingservice.port" value="1099" />
-   <default symbol="management.jmxconnector.ServiceUrl" 
-       value="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/jmx" />
- </contribution>
- }}}
- 
- Ensure that those port numbers are equal.
- 
- http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html
- 
- === J2SE 1.5 local connector ===
- 
- Local management with jconsole is possible without adding any connector.
- Simply set the system property com.sun.management.jmxremote before launching your app.
- 
- {{{
- java -Dcom.sun.management.jmxremote ...
- }}}
- 
- Connect with JConsole using the 'local' tab on the connection dialog.
- 
- == Export services as MBeans ==
- 
- Services can be registered as MBean very easily by a contribution to "mbeans":
- {{{
- <contribution configuration-id="hivemind.management.mbeans" >
-     <mbean service-id="test.management.Calculator" />
- </contribution>
- }}}
- 
- Now the complete service interface is available via jmx.
- (There are some datatype constraints and the servicemodel should be primitive or singleton)
- 
- == Performance interceptor ==
- 
- The interceptor PerformanceMonitor collects statistical data about calls to the intercepted
service.
- The results are sent to a newly created mbean. For each service method it displays: number
of calls, maximum, minimum, average and last execution duration.
- 
- Add the Interceptor to your service:
- {{{
- <service-point id="Calculator" interface="org.apache.hivemind.management.Calculator">
-    <invoke-factory>
-       <construct class="org.apache.hivemind.management.CalculatorImpl" />
-    </invoke-factory>
-    <interceptor service-id="hivemind.management.PerformanceMonitorFactory">
- 	  <exclude method="getSum"/>
- 	  <include method="add"/>
- 	  <include method="subtract"/>
-    </interceptor>
- </service-point>
- }}}
- 
- The statistics are displayed by a MBean named like your service, with an additional name
part "decorator=PerformanceCollector".
- 
- == Monitor ==
- 
- Though creation of jmx monitors is not automated a monitor can easily defining as service
point using the standard builderfactory functionality.
- Such a monitor can watch the attribute of another mbean (for example the average execution
time of a service method) and 
- send notifications, if a treshold is crossed.
- 
- The mbean test.management.service.CalculatorSumMonitor monitors the sum attribute of the
calculator service (attribute DerivedGauge).
- 
- {{{
-   <service-point id="CalculatorSumMonitor" interface="javax.management.monitor.GaugeMonitorMBean">
-     JMX Monitor that monitors the attribute Sum of the Calculator service
-     <invoke-factory model="primitive" >
- 	   <construct class="javax.management.monitor.GaugeMonitor" >
- 	   	 <set property="granularityPeriod" value="1000" />
- 	   	 <set property="observedObject" value="HiveMind:module=test.management,type=service,id=Calculator"
/>
- 	   	 <set property="observedAttribute" value="Sum" />
-        </construct>	
-     </invoke-factory>  	
-   </service-point>
- }}}
- 
- == Multiple applications in one JVM ===
- 
- todo ..
- 
- = Implementation details =
- 
- == Dependencies ==
- 
- The implementation uses JMX 1.2 and supports JSR 160 for remote management (via jconsole,
mc4j etc.)
- It is depending on MX4J but is working fine with Sun RI and J2SE 1.5 too.
- The dependency could be broken up, but there is no standardized way for creating an HTMLAdaptor.
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 

---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-cvs-help@jakarta.apache.org


Mime
View raw message