gojmx

README

gojmx is a go module that allows fetching data from a JMX endpoint.

Installing

You can use gojmx in your project by running go get command:

go get github.com/newrelic/nrjmx/gojmx

Next, import the dependency into your application:

import "github.com/newrelic/nrjmx/gojmx"

This go module will call nrjmx library in order to fetch the metrics.

To install nrjmx library on your system, packages are available on this repository in the release assets or on our package manager repositories stored here. You can folow this documentation to include our repository into your package manager.

nrjmx library is also available as a tarball.

Usage

After nrjmx library was installed on the system, you need a JMX service exposed. For this example, we will use the test-server available on the root of this repository:

docker build -t nrjmx/test-server .
docker run -d -p 7199:7199 nrjmx/test-server

// JMX Client configuration.
config := &gojmx.JMXConfig{
    Hostname:         "localhost",
    Port:             7199,
    RequestTimeoutMs: 10000,
}

// Connect to JMX endpoint.
client, err := gojmx.NewClient(context.Background()).Open(config)
handleError(err)

// Get the mBean names.
mBeanNames, err := client.QueryMBeanNames("java.lang:type=*")
handleError(err)

// Get the Attribute names for each mBeanName.
for _, mBeanName := range mBeanNames {
    mBeanAttrNames, err := client.GetMBeanAttributeNames(mBeanName)
    handleError(err)

    // Get the attribute value for each mBeanName and mBeanAttributeName.
    jmxAttrs, err := client.GetMBeanAttributes(mBeanName, mBeanAttrNames...)
    if err != nil {
        fmt.Println(err)
        continue
    }
    for _, attr := range jmxAttrs {
        if attr.ResponseType == gojmx.ResponseTypeErr {
            fmt.Println(attr.StatusMsg)
            continue
        }
        printAttr(attr)
    }
}

// Or use QueryMBean call which wraps all the necessary requests to get the values for an MBeanNamePattern.
// Optionally you can provide atributes to QueryMBeanAttributes in tha same way you provide for GetMBeanAttributes,
// e.g.: response, err := client.QueryMBeanAttributes("java.lang:type=*", mBeanAttrNames...)
response, err := client.QueryMBeanAttributes("java.lang:type=*")
handleError(err)
for _, attr := range response {
    if attr.ResponseType == gojmx.ResponseTypeErr {
        fmt.Println(attr.StatusMsg)
        continue
    }
    printAttr(attr)
}

You can find the full example in the examples directory.

Custom connectors

JMX allows the use of custom connectors to communicate with the application. In order to use a custom connector, you have to include the custom connectors in the nrjmx classpath.

By default, the sub-folder connectors is in the classpath. If this folder does not exist, create it under the folder where nrjmx is installed.

For example, to add support for JBoss, create a folder named connectors under the default (Linux) library path /usr/lib/nrjmx/ (/usr/lib/nrjmx/connectors/) and copy the custom connector jar ($JBOSS_HOME/bin/client/jboss-cli-client.jar) into it. You can now execute JMX queries against JBoss.

Internal nrjmx query stats

If InternalStats feature is enabled (gojmx.JMXConfig.EnableInternalStats = true), the nrjmx java subprocess will collect information about each JMX request. This feature can be used to give more insights while troubleshooting performance issues.

The InternalStats are collected in memory (up to 10000 samples by default). When the maximum limit is reached, old samples will be discarded. You can increase the maximum limit using gojmx.JMXConfig.MaxInternalStatsSize config option. After the stats are retrieved (using client.GetInternalStats()) nrjmx java subprocess will clean the sample storage.

e.g.:

    // JMX Client configuration.
	config := &gojmx.JMXConfig{
		Hostname:         "localhost",
		Port:             7199,

		// Enable internal gojmx stats for troubleshooting.
		EnableInternalStats: true,
	}

    // Connect to JMX endpoint.
	client, err := gojmx.NewClient(context.Background()).Open(config)
	handleError(err)

	defer client.Close()

    ... queries ...
   
	// Collecting gojmx internal query stats. Use this only for troubleshooting.
	internalStats, err := client.GetInternalStats()
	handleError(err)

	for _, internalStat := range internalStats {
		fmt.Println(internalStat.String())
	}

Documentation

Index

• Variables
• func FormatConfig(config *JMXConfig, hideSecrets bool) string
• func FormatJMXAttributes(attrs []*AttributeResponse) string
• type AttributeResponse
  • func (j *AttributeResponse) GetValue() interface{}
  • func (j *AttributeResponse) GetValueAsFloat() (float64, error)
  • func (j *AttributeResponse) String() string
• type Client
  • func NewClient(ctx context.Context) *Client
  • func (c *Client) Close() error
  • func (c *Client) GetClientVersion() string
  • func (c *Client) GetInternalStats() (InternalStatsList, error)
  • func (c *Client) GetMBeanAttributeNames(mBeanName string) ([]string, error)
  • func (c *Client) GetMBeanAttributes(mBeanName string, mBeanAttrName ...string) ([]*AttributeResponse, error)
  • func (c *Client) IsRunning() bool
  • func (c *Client) Open(config *JMXConfig) (client *Client, err error)
  • func (c *Client) QueryMBeanAttributes(mBeanNamePattern string, mBeanAttrName ...string) ([]*AttributeResponse, error)
  • func (c *Client) QueryMBeanNames(mBeanGlobPattern string) ([]string, error)
• type InternalStat
  • func (is *InternalStat) String() string
• type InternalStatsList
  • func (is InternalStatsList) String() string
• type JMXClientError
  • func IsJMXClientError(err error) (*JMXClientError, bool)
  • func (e *JMXClientError) Error() string
  • func (e *JMXClientError) String() string
• type JMXConfig
• type JMXConnectionError
  • func IsJMXConnectionError(err error) (*JMXConnectionError, bool)
  • func (e *JMXConnectionError) Error() string
  • func (e *JMXConnectionError) String() string
• type JMXError
  • func IsJMXError(err error) (*JMXError, bool)
  • func (j *JMXError) Error() string
  • func (j *JMXError) String() string
• type ResponseType

Variables

var (
	// ResponseTypeBool AttributeResponse of bool value
	ResponseTypeBool = nrprotocol.ResponseType_BOOL
	// ResponseTypeString AttributeResponse of string value
	ResponseTypeString = nrprotocol.ResponseType_STRING
	// ResponseTypeDouble AttributeResponse of double value
	ResponseTypeDouble = nrprotocol.ResponseType_DOUBLE
	// ResponseTypeInt AttributeResponse of int value
	ResponseTypeInt = nrprotocol.ResponseType_INT
	// ResponseTypeErr AttributeResponse with error
	ResponseTypeErr = nrprotocol.ResponseType_ERROR
)

Functions

func FormatConfig

func FormatConfig(config *JMXConfig, hideSecrets bool) string

FormatConfig will convert the JMXConfig into a string.

func FormatJMXAttributes

func FormatJMXAttributes(attrs []*AttributeResponse) string

FormatJMXAttributes will prettify JMXAttributes.

Types

type AttributeResponse

type AttributeResponse nrprotocol.AttributeResponse

AttributeResponse keeps the JMX MBean query response.

func (*AttributeResponse) GetValue

func (j *AttributeResponse) GetValue() interface{}

GetValue extracts the value from AttributeResponse based on type.

func (*AttributeResponse) GetValueAsFloat

func (j *AttributeResponse) GetValueAsFloat() (float64, error)

GetValueAsFloat casts the value from AttributeResponse to float based on type.

func (*AttributeResponse) String

func (j *AttributeResponse) String() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client to connect with a JMX endpoint.

func NewClient

func NewClient(ctx context.Context) *Client

NewClient returns a JMX client.

func (*Client) Close

func (c *Client) Close() error

Close will stop the connection with the JMX endpoint.

func (*Client) GetClientVersion

func (c *Client) GetClientVersion() string

GetClientVersion returns nrjmx version.

func (*Client) GetInternalStats

func (c *Client) GetInternalStats() (InternalStatsList, error)

GetInternalStats returns the nrjmx internal query statistics for troubleshooting. Internal statistics must be enabled using JMXConfig.EnableInternalStats flag. Additionally you can set a maximum size for the collected stats using JMXConfig.MaxInternalStatsSize. (default: 100000) Each time you retrieve GetInternalStats, the internal stats will be cleaned.

func (*Client) GetMBeanAttributeNames

func (c *Client) GetMBeanAttributeNames(mBeanName string) ([]string, error)

GetMBeanAttributeNames returns all the available JMX attribute names for a given mBeanName.

func (*Client) GetMBeanAttributes

func (c *Client) GetMBeanAttributes(mBeanName string, mBeanAttrName ...string) ([]*AttributeResponse, error)

GetMBeanAttributes returns the JMX attribute values.

func (*Client) IsRunning

func (c *Client) IsRunning() bool

IsClientRunning returns if the nrjmx client is running.

func (*Client) Open

func (c *Client) Open(config *JMXConfig) (client *Client, err error)

Open will create the connection the the JMX endpoint.

func (*Client) QueryMBeanAttributes

func (c *Client) QueryMBeanAttributes(mBeanNamePattern string, mBeanAttrName ...string) ([]*AttributeResponse, error)

QueryMBeanAttributes performs all calls necessary for retrieving all MBeanAttrs values for the mBeanNamePattern: 1. QueryMBeanNames 2. GetMBeanAttributeNames 3. GetMBeanAttributes If an error occur it checks if it's a collection error (it can recover) or a connection error (that blocks all the collection).

func (*Client) QueryMBeanNames

func (c *Client) QueryMBeanNames(mBeanGlobPattern string) ([]string, error)

QueryMBeanNames returns all the mbeans that match the glob pattern DOMAIN:BEAN. e.g *:* or jboss.as:subsystem=remoting,configuration=endpoint

type InternalStat

type InternalStat nrprotocol.InternalStat

InternalStat gathers stats about queries performed by nrjmx.

func (*InternalStat) String

func (is *InternalStat) String() string

type InternalStatsList

type InternalStatsList []*InternalStat

func (InternalStatsList) String

func (is InternalStatsList) String() string

type JMXClientError

type JMXClientError struct {
	Message string
}

JMXClientError is returned when there is an nrjmx process error. Those errors require opening a new client.

func IsJMXClientError

func IsJMXClientError(err error) (*JMXClientError, bool)

IsJMXClientError checks if the err is JMXJMXClientError.

func (*JMXClientError) Error

func (e *JMXClientError) Error() string

func (*JMXClientError) String

func (e *JMXClientError) String() string

type JMXConfig

type JMXConfig nrprotocol.JMXConfig

JMXConfig keeps the JMX connection settings.

type JMXConnectionError

type JMXConnectionError nrprotocol.JMXConnectionError

JMXConnectionError is returned when there is a JMX connection error or a nrjmx process error.

func IsJMXConnectionError

func IsJMXConnectionError(err error) (*JMXConnectionError, bool)

IsJMXConnectionError tries to convert the error to exported JMXConnectionError.

func (*JMXConnectionError) Error

func (e *JMXConnectionError) Error() string

func (*JMXConnectionError) String

func (e *JMXConnectionError) String() string

type JMXError

type JMXError nrprotocol.JMXError

JMXError is reported when a JMX query fails.

func IsJMXError

func IsJMXError(err error) (*JMXError, bool)

IsJMXError asserts if the error is JMXError.

func (*JMXError) Error

func (j *JMXError) Error() string

func (*JMXError) String

func (j *JMXError) String() string

type ResponseType

type ResponseType nrprotocol.ResponseType

ResponseType specify the type of the value of the AttributeResponse.