1 #============================================================================== 2 # JVM Management MIB - Instrumentation Classes 3 #============================================================================== 4 5 In this directory: 6 ------------------ 7 8 README: this file 9 commands.env: a file containing some ksh variables & functions 10 that I have used to generate & compile all the 11 stuff. Probably only valid in my own environment. 12 logging.properties: logging.properties file that can be used to obtain 13 trace information. 14 *.java: utility and custom classes for the JVM Management MIB. 15 These classes show how to provide instrumentation for 16 a mibgen generated MIB, how to simulate virtual tables, 17 and how to make use of the SnmpUserDataFactory. 18 Only the jvmMemory group and its tables are instrumented. 19 20 Dependency 21 ---------- 22 23 jvmManagementMib.txt : the JVM Management MIB module in compilable form. 24 Tiger SNMP Runtime : SNMP Runtime classes for Tiger. We assume these 25 classes could be part of the JMX delivery 26 (classes in com.sun.jmx.snmp.*) 27 JDMK 5.1 : The jdmktk.jar contains the com.sun.jdmk.tools.MibGen class 28 used to compile the MIB. JDMK also has a mibgen.sh script 29 to start mibgen. By default mibgen generates code that can 30 integrate with JDMK SNMP runtime. In order to generate 31 code that integrate with Tiger SNMP runtime, you need to 32 start mibgen with a non-default resource file. 33 JDMK 5.1 workspace contains a mibgen resource file 34 specific for tiger: mibgen.property.tiger 35 Custom Instrumentation Code: the files in this directory. 36 37 How to proceed: 38 --------------- 39 40 Get mibgen from JDMK 5.1. Start mibgen with mibgen resource file for 41 tiger (add -Dcom.sun.jdmk.tools.mibgen.config.file=<mibgen.properties.tiger>) 42 on the Java command line. 43 44 Use mibgen to generate code for the jvmManagementMib.txt file. Note that 45 the custom classes provided in this directory are all in the 46 sun.management.snmp.jvminstr package, and expect the generated classes to 47 be in another sun.management.snmp.jvmmib package (use mibgen option 48 -tp sun.management.snmp.jvmmib) 49 50 If this package name does not suit you, simply change it to something else, 51 both in the custom classes below (you might use 'sed' or do it manually) 52 and in the -tp option that you will pass to mibgen. 53 54 It is recommended to generate all classes in a different directory (if 55 you read command.env you will see that I have put the custom classes 56 in a "custom" directory, and the generated classes in a "parsed" 57 directory. This makes it easier to cleanup the mib. You can safely 58 do a rm -rf <parsed> and call mibgen again. 59 60 Then compile the generated classes - you will need JMX and Tiger SNMP 61 runtime classes in your classpath - if you compile with a tiger build that 62 already have them then you don't need to specify anything special. 63 64 Then make your classpath point to the compiled generated classes, and 65 compile the custom code in this directory. 66 67 Then you can use the SnmpDaemonTest class to start a JVM with the 68 intsrumented MIB, and you can use e.g. the easymanager contrib of 69 JDMK to view the MIB through SNMP. 70 71 #============================================================================== 72 # Classes Details 73 #============================================================================== 74 75 Utility Classes developped for the JVM Management MIB: 76 ------------------------------------------------------ 77 JvmContextFactory.java : The context factory allocates a Map that 78 serves as request contextual cache. 79 Values obtained from JSR 163 API can be 80 cached in this object. 81 A request contextual cache is allocated 82 each time a request is being processed, 83 and is released at the end of processing. 84 Object: 1) preserve atomicity 85 2) minimize API calls 86 3) ensure consistency of the 87 various pieces of data returned. 88 89 MibLogger.java : Send traces to java.util.logging 90 91 SnmpTableHandler.java : an interface used to access table data. 92 93 SnmpCachedData.java : This object can be use to cache a snapshot 94 of the data contained in a table. 95 96 SnmpTableCache.java : A weak cache for table data. The data is 97 computed on demand and cached in a 98 weakreference. Makes it possible to specify 99 a validity period for the cache data. 100 101 SnmpListTableCache.java : Extends SnmpTableCache - for tables whose 102 data is returned in a List object. 103 104 SnmpNamedListTableCache.java : Extends SnmpListTableCache - for tables whose 105 elements can be named by a unique string. 106 107 SnmpDaemonTest.java : A dummy standalone SNMP agent that registers 108 the JVM Managemnt MIB in Tiger's SNMP 109 adaptor. This is the "main". Note that 110 this not the class that will be used to 111 start the adaptor in the final Tiger - it is 112 just a dummy test main. 113 114 JVM Management MIB 115 ------------------ 116 117 JVM_MANAGEMENT_MIB_IMPL.java : subclasses the generated JVM_MANAGEMENT_MIB 118 class. 119 Object: overriding factory method in order 120 to instantiate custom code instead 121 of generated code. 122 123 124 JVM Memory Group 125 ---------------- 126 127 JvmMemoryImpl.java : Provides instrumentation for the jvmMemory 128 group. Replaces the generated JvmMemory class, 129 which is not used and can be thrown away. 130 Implements the generated JvmMemoryMBean 131 interface (which was also implemented by 132 the generated JvmMemory skeleton class) 133 Use the request contextual cache 134 in order to ensure consistency when 135 returning MemoryUsage datas. Note that all 136 tables in this group have been implemented 137 as virtual tables. As a consequence, the 138 generated TableJvmMemXXXXXTable.java classes 139 are not needed. 140 141 JvmMemoryMetaImpl.java : Custom MetaData class for the jvmMemory group. 142 Subclasses the generated JvmMemoryMeta class. 143 Object: overrides the factory methods in order 144 to instantiate custom meta data classes 145 for the jvmMemManagerTable, 146 jvmMemGCTable, 147 jvmMemPoolTable, 148 jvmMemMgrPoolRelTable. 149 150 JVM Memory Manager Table 151 ------------------------ 152 153 JvmMemManagerTableMetaImpl.java : Custom MetaData class for the 154 jvmMemManagerTable. This MetaData traps 155 all the SNMP Runtime calls made to the 156 table - in order to make the Memory Manager 157 table virtual: i.e. the table does not have 158 to be maintained permanently in memory. 159 Instead, the table is computed "on demand", 160 and the data is cached in a weak cache 161 (see SnmpNamedListTableCache) which remains 162 valid for a few ms. If the data is found 163 to be obsolete, or was garbage collected, 164 the table is recomputed. 165 166 JvmMemManagerEntryImpl.java : Custom Entry class for jvmMemManagerTable. 167 Entries are created on the fly when it 168 becomes necessary to get data from a 169 Memory Managers. They are temporary objects 170 that wrap the MemoryManager just for the 171 call duration - and are released just after. 172 173 JVM Memory GC Table 174 ------------------- 175 176 JvmMemGCTableMetaImpl.java : Custom MetaData class for the 177 jvmMemGCTable. This MetaData traps 178 all the SNMP Runtime calls made to the 179 table - in order to make the GC 180 table virtual: the GC table reuses the 181 cached data computed for the 182 jvmMemManagerTable - simply acting as a 183 filter that only shows those elements that 184 are instance of GarbageCollectorMetrics. 185 In other words it implements a fitered view 186 of the jvmMemManagerTable. 187 188 JvmMemGCEntryImpl.java : Provide access to the data specific to 189 GarbageCollectorMetrics objects. Objects 190 of this classes are created on the fly, 191 when data needs to be returned from a 192 GarbageCollectorMetrics object, and are 193 released just after. They are not kept in 194 memory. 195 196 JVM Memory Pool Table 197 --------------------- 198 199 JvmMemPoolTableMetaImpl.java : Custom MetaData class for the jvmMemPoolTable. 200 This is quite similar to what was done for 201 the jvmMemManagerTable in 202 JvmMemManagerTableMetaImpl. Most of the code 203 here was obtain by cut&paste-ing from 204 JvmMemManagerTableMetaImpl and replacing 205 "Manager" with "Pool". 206 207 JvmMemPoolEntryImpl.java : Provide access to the data specific to 208 MemoryPoolMetrics objects. Objects 209 of this classes are created on the fly, 210 when data needs to be returned from a 211 MemoryPoolMetrics object, and are 212 released just after. They are not kept in 213 memory. Use the request contextual cache 214 in order to ensure consistency when 215 returning MemoryUsage datas. 216 217 JVM Memory Manager / Memory Pool Relation Table 218 ------------------------------------------------ 219 220 221 JvmMemMgrPoolRelTableMetaImpl.java : Custom MetaData class for the 222 jvmMemMgrPoolRelTable. This meta data 223 uses the JvmMemManagerTableMetaImpl and 224 JvmMemPoolTableMetaImpl in order to 225 find out the content of the 226 jvmMemManagerTable and the mapping between 227 Memory Pool Name and Memory Pool Index. 228 For each element of the jvmMemManagerTable 229 it calls the JSR 163 APIs to find the 230 related Memory Pool, then finds out their 231 index, and then creates the corresponding 232 row in the jvmMemMgrPoolRelTable cached data. 233 Like all the other tables, this table is 234 virtual: the data is kept on a weak cache 235 and recomputed on demand, if its validity 236 as expired or if it has been gc'ed. 237 238 JvmMemMgrPoolRelEntryImpl.java : A simple couple MemoryManager/MemoryPool. 239 Models a row in the jvmMemMgrPoolRelTable. 240 Objects of this type are cached in the 241 jvmMemMgrPoolRelTable cached data. 242 243 #============================================================================== 244 #==============================================================================