README
¶
Go Wrap MX4J
gowrapmx4j is a base library to assist interacting with the MX4J service.
MX4J is a very useful service which makes JMX data accessible via HTTP. Unfortunately little is done to improve the data's representation and it is returned as dense raw XML via an API frought with perilous query variables which are poorly documented.
The types and unmarshalling structures defined here have sorted out some of the XML saddness returned from MX4J and makes it easier to operate on the data stuctures.
Why
Java databases are still industry standard and there's a lot of mindshare built around them. Sadly their tools can be very arcane or non-existant. This library is built specifically to help surface useful information from Cassandra's MX4J endpoint to assist in debugging, monitoring, and management.
This library was built against Cassandra 2.1.10 and MX4J 3.0.2. The tooling should work against other Java services which run with MX4J.
A JSON API running in sidecar is far more human readable, consume, and engage with other services.
Basic API Primer
Types types.go are the basic structs created to aid interaction/querying MX4J, unmarshal data from XML endpoints.
The Registry registry.go is a concurrent safe map of MX4J data which is updated when queries are made.
This is to reduce the number of calls to MX4J if multiple goroutines want to access the data.
The Distill distill.go API aids in cleaning up the data structures created from unmarshalling the
XML API. DistillAttribute and DistillAttributeTypes are the main functions which return
clean data structures for http endpoints.
Where to start
An example web service which operates in a sidecar pattern to the Cassandra/MX4J services provides nice
example usage: gowrapmx4j/cmd/cassandra_example/main.go
Showcases gowrapmx4j components:
- Data structures to unmarshal XML data into Go structs
- Registry usage(registering endpoints, updating, and consumption)
- Wrapping the MX4J endpoint for easy polling to update the registry
- Custom http JSON endpoints to expose JMX data cleanly!
TODO:
- Metrics examples; currently the metric functionality isn't showcased however it is possible and creating useful keyspace level metrics for production environments.
Contact
Josh Roppo is the primary developer on the project.
Critique, ideas, and PRs welcome!
External Requirements
Logrus; for nice log handling.
If using the Go Vendor Experiment everything should just work(yay GO 1.6!). Otherwise you might need to go get -u github.com/Sirupsen/logrus to make it available in your GOPATH.
Documentation
¶
Overview ¶
gowrapmx4j is a base library of types to assist UnMarshalling and Querying MX4J data.
MX4J is a very useful service which makes JMX data accessible via HTTP. Unfortunately little is done to improve the data's representation and it is returned as dense raw XML via an API frought with perilous query variables which are poorly documented.
The types and unmarshalling structures defined here have sorted out some of the XML saddness returned from MX4J and makes it easier to operate on the data stuctures.
Why? Java databases are still industry standard and there's a lot of mindshare built around them. Sadly their tools can be very arcane or non-existant. This library is built specifically to help surface useful information from Cassandra's MX4J endpoint to assist in debugging, monitoring, and management.
A JSON API running in sidecar to MX4J is far more human readable, consumeable, and easier to engage with other services.
Basic API Primer:
Types* are the basic structs created to aid interaction/querying MX4J, unmarshall data from XML endpoints.
The Registry is a concurrent safe map of MX4J data which is updated when queries are made. This is to reduce the number of calls to MX4J if multiple goroutines want to access the data.
The Distill* API aids in cleaning up the data structures created from unmarshalling the XML API. DistillAttribute and DistillAttributeTypes are the main functions which return clean data structures for http endpoints.
Example:
gowrapmx4j/cmd/cassandra_example/main.go
Showcases some ways to use features of gowrapmx4j
Registry usage(registering endpoints, updating, and consumption) Wrapping the MX4J endpoint to update the registry Custom http JSON endpoints to expose JMX data cleanly!
Index ¶
- Variables
- func DistillAttribute(mb MX4JData) (map[string]interface{}, error)
- func DistillAttributeTypes(mb MX4JData) (map[string]interface{}, error)
- func DistillAttributes(mb MX4JData) map[string]string
- func HttpRegistryProcessed(w http.ResponseWriter, r *http.Request)
- func HttpRegistryRaw(w http.ResponseWriter, r *http.Request)
- func QueryMX4J(mx4j MX4JService) (*[]MX4JMetric, error)
- func RegistryBeans() map[string]MX4JData
- func RegistryFlush()
- func RegistryGetHRMap() map[string]MX4JMetric
- func RegistryPurge()
- func RegistrySet(mm MX4JMetric, mb MX4JData)
- type Bean
- type MX4JAttribute
- type MX4JData
- type MX4JElement
- type MX4JMap
- type MX4JMetric
- type MX4JService
Constants ¶
This section is empty.
Variables ¶
var DistillError = errors.New("gowrapmx4j: Attribute parsing error")
Functions ¶
func DistillAttribute ¶
DistillAttribute cleanly extracts the name and value from a singleton MX4J Bean struct
func DistillAttributeTypes ¶
DistillAtributeTypes parses Bean struct []Attributes data and returns map parsed from attribute information which can be marsahlled into JSON.
func DistillAttributes ¶
DistillAttributes parses the queried MX4JMetric endpoints and yields a map of metric fields to their original string values. TODO: Return an actual error
func HttpRegistryProcessed ¶
func HttpRegistryProcessed(w http.ResponseWriter, r *http.Request)
API Endpoint which will execute the optionally specified ValFunc function on the data structure to process the metric's data.
func HttpRegistryRaw ¶
func HttpRegistryRaw(w http.ResponseWriter, r *http.Request)
Cassandra MX4J status endpoint
func QueryMX4J ¶
func QueryMX4J(mx4j MX4JService) (*[]MX4JMetric, error)
Query all registered MX4J endpoints and compose their data into the MX4JMetric array or return error
func RegistryBeans ¶
Return all data points in the Registry
func RegistryFlush ¶
func RegistryFlush()
RegistryFlush resets the MX4JMetric.Data fields for all registered metrics. If connection to MX4J is lost this can be called to remove stale data but keep the metric handles for when MX4J recovers.
func RegistryGetHRMap ¶
func RegistryGetHRMap() map[string]MX4JMetric
Return a map of MX4JMetric structs keyed by their human readable name field.
func RegistryPurge ¶
func RegistryPurge()
Purge the gowrapmx4j data registry Primarily for use in the case where connection to MX4J has been lost, and reporting stale data is unhelpful. Endpoints will need to be re-registered in order for data collection to continue.
func RegistrySet ¶
func RegistrySet(mm MX4JMetric, mb MX4JData)
Set a value in the Registry keyed to its Human Name
Types ¶
type Bean ¶
type Bean struct {
XMLName xml.Name `xml:"MBean"`
ObjectName string `xml:"objectname,attr"`
ClassName string `xml:"classname,attr"`
Attributes []MX4JAttribute `xml:"Attribute"`
}
Bean struct implements querying a full map of data points based on the ObjectName of the attributes. A map of attributes can be returned for selective use by Bean.AttributeMap().
func (Bean) AttributeMap ¶
func (b Bean) AttributeMap() map[string]MX4JAttribute
func (Bean) QueryMX4J ¶
func (b Bean) QueryMX4J(m MX4JService, mm MX4JMetric) (MX4JData, error)
type MX4JAttribute ¶
type MX4JAttribute struct {
Classname string `xml:"classname,attr"`
Name string `xml:"name,attr"` // Effective Key
Value string `xml:"value,attr"` // Always encoded as a string...
Aggregation string `xml:"aggregation,attr"` // "map"-> map; "collection"-> array
JavaType string `xml:"type,attr"`
Map MX4JMap `xml:"Map"`
}
MX4JAttribute is the underlying data structure which is unmarshalled to expose the actual data from MX4J.
type MX4JData ¶
type MX4JData interface {
QueryMX4J(m MX4JService, mm MX4JMetric) (MX4JData, error)
}
MX4JData interface requires the QueryMX4J() which makes http request to MX4J to extract data given the type implmenting the interface.
type MX4JElement ¶
type MX4JElement struct {
Key string `xml:"key,attr"`
Element string `xml:"element,attr"` //Known as 'Value' to the rest of the world
Index string `xml:"index,attr"`
}
MX4JElement is the MX4J representation of Key-Value pairs renamed to be confusing as Key-Element pairs. Struct allows for maps to be unmarshalled.
type MX4JMap ¶
type MX4JMap struct {
Length string `xml:"length,attr"`
Elements []MX4JElement `xml:"Element"`
}
type MX4JMetric ¶
type MX4JMetric struct {
HumanName string // Name only used by Homo Sapiens for sanity
ObjectName string // JMX specific path to query
Format string // JMX Data type
Attribute string // Field of interest under the ObjectName
ValFunc func(MX4JData) (map[string]interface{}, error)
MetricFunc func(MX4JData, string)
Data MX4JData
}
MX4JMetrics assists in deriving information from the extracted MX4JData structs Optional functions can be assigned to the MX4JMetric to be run on the underlying MX4JData type.
func NewMX4JMetric ¶
func NewMX4JMetric(hname, objname, format, attr string) MX4JMetric
NewMX4JMetric provides requires common init arguments for single attribute MBean data struct
func RegistryGet ¶
func RegistryGet(humanName string) MX4JMetric
Return a single MX4JMetric keyed by its human readable name
func RegistryGetAll ¶
func RegistryGetAll() []MX4JMetric
Return a slice of all MX4JMetrics currently registered
type MX4JService ¶
Struct representing MX4J service address information to query against
func (*MX4JService) Init ¶
func (m *MX4JService) Init()
func (MX4JService) QueryGetAttributes ¶
func (m MX4JService) QueryGetAttributes(objectname, format, attribute string) (*Bean, error)
Queries MX4J to get an attribute's data, returns Bean struct or error equivalent to http://hostname:port/getattribute?queryargs... eg: "http://localhost:8081/getattribute?objectname=org.apache.cassandra.metrics:type=ColumnFamily,keyspace=yourkeyspace,scope=node,name=ReadLatency&format=array&attribute=Max&template=identity"
Source Files
Directories