db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Db-derby Wiki] Update of "DerbyJMX" by JohnHEmbretsen
Date Thu, 27 Mar 2008 12:51:01 GMT
Dear Wiki user,

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

The following page has been changed by JohnHEmbretsen:
http://wiki.apache.org/db-derby/DerbyJMX

The comment on the change is:
Added quick start info for JConsole

------------------------------------------------------------------------------
  
  This page describes Derby's JMX extensions, a new feature set being developed for the first
10.4 release and beyond.
  
- [[TableOfContents]]
+ [[TableOfContents(2)]]
  
  = Jira issues =
  
@@ -111, +111 @@

  
  You start Derby by loading Derby's embedded driver. If you are using Derby's Network Server,
the embedded driver is automatically loaded in the server JVM when the server is started.
  
- Basically, Derby's JMX features consist of a set of MBeans (Managed Beans) and their attributes
and operations. MBean implementations instrument one or more parts of a running Derby system,
potentially giving you real-time access to Derby-specific information from a host of your
choice. The word ''potentially'' here indicates that JMX access may depend on how you configure
your JVM and (for example) Derby's security features.
+ In short, Derby's JMX features consist of a set of MBeans (Managed Beans) and their attributes
and operations. MBean implementations instrument one or more parts of a running Derby system,
potentially giving you real-time access to Derby-specific information from a host of your
choice. The word ''potentially'' here indicates that JMX access may depend on how you configure
your JVM and (for example) Derby's security features.
  
  Note that if you are unfamiliar with JMX technology, it may be a good idea to take a look
at some of the references provided [#Resources above] before you continue. 
  
  You may access Derby's MBeans using for example an existing JMX client utility, such as
JConsole, or programmatically by writing your own Java code utilizing JMX.
  
+ == Enabling JMX ==
+ 
+ '''Note:''' In the following, ''local'' basically means ''on the same host (machine)'' and
''running as the same user''. For example, this means that local JMX access is possible only
if the JVM you want to access is running on the same host and as the same user as the user
running JConsole (or a different user with sufficient file system permissions). In order to
allow other users to access the JVM, or to allow access from other hosts, remote JMX must
be enabled.
+ 
+ === Local JMX access ===
+ 
+ If you are using a Java SE 6 JVM, local JMX management and monitoring is most likely enabled
by default. 
+ 
+ Some JVMs, for example J2SE 5.0 JVMs, do not enable local JMX management by default. Refer
to the documentation for your JVM for details. It seems that the de-facto standard way to
enable (local) JMX access is to include `-Dcom.sun.management.jmxremote` on the command line
when starting the JVM.
+ 
+ === Remote JMX access ===
+ 
+ Remote JMX management and monitoring is a powerful Java feature, letting you monitor a specific
JVM from a remote location. Enabling remote JMX requires explicit actions by the JVM administrator
(you), since it may involve exposing sensitive information about your JVM or application.
+ 
+ The most common way to enable remote JMX access to your JVM is to specify a TCP/IP port
number and some basic security (authentication, SSL  (Secure Sockets Layer)) settings when
starting the JVM. For a list of (seemingly de-facto standard) command line options (system
properties) and their meaning, refer to the [http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html#gdeum
Java SE Monitoring and Management Guide], the [http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html
Platform Monitoring and Management guide for J2SE 5.0], or your JVM's documentation.
+ 
+ The following example starts the Derby Network Server on the command line with (insecure)
remote JMX management and Monitoring enabled, using the JVM from Sun's JDK 6. Password authentication
over SSL is enabled by default, but in this example these security features are disabled,
to keep the example simple. '''It is not recommended to disable authentication or SSL in production
environments'''.
+ 
+ {{{
+ java -Dcom.sun.management.jmxremote.port=9999
+ -Dcom.sun.management.jmxremote.authenticate=false
+ -Dcom.sun.management.jmxremote.ssl=false 
+ -jar lib/derbyrun.jar server start
+ }}}
+ 
+ Refer to the above mentioned documentation for information about enabling JMX security features.
+ 
+ === Security policy ===
+ 
+ When starting the Derby Network Server from the command line, it installs a basic security
policy by default. This policy includes the required permissions to allow authenticated JMX
users to access Derby's MBeans. 
+ 
+ If you are using a custom security policy, refer to the [http://db.apache.org/derby/javadoc/publishedapi/
public API] of Derby's MBeans and Derby's template security policy file ($DERBY_HOME/demo/templates/server-policy)
for details about the permissions you may need to set to allow or restrict specific JMX access.
See also ["JMXSecurityExpectations"].
+ 
  == Using JConsole to access Derby's MBeans ==
  
- Add quick start info here...
+ JConsole is a graphical JMX-compliant tool originally developed by Sun Microsystems, and
is available in recent versions of Sun's Java Development Kits (JDKs). JConsole enables you
to monitor and manage Java applications and virtual machines on a local or remote machine.
+ 
+ Note that you may use JConsole from JDK 6 even if you are running Derby using JDK 5.0 (or
just the JRE), or vice versa. It is recommended that you use the newest version possible.
More information about JConsole is available [http://www.openjdk.org/tools/svc/jconsole/index.html
in the Java SE Monitoring and Management Guide] and [http://openjdk.java.net/tools/svc/jconsole/
in the OpenJDK project].
+ 
+ === Starting JConsole and connecting to Derby ===
+ 
+ In Sun's JDK 5.0 and JDK 6, the JConsole binary is available in the `bin` directory of `JDK_HOME`,
where `JDK_HOME` is the directory in which the JDK is installed. You can simply start JConsole
by running the `jconsole` executable, for example (Unix):
+ {{{
+ /usr/local/java/jdk1.6.0/bin/jconsole
+ }}}
+ 
+ A graphical user interface (GUI) should appear. For additional startup options, refer to
the references mentioned above.
+ Once the GUI starts, you will be presented with a list of JVMs that are accessible on the
local host. Locate the JVM running Derby in that list and connect to it.
+  * If you want to connect to a JVM on a remote host, you will need to supply the host name
and port number, or a JMX service URL, instead.
+  * If you cannot find the Derby JVM running on the local host, make sure you are running
JConsole as the same user as the Derby JVM, or a different user with sufficient file system
permissions. Also make sure you have enabled JMX if using J2SE 5.0. When using Java SE 6,
local JMX access is enabled by default.
+ 
+ === Accessing MBeans ===
+ 
+ Once connected to a JVM via JConsole, the JVM's MBeans should be available on a separate
tab in the internal JConsole window. Under the domain "org.apache.derby" you should see a
list of MBeans. Browse the MBeans and their attributes and operations by navigating the hierarchy
presented.
+ 
+ Below is a screenshot showing how JConsole (from JDK 6) presents the attributes if the NetworkServerMBean
(requires that the Network Server has been started).
+ 
+ inline:nserverAttribsJConsole.png
+ 
+ Another useful JConsole feature is that you can view dynamic data represented as JMX attributes
as graphs. You may view these graphs by double clicking an attribute value that is a number
(in '''bold''' in the screenshot above). The partial screenshot below shows some of the attribute
values of the NetworkServerMBean as graphs, after the Network Server has been running with
some load.
+ 
+ inline:nserverGraphJConsole.png
+ 
  
  == Accessing Derby's MBeans using custom Java code ==
  
  Add quick start info here...
  
+ ----
+ 
+ [[AttachInfo]]
+ 

Mime
View raw message