package module
Version: v0.1.2 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jun 28, 2021 License: Apache-2.0 Imports: 13 Imported by: 370


go-mackerel-plugin GoDev Build Status

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

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, float, integer, percentage, bytes, bytes/sec, iops 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.
  • Stacked: If Stacked is true, the line is stacked.
  • Scale: Each value is multiplied by Scale.

Example of graph definition.

var graphdef = map[string]mackerelplugin.Graphs{
	"memcached.connections": {
		Label: "Memcached Connections",
		Unit:  "integer",
		Metrics: []mackerelplugin.Metrics{
			{Name: "curr_connections", Label: "Connections", Diff: false},


A plugin must implement this interface and the main method.

type PluginWithPrefix interface {
	FetchMetrics() (map[string]float64, 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")

	var memcached MemcachedPlugin

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


You can find an example implementation in _example/ directory.

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},


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 {




View Source
const (
	UnitFloat          = "float"
	UnitInteger        = "integer"
	UnitPercentage     = "percentage"
	UnitBytes          = "bytes"
	UnitBytesPerSecond = "bytes/sec"
	UnitIOPS           = "iops"

Metric units


This section is empty.


This section is empty.


type GraphDef

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

GraphDef is 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 {
	Tempfile string
	// contains filtered or unexported fields

MackerelPlugin is for mackerel-agent-plugins

func NewMackerelPlugin

func NewMackerelPlugin(plugin Plugin) *MackerelPlugin

NewMackerelPlugin returns new MackrelPlugin

func (*MackerelPlugin) OutputDefinitions

func (mp *MackerelPlugin) OutputDefinitions()

OutputDefinitions outputs graph definitions

func (*MackerelPlugin) OutputValues

func (mp *MackerelPlugin) OutputValues()

OutputValues output the metrics

func (*MackerelPlugin) Run

func (mp *MackerelPlugin) Run()

Run the plugin

func (*MackerelPlugin) SetTempfileByBasename

func (mp *MackerelPlugin) SetTempfileByBasename(base string)

SetTempfileByBasename sets Tempfile under proper directory with specified basename.

type Metrics

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

Metrics represents definition of a metric

type Plugin

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

Plugin is old interface of mackerel-plugin

type PluginWithPrefix

type PluginWithPrefix interface {
	MetricKeyPrefix() string

PluginWithPrefix is recommended interface


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL