mackerelplugin

README

go-mackerel-plugin-helper

This package provides helper methods to create mackerel agent plugin easily.

Recommend to use go-mackerel-plugin

We recommend to use go-mackerel-plugin instead of go-mackerel-plugin-helper to create mackerel agent plugin. It is because you can create a plugin more simply by go-mackerel-plugin than by go-mackerel-plugin-helper.

How to use

Graph Definition

A plugin can specify Graphs and Metrics. Graphs represents one graph and includes some Metricss which represent each line.

Graphs includes followings:

• Label: Label for the graph
• Unit: Unit for lines, integer, float can be specified.
• Metrics: Array of Metrics which represents each line.

Metics includes followings:

• Name: Key of the line
• Label: Label of the line
• Diff: If Diff is true, differential is used as value.
• Type: 'float64', 'uint64' or 'uint32' can be specified. Default is float64
• Stacked: If Stacked is true, the line is stacked.
• Scale: Each value is multiplied by Scale.

var graphdef = map[string](mackerelplugin.Graphs){
	"memcached.cmd": {
		Label: "Memcached Command",
		Unit:  "integer",
		Metrics: [](mackerelplugin.Metrics){
			{Name: "cmd_get", Label: "Get", Diff: true, Type: "uint64"},
			{Name: "cmd_set", Label: "Set", Diff: true, Type: "uint64"},
			{Name: "cmd_flush", Label: "Flush", Diff: true, Type: "uint64"},
			{Name: "cmd_touch", Label: "Touch", Diff: true, Type: "uint64"},
		},
	},
}

Calculate Differential of Counter

Many status values of popular middle-wares are provided as counter. But current Mackerel API can accept only absolute values, so differential values must be calculated beside agent plugins.

Diff of Metrics is a flag whether values must be treated as counter or not. If this flag is set, this package calculate differential values automatically with current values and previous values, which are saved to a temporally file.

Adjust Scale Value

Some status values such as jstat memory usage are provided as scaled values. For example, OGC value are provided KB scale.

Scale of Metrics is a multiplier for adjustment of the scale values.

var graphdef = map[string](mackerelplugin.Graphs){
    "jvm.old_space": {
        Label: "JVM Old Space memory",
        Unit:  "float",
        Metrics: [](mackerelplugin.Metrics){
            {Name: "OGCMX", Label: "Old max", Diff: false, Scale: 1024},
            {Name: "OGC", Label: "Old current", Diff: false, Scale: 1024},
            {Name: "OU", Label: "Old used", Diff: false, Scale: 1024},
        },
    },
}

Deal with counter overflow

If Type of metrics is uint64 or uint32 and Diff is true, the helper check counter overflow. When differential value is negative, overflow or counter reset may be occurred. If the differential value is ten-times above last value, the helper judge this is counter reset, not counter overflow, then the helper set value is unknown. If not, the helper recognizes counter overflow occurred.

Tempfile

MackerelPlugin interface has Tempfile field. The Tempfile is used to calculate differences in metrics with Diff: true. If this field is omitted, the filename of the temporaty file is automatically generated from plugin filename.

Default value of Tempfile

mackerel-agent's plugins should place its Tempfile under os.Getenv("MACKEREL_PLUGIN_WORKDIR") unless specified explicitly. Since this helper handles the environmental value, it's recommended not to set default Tempfile path. But if a plugin wants to set default Tempfile filename by itself, use MackerelPlugin.SetTempfileByBasename(), which sets Tempfile path considering the environmental value.

  helper.Tempfile = *optTempfile
  if optTempfile == nil {
    helper.SetTempfileByBasename("YOUR_DEFAULT_FILENAME")
  }

Method

A plugin must implement this interface and the main method.

type PluginWithPrefix interface {
	FetchMetrics() (map[string]interface{}, error)
	GraphDefinition() map[string]Graphs
	MetricKeyPrefix() string
}

func main() {
	optHost := flag.String("host", "localhost", "Hostname")
	optPort := flag.String("port", "11211", "Port")
	optTempfile := flag.String("tempfile", "", "Temp file name")
    optMetricKeyPrefix := flag.String("metric-key-prefix", "memcached", "Metric Key Prefix")
	flag.Parse()

	var memcached MemcachedPlugin

	memcached.Target = fmt.Sprintf("%s:%s", *optHost, *optPort)
    memcached.prefix = *optMetricKeyPrefix
	helper := mackerelplugin.NewMackerelPlugin(memcached)
	helper.Tempfile = *optTempfile

	helper.Run()
}

old Plugin interface

Plugin interface is old one. PluginWithPrefix interface is recommended now.

Documentation

Index

• type GraphDef
• type Graphs
• type MackerelPlugin
  • func NewMackerelPlugin(plugin Plugin) MackerelPlugin
  • func (h *MackerelPlugin) FetchLastValues() (metricValues MetricValues, err error)
  • func (h *MackerelPlugin) OutputDefinitions()
  • func (h *MackerelPlugin) OutputValues()
  • func (h *MackerelPlugin) Run()
  • func (h *MackerelPlugin) SetTempfileByBasename(base string)
• type MetricValues
• type Metrics
• type Plugin
• type PluginWithPrefix

Types

type GraphDef

type GraphDef struct {
	Graphs map[string]Graphs `json:"graphs"`
}

GraphDef represents graph definitions

type Graphs

type Graphs struct {
	Label   string    `json:"label"`
	Unit    string    `json:"unit"`
	Metrics []Metrics `json:"metrics"`
}

Graphs represents definition of a graph

type MackerelPlugin

type MackerelPlugin struct {
	Plugin
	Tempfile string
	// contains filtered or unexported fields
}

MackerelPlugin is for mackerel-agent-plugin

func NewMackerelPlugin

func NewMackerelPlugin(plugin Plugin) MackerelPlugin

NewMackerelPlugin returns new MackerelPlugin struct

func (*MackerelPlugin) FetchLastValues

func (h *MackerelPlugin) FetchLastValues() (metricValues MetricValues, err error)

FetchLastValues retrieves the last recorded metric value if there is the graph-def that is set Diff to true in the result of h.GraphDefinition().

func (*MackerelPlugin) OutputDefinitions

func (h *MackerelPlugin) OutputDefinitions()

OutputDefinitions outputs graph definitions

func (*MackerelPlugin) OutputValues

func (h *MackerelPlugin) OutputValues()

OutputValues output the metrics

func (*MackerelPlugin) Run

func (h *MackerelPlugin) Run()

Run the plugin

func (*MackerelPlugin) SetTempfileByBasename

func (h *MackerelPlugin) SetTempfileByBasename(base string)

SetTempfileByBasename sets Tempfile under proper directory with specified basename.

type MetricValues

type MetricValues struct {
	Values    map[string]interface{}
	Timestamp time.Time
}

MetricValues represents a collection of metric values and its timestamp

type Metrics

type Metrics struct {
	Name         string  `json:"name"`
	Label        string  `json:"label"`
	Diff         bool    `json:"-"`
	Type         string  `json:"-"`
	Stacked      bool    `json:"stacked"`
	Scale        float64 `json:"-"`
	AbsoluteName bool    `json:"-"`
}

Metrics represents definition of a metric

type Plugin

type Plugin interface {
	FetchMetrics() (map[string]interface{}, error)
	GraphDefinition() map[string]Graphs
}

Plugin is old interface of mackerel-plugin

type PluginWithPrefix

type PluginWithPrefix interface {
	Plugin
	MetricKeyPrefix() string
}

PluginWithPrefix is recommended interface