Write Zabbix modules in Go!
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dummy Switched from regexp to native string parsing in dummy.go Aug 29, 2015
.gitignore Simplifed function routing. Working much nicer Aug 28, 2015
.travis.yml Refactored Makefiles Aug 29, 2015
Dockerfile Fixed Go pointer return in zbx_module_item_list. Fixes #7 Mar 8, 2016
LICENSE Added LICENSE file Aug 29, 2015
Makefile Fixed Go pointer return in zbx_module_item_list. Fixes #7 Mar 8, 2016
README.md Added warning about #5 to readme May 25, 2016
darwin.go Fixed build on OS X Aug 29, 2015
doc.go Added performance testing tools and findings document Aug 29, 2015
example_discovery_test.go Removed license header from godoc examples Aug 29, 2015
example_double_test.go Removed license header from godoc examples Aug 29, 2015
example_init_test.go Added godoc examples for init/uninit Aug 29, 2015
example_string_test.go Added godoc examples for init/uninit Aug 29, 2015
example_uint64_test.go Removed license header from godoc examples Aug 29, 2015
example_uninit_test.go Added godoc examples for init/uninit Aug 29, 2015
g2z.go Fixed build on OS X Aug 29, 2015
linux.go Attempting to fix Travis-CI build Aug 29, 2015
lld.go Added docs to dummy module Aug 28, 2015
log.go Added tests to dummy module Aug 29, 2015
log.h Initial commit Aug 19, 2015
module.go Fixed Go pointer return in zbx_module_item_list. Fixes #7 Mar 8, 2016
module.h Initial commit Aug 19, 2015
performance.md Added more detail to instructions in README Aug 29, 2015
router.go Added performance testing tools and findings document Aug 29, 2015
zbxtypes.h Initial commit Aug 19, 2015

README.md

g2z

Zabbix module adapter for Go

GoDoc Build Status

This project provides Go bindings for creating native Zabbix modules.

WARNING:_ Please see issue #5 before making use of this library. Single threaded workloads are fine but any use of go-routines/threads (or APIs which make use of threads) will not work and probably never will. This is due to irreconcilable architectural differences between the Zabbix agent and Go runtime (sad face...).

Zabbix modules are an effective way of extending the Zabbix agent and server to monitor resources which are not natively supported by Zabbix.

There are currently two ways to extend Zabbix:

User Parameters simply map agent item keys to system calls. While this is by far the easiest way to extend Zabbix, User Parameters require a process fork on every call (a severe performance impact under load) and typically require a script interpreter such as Perl or Ruby and their dependent framework modules.

Loadable Modules offer a significant performance increase (being native C libraries) and reduce the overhead of dependencies. Unfortunately, modules are rarely adopted because the effort and expertise required to write one in C is a great deal more than writing a script in a higher level language like Perl.

This project aims to deliver the best of both worlds; fast, native C libraries, written in an easier high-level language (Go), with all the dependencies bundled into a standalone library file.

The findings of some performance tests are listed in performance.md.

Requirements

  • Go v1.5.0+
  • Zabbix v2.2.0+
  • C build tools (only tested on GCC)

Installation

The module APIs of Zabbix v2 and v3 are currently incompatible. As a result, you must install and import the appropriate version of g2z for your targeted Zabbix version.

For Zabbix v2.X:

$ go get gopkg.in/cavaliercoder/g2z.v2

For Zabbix v3.X:

$ go get gopkg.in/cavaliercoder/g2z.v3

Usage

Here's a quick high-level run down on how to create a Zabbix agent module. For further guidance, there is full API documentation available on godoc.org and an example module included in the g2z sources which implements the dummy C module published by Zabbix.

To begin, create a mandatory main() entry point to your library and import g2z. The main() function will never be called but is a requirement for building shared libraries in Go.

package main

import "github.com/cavaliercoder/g2z"

func main() {
    panic("THIS_SHOULD_NEVER_HAPPEN")
}

Write a Go function which accepts a *g2z.AgentRequest parameter and returns either a string, uint64, float64 or g2z.DiscoveryData as the first parameter, and an error as the second return parameter.

func Echo(request *g2z.AgentRequest) (string, error) {
    return strings.Join(request.Params, " "), nil
}

Create an init() function to register your functions as agent item keys. The init() function is executed by the Go runtime when your module is loaded into Zabbix via dlopen(). You should not execute any other calls in this function, other than registering your items and init/uninit handlers.

func init() {
    g2z.RegisterStringItem("go.echo", "Hello world!", Echo)
}

There are a few different item types you may register. Each requires an agent item key name, some test parameters and a handler function for Zabbix to call when it receives a request for the registered item key.

Compile your project with:

$ go build -buildmode=c-shared

Load your .so module file into Zabbix as per the Zabbix manual.

Test your item keys with zabbix_agentd -p or zabbix_agent_bench.

License

g2z - Zabbix module adapter for Go Copyright (C) 2015 - Ryan Armstrong ryan@cavaliercoder.com

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.