JMX, SNMP, Java, etc...

Before I can launch into a blog about understanding the JVM-MANAGEMENT-MIB, I will need to say a few words about SNMP MIBs in general, and more particularly, about how SNMP data is structured. These will be the miscellaneous stops we will make in our hitchhiking journey:

Introduction

In previous entries, I have briefly talked about SNMP itself, and introduced the Tiger (and Mustang) JVM SNMP agent.
In this blog, I'm going to elaborate a little more on the structure of SNMP MIBs - and the syntax used to describe those MIBs. As I have already explained in Simple Is Not Easy there are two versions of this syntax: SMIv1 and SMIv2. In this blog I will only speak of SMIv2.

For those advanced readers who wish to acquire more background, RFC 3584 - Coexistence between Version 1, Version 2, and Version 3 of the Internet-standard Network Management Framework, explains all the fine points of why and how SMIv2 MIBs can be implemented by agents supporting any of the existing SNMP protocol versions - therefore obsoleting SMIv1.
For those advanced readers who wish to get first hand information about designing SNMP MIBs, then Understanding SNMP MIBs, by Perkins and McGinnis, published by Prentice Hall, is probably the best reference.
And for those of you who really wish to know the ultimate answer to the great question of SNMP, the Universe, and the Structure of Management Information version 2, then fity-eight, two-thousand-five-hundred-and-seventy-eight is the answer. You will note that it is a somewhat more complex answer than that to the great question of Life, the Universe, and Everything ;-)...

At this point, it is not in my intention to launch in a full-fledged tutorial about MIBs and SNMP - and were I to do so, I wouldn't probably have the requisite editorial skills. My ambitions are more humbly to get you started on understanding how SNMP (the protocol) and MIBs (the data accessed by the protocol) work, so that you may practice with our little JVM agent.

The Global OID Tree

At the root of the structure of SNMP data - is the concept of OBJECT IDENTIFIER, or OID. In my previous blog I have briefly explained the concept of OBJECT-IDENTIFIER. In particular, I have explained that all SNMP definitions - MIBs, objects, etc... are identified by their OID in the global OID tree. I have also shown how enterprises can obtain a sub-node in the enterprises sub-branch of this OID tree. More to the point, I have explained that Sun Microsystems owns the subnode 42 in that enterprises sub-branch and is therefore responsible for the allocation of any node below:

sun OBJECT IDENTIFIER ::= { iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) 42 }

There, a whole sub-tree has been reserved for the JVM-MANAGEMENT-MIB, whose root is defined at:

sun 2 jmgt(145) standard(3) jsr163(163) 1

From now on, I will therefore use the label jvmMgtMIB to represent the OID at the root of the JVM-MANAGEMENT-MIB which is - in dot notation:

1.3.6.1.4.1.42.2.145.3.163.1

SNMP and OBJECT IDENTIFIERS

An important thing to note is that OIDs are not only used to register global definitions, but also to identify the corresponding pieces of data that can be retrieved from an SNMP Agent implementing these definitions. Let me take an example. In the JVM-MANAGEMENT-MIB, we have defined a scalar variable that represents the current count of living threads. This variable is defined by the following OBJECT-TYPE definition, extracted from the JVM-MANAGEMENT-MIB:

[...]
jvmMgtMIBObjects OBJECT IDENTIFIER ::= { jvmMgtMIB 1 }
[...]
jvmThreading     OBJECT IDENTIFIER ::= { jvmMgtMIBObjects 3 }

-- The following objects are mapped from the ThreadMXBean interface.
-----------------------------------------------------------------------

jvmThreadCount OBJECT-TYPE
    SYNTAX      Gauge32
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
	"The current number of live threads.

	 See java.lang.management.ThreadMXBean.getThreadCount()
        "
    REFERENCE "J2SE 5.0 API Specification,
              java.lang.management.ThreadMXBean"
    ::= { jvmThreading 1 }

This means that to get the jvmThreadCount from an SNMP agent that implements the JVM-MANAGEMENT-MIB, we will simply send an SNMP GET request containing the OID:

1.3.6.1.4.1.42.2.145.3.163.1.1.3.1.0
^---sun-----^              ^     ^ ^
^--------jvmMgtMIB---------^     ^ ^
^-----------jvmThreadCount-------^ ^
^------value of jvmThreadCount-----^

It is also important to note that only terminal values (leaves of the tree) can be accessed through the SNMP protocol. This is why scalar variables are accessed with a trailing .0 in their OID, which distinguishes the value (jvmThreadCount.0) from the definition (jvmThreadCount). Another way to put it would be to say that the MIB contains the definitions (jvmThreadCount), while the agent contains only the actual associated values (jvmThreadCount.0).

SNMP is Simple

Now one of the reasons why we say that SNMP is simple, is because SNMP and SMIv2 will only allow you to define, expose, get, and set values of simple types. The types supported by the SNMP protocol and SMIv2 are defined in STD 58, RFC 2578. I will not go and describe all these types, and the interested reader is invited to go directly at the source in RFC 2578. To sketch it, we can say that SNMP allows you only to expose:

• INTEGER based types (Counters, Gauges, Integers, Named-Integers)
• OCTET-STRING based types (Displayable Strings, hexadecimal strings, bit maps, DateAndTime, etc...)
• and OBJECT IDENTIFIERS

Scalar Objects and Columnar Objects

In SMI, we will find two kinds of objects that you can GET and SET: scalar objects, of which jvmThreadCount is an instance, and columnar objects, which allow us to represent tables. Tables are probably the most complex things that you will encounter in SNMP. This is because a) all the data in SNMP is registered in a tree structure, which does not map quite naturally to two-dimensional [column/row] tables, and b) the protocol itself has no verb for CREATE/INSERT/DELETE, so all creation/deletion of rows in tables has to be performed by means of SET requests.

Defining Tables in SNMP

-----------------------------------------------------------------------
--
-- The JVM Input Argument Table
--
-- The jvmRTInputArgsTable contains one row per input argument given on
-- the Java command line.
--
-- See J2SE 5.0 API Specification,
--     java.lang.management.RuntimeMXBean.getInputArguments()
--     for more information.
-----------------------------------------------------------------------

jvmRTInputArgsTable OBJECT-TYPE
    SYNTAX      SEQUENCE OF JvmRTInputArgsEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
	"The Input Argument Table lists the input arguments passed
	 to the Java Virtual Machine. 

	 The jvmRTInputArgsIndex is the index of the argument in 
	 the array returned by RuntimeMXBean.getInputArguments().
	 
	 See java.lang.management.RuntimeMXBean.getInputArguments()
        "
    REFERENCE "J2SE 5.0 API Specification,
              java.lang.management.RuntimeMXBean"
    ::= { jvmRuntime 20 }

This defines a table called jvmRTInputArgsTable whose rows are modeled as instances of JvmRTInputArgsEntry.

Conceptual Rows

In fact, in SNMP, we do not speak of rows, but rather of conceptual rows. This is because there doesn't exists such a thing as a row in an OID tree: there doesn't exist such a thing as an instance of JvmRTInputArgsEntry, that you could identify by a single OID, and that you could get and set. What we have in the OID tree, and what you can get and set with SNMP, are individual table cells, identified by the OID of the column you're looking at, and the index of the conceptual row that intersects with that column. So here is how you define a conceptual row:

jvmRTInputArgsEntry OBJECT-TYPE
    SYNTAX      JvmRTInputArgsEntry
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
	"Represent an input argument passed to the Java Virtual Machine.

	 See java.lang.management.RuntimeMXBean.getInputArguments()
        "
    REFERENCE "J2SE 5.0 API Specification,
              java.lang.management.RuntimeMXBean"
    INDEX { jvmRTInputArgsIndex }
    ::= { jvmRTInputArgsTable 1 }

JvmRTInputArgsEntry ::= SEQUENCE {
        jvmRTInputArgsIndex JvmPositive32TC,
	jvmRTInputArgsItem  JvmArgValueTC
}

The first construct (jvmRTInputArgsEntry is an OBJECT-TYPE that identifies the definition of the conceptual row itself. You will notice that this OBJECT-TYPE, like the OBJECT-TYPE that declares the table itself, is said to be not-accessible. This is because, as I have stated earlier, these objects are not value leaves of the OID tree, and therefore cannot be returned.
The jvmRTInputArgsEntry has mostly two clauses that interests us: the SYNTAX clause identifies the pseudo-type of the conceptual row. Just like the pseudo-type of the jvmRTInputArgsTable was declared to be a SEQUENCE OF JvmRTInputArgsEntry, the pseudo-type of jvmRTInputArgsEntry is declared to be JvmRTInputArgsEntry. Notice how the name of the conceptual row definition and the name of its pseudo-type differ only in the case of their first letter.
The second clause that interests us is the INDEX clause. The INDEX clause identifies the columns whose values will serve to uniquely identify a row in the table (they compose a primary key). In our case, we have only one column in the primary key - named jvmRTInputArgsIndex. We will see later the definition of this columnar object.

The second construct is not an OBJECT-TYPE, but is the ASN.1 definition of the pseudo-type of the conceptual row. This pseudo-type is declared to be a SEQUENCE of fields whose name and types correspond to the table's columnar objects. In this small example, we have only two columns, which are, the column index itself jvmRTInputArgsIndex and the value of the JVM input argument at that index, jvmRTInputArgsItem.

Definition of Index and Non-Index Columnar Objects

To complete the definition of our small input argument table, we must now define its two columns:

jvmRTInputArgsIndex OBJECT-TYPE
    SYNTAX      JvmPositive32TC
    MAX-ACCESS  not-accessible
    STATUS      current
    DESCRIPTION
	"The index of the input argument, as in the array returned 
	 by RuntimeMXBean.getInputArguments().

	 See java.lang.management.RuntimeMXBean.getInputArguments()
        "
    REFERENCE "J2SE 5.0 API Specification,
              java.lang.management.RuntimeMXBean"
    ::= { jvmRTInputArgsEntry 1 }

defines the jvmRTInputArgsIndex index column. There are two things that are noticeable about this definition. First, this index object is declared to be not-accessible. Why? because of The Chicken, and because of The Egg. Namely, to GET the value of the index, you would have to know the value of the index in the first place: asking for "hey, I want the value of the index where the value of the index is Z" would simply get you Z. This would be completely irrelevant and SMIv2 thus mandates that all indexes be declared as not-accessible - there is one exception, which I'm not going to detail - when the table contains only indexes - e.g. when it simply defines relationships between indexes in other tables. However, this is for 2nd year in SNMP, so let's forget about this for now - readers etc... STD 58, RFC 2578 etc... ;-)

TEXTUAL-CONVENTIONS

The second thing that is noticeable about this definition is the value of the SYNTAX clause, which is defined to be JvmPositive32TC.
JvmPositive32TC is a TEXTUAL-CONVENTION which is defined in the JVM-MANAGEMENT-MIB as follows:

JvmPositive32TC ::= TEXTUAL-CONVENTION
    STATUS       current
    DESCRIPTION
          "A positive Integer32. In Java that would be a number 
           in [0..Integer.MAX_VALUE].
	  "  
    -- We use Integer32 (0..2147483647) rather than Unsigned32 because
    -- Unsigned32 (0..2147483647) because Unsigned32 is based on 
    -- Gauge32 - which has a specific ASN.1 tag and a specific semantics. 
    -- In principle you cannot use a Gauge32 as base type for an index 
    -- in a table.
    -- Note also that Unsigned32 is (0..2^32-1) 
    --          while Positive32 is (0..2^31-1)
    -- 
    SYNTAX Integer32 (0..2147483647)

TEXTUAL-CONVENTIONS are in fact a means to assign some specific semantics to to a generic base type used in a specific context - here as value of an index. When the value of jvmRTInputArgsIndex will be encoded and sent over the wire, it will be encoded as a simple Integer32, just as if the JvmPositive32TC had never existed. Only by reading the MIB definitions for the corresponding object can you know that jvmRTInputArgsIndex in fact follows the JvmPositive32TC TEXTUAL-CONVENTION.

The End Is Close!

Finally, and to complete our table, we still need to define the only piece of data that we will be able to access, the real content of the table, its unique non index column (unique in this case: tables can have multiple indexes and multiple non index columns), the jvmRTInputArgsItem:

jvmRTInputArgsItem OBJECT-TYPE
    SYNTAX      JvmArgValueTC
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION
	"An input argument at index jvmRTInputArgsIndex, as in the array 
	 returned by RuntimeMXBean.getInputArguments().

	 Note that the SNMP agent may have to truncate the string returned
         by the underlying API if it does not fit in the JvmArgValueTC 
         (1023 bytes max).

	 See java.lang.management.RuntimeMXBean.getInputArguments()
        "
    REFERENCE "J2SE 5.0 API Specification,
              java.lang.management.RuntimeMXBean"
    ::= { jvmRTInputArgsEntry 2 }

This, dear reader who has been patient enough to follow me this far, is the actual data that is contained in this table - which makes it possible to retrieve, using the SNMP protocol, each of the args[i] input passed to the JVM public static void main(String[] args) method...
Hurrah!

Getting an Instance of a Columnar Object

So to get the value of args[i], and according to all these definitions we've been examining so far, you will simply need to send a GET request for the following OID: jvmRTInputArgsItem.<i> or in dot notation, and assuming that i=5:

1.3.6.1.4.1.42.2.145.3.163.1.1.4.20.1.2.5
^---sun-----^              ^     ^  ^ ^ ^
^------jvmMgtMIB-----------^     ^  ^ ^ ^
^--------jvmRTInputArgsTable-----^  ^ ^ ^
^--------jvmRTInputArgsEntry--------^ ^ ^ 
^----------jvmRTInputArgsItem---------^ ^
^------value of jvmRTInputArgsItem------^
         at jvmRTInputArgsIndex=5 

The End! Don't miss the next episode in our SNMP series!

In some next entries, I'll do a follow-up to explain how you can discover the content of a table by sending GET-NEXT request, how you can compose the index part of an OBJECT-IDENTIFIER when the index value is a string, and how to work with tables which have multiple indexes. But I think you will agree with me, this would be definitely too much for tonight...