Black Hill Software is currently developing an API for processing SMF data using Java.
The API builds on experience gained developing EasySMF to create a powerful and easy to use API for working with SMF data.
The API will run on z/OS and other platforms such as Linux and Windows. The API is 100% Java which makes it zAAP eligible on z/OS.
The design at the time of this post used Joda Time for times and durations. This was changed prior to the initial release to use the java.time package introduced with Java 8. Java.time has the same advantages as Joda Time but it is a core part of Java so the removal of an external dependency was worth the cost of requiring Java 8 as a minimum level. Java.time is well suited to working with the dates and times in SMF, with specific classes to distinguish between e.g. local date/times, UTC date/times and durations. The java.time resolution of 1 nanosecond is accurate enough for most SMF purposes.
Data Conversions
The API aims to provide a consistent interface across different record types and sections.
- Times representing a duration e.g. CPU time, connect time are converted to floating point values expressed in seconds. This allows easy manipulation and comparison, without dealing with the multitude of time units used in SMF. The raw unconverted value is also available if required.
- Dates and times of day are expressed using Joda-Time classes. Joda-Time provides simple functions for most date and time calculations, so you can easily work with days of the week etc. It also provides time zone calculations, so you can e.g. apply a time zone to the times from the SMF records and match times between systems in different time zones. Joda-Time includes the Time Zone Database, so if you apply a time zone it can apply the correct rules to account for daylight savings.
- STCK fields are available as a DateTime value (with only millisecond precision) and as a BigInteger with the complete value for use as a timestamp, for sorting etc.
- 1, 2 and 3 byte integer values are converted to the Java int datatype.
- 4 byte/32 bit unsigned integer values are converted to the Java long (64 bit integer) datatype. Java does not have an unsigned datatype, so a 4 byte int can’t hold the complete range of 32 bit unsigned values.
- 8 byte/64 bit unsigned integer values are available as long or BigInteger values. The long datatype may provide better performance if the value will not exceed the maximum 64 bit signed value. The API will throw an exception if the value is too large for a long. If this is possible, use the BigInteger value.
- Integers greater than 8 bytes are converted to BigIntegers.
- Floating point values are converted to the Java double datatype.
- SMF record classes provide methods to return the SMF subsections. Subsections are returned as a List<T> if the number of sections can vary, or individually if there is always a single section.
Current Status
The API is currently undergoing pre-release testing. I am looking for feedback on usability, performance and naming conventions. You can download the current version from the links on this page. Feedback is welcome in the comments area, or to info@blackhillsoftware.com.
Record types 30, 70, 71, 72, 73, 74, 75, 77 and 78 are currently mapped. More record types are planned, but these record types should make enough interesting data available for some realistic testing and real world feedback on the design of the API.
At this point the API design is changeable, so program changes may be required for new versions. One of the objectives of the testing period is to get enough feedback to identify problems now, and avoid breaking changes in the future.
Feedback
Some of the areas where I would particularly like feedback are:
- Naming conventions: Many Java APIs use the get…() naming convention for method names. Almost all the SMF methods are get methods. Prefixing everything with get didn’t seem to add much value and made the resulting code more difficult to read, so the methods currently use bare field names. Are there advantages to using the get prefix e.g. for use with code generation/reporting tools?
- More naming conventions: Many of the names of classes representing section types are long. However, they are named to be consistent with the SMF documentation. I believe this makes the programs easier to write and understand, and makes the Eclipse auto complete easier to use.
- Use of the Joda Time classes: Joda Time is useful for date and time calculations. However, it does add a dependency on an external library. Would it be preferable to use the standard date time classes and eliminate the dependency? Joda Time could still be used at a site’s own discretion, writing their own conversions from standard times as required.
- General comments on the data types used.
Documentation and Downloads
The current Javadoc is available here.
For more information, including code samples see:
https://www.blackhillsoftware.com/news/category/java-smf/
Sample Programs
Sample 1 : SMF Records by type and subtype
Sample 2 : Prime Shift Top CPU Consumers
Download the current version here:
- EasySMF:JE – Zip format – Jars and samples in zip format
- EasySMF:JE – tar.gz format – Jars and samples in tar.gz format
- EasySMF:JE – Pax archive – Jars and samples in pax archive format, for installation on z/OS
Samples are available on Github: https://github.com/BlackHillSoftware/easysmf-samples