zabbix_sender_api 1.0.5 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f768b8820795e99e87ea3af8ed4cdae063daef728e7c121d5bf9b51a155780b
-  data.tar.gz: b15a5dd5f1ead39e38edff158b35a1b015864c51dc1f4ac9907e1e6ac7f9e1cb
+  metadata.gz: b1bb42ed344a48f3aa83f04739a41ad388eb59ca3beb2819636255d3a5cd6ce7
+  data.tar.gz: 9039d00b328b41b2ad5462a3632a6834319fe027f672084352a707d8c1d3e5a5
 SHA512:
-  metadata.gz: cc34a4e8f82f4c4ca922c65ee35e0ce998eaea72ad5f46138c016bb5226fc1c9387712d2668727fb0305494cc009f79ed1df48586dab81b66a9ad0cbb47c4e99
-  data.tar.gz: 9a24440d4b7d0002ccd331fb43a3c3278af279f3834adb77d17c119583acc63fda4e1af1e23873cd0fe6912a350aa104c24a69928ebc6fb16e702ad6f6040bea
+  metadata.gz: 7df9cceb6e1a5d0836c6bc410a7ab444cd6cab38b9948ba688aaf5daac971c164a88a8d21a6fd629f3841492c9c8f8257c802c25bf8219929421eb3ff31fcdc8
+  data.tar.gz: 9a7b38fc6ae72efabcfa7bfda7b2c503aee772ebf0f3442c8e63ab5391c812a47572dd5ef2143ba33c3c6f591191749b8b34ffb051567d2023240272b4d03d6b

data/.gitignore

@@ -1,8 +1,8 @@
+Gemfile.lock
 /.bundle/
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

data/.gitlab-ci.yml

@@ -0,0 +1,12 @@
+image: alpine:latest
+
+pages:
+  stage: deploy
+  script:
+  - echo 'Nothing to do...'
+  artifacts:
+    paths:
+    - public
+    expire_in: never
+  only:
+  - master

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 1.1.0
+- added native (socket based) sender logic (Zabbix::Sender::Socket).
+- changed Zabbix::Sender::Pipe's open method from popen to Open3::popen3 to allow capture of stdout stderf and exitA
+- the Socket and Pipe .flush method returns status, sendBatchAtomic relays it from its internal call to flush
+# 1.1.1
+- added ability to override Zabbix::AgentConfiguration search path
+- cleaned up a few issues + the docs
+# 1.1.2
+- This is just a documentation fix.  rubydoc.info wasn't generating docs from the gem properly so docs are now in a gitlab "pages" site.

data/README.md

@@ -1,39 +1,17 @@
 # zabbix_sender_api
 
-This gem describes an api that takes some of the drudgery out of the task of putting together bulk data for the zabbix_sender utility.
+This gem provides a model for assembling and sending data to Zabbix via its sender/trapper mechanism.  It works both with the zabbix_sender command line utility, or by itself using a socket connection to a trapper port direct from Ruby.
 
-**Detailed documentation for this library is at [rubydoc.info](https://rubydoc.info/gems/zabbix_sender_api)**
+**Detailed documentation for this library is [>>HERE<<](https://svdasein.gitlab.io/zabbix_sender_api)**
 
 Look at [the source for the zfstozab gem](https://gitlab.com/svdasein/zfstozab/-/blob/master/exe/zabbix-zfs.rb) for a practical example how to use this api.
 
-zabbix_sender is a command line utility for sending monitoring data to Zabbix server or proxy. On the Zabbix server an item of type Zabbix trapper should be created with corresponding key.
+zabbix_sender_api can send data to zabbix via one of two included connection types:
+ * zabbix_sender (this was the original and for quite some time only mode supported)
+ * TCP socket connection directly to a Zabbix "trapper" port (as of vers 1.1.0)
 
- * [Zabbix sender manpage](https://www.zabbix.com/documentation/4.0/manpages/zabbix_sender)
- * [Zabbix sender CLI help](zabbix-sender-help.md)
 
 
-zabbix_sender_api's function is to generate data to send to a zabbix_sender instance via stdin where zabbix_sender was invoked with these options:
-
-```
-  -i --input-file input-file   Load values from input file. Specify - for
-                             standard input. Each line of file contains
-                             whitespace delimited: <host> <key> <value>.
-                             Specify - in <host> to use hostname from
-                             configuration file or --host argument
-                             
-  -T --with-timestamps       Each line of file contains whitespace delimited:
-                             <host> <key> <timestamp> <value>. This can be used
-                             with --input-file option. Timestamp should be
-                             specified in Unix timestamp format
-```
-
-It is analogous to:
-
- \<program that generates sender input\> | zabbix-sender -z \<zabbix-server-or-proxy-ip\> -T -i -
- 
-(You can use this api to just generate output that you then pipe to zabbix_sender yourself if you prefer)
- 
-
 ## Installation
 
     $ gem install zabbix_sender_api
@@ -81,6 +59,7 @@ data.addDiscovery(disco)
 
 ### Under the hood
 
+#### Zabbix::Sender::Pipe method:
 The zabbix-sender cli utility provides a number of methods by which to insert data into zabbix. 
 
  * zabbix-sender ... -s zabbixHostName -k keyName -o value (one k-v pair at a time)
@@ -120,3 +99,21 @@ If you wished to use the above lld to actually do some discovery, you'd set thin
 
 ![Discovery rule configuration](images/Spectacle.Z29721.png)
 ![Item prototype configuration](images/Spectacle.l29721.png )
+
+#### Zabbix::Sender::Socket method:
+
+You can switch between using the Pipe(zabbix_sender) method and the Socket(direct to zabbix via tcp socket) method very simply.  Just change:
+
+```
+sender = Zabbix::Sender::Pipe.new
+```
+to
+```
+sender = Zabbix::Sender::Socket.new
+```
+
+If you were specifiying a path to zabbix_sender using the Pipe method, remove that.  If you're using a socket other than 10051 on your server/proxy,  you'll want to add the port: option
+
+The socket method doesn't support sending multiple batches between flushes, so you should just use sendBatchAtomic(aBatch) with the Socket method.
+
+You don't have to change anything else - the rest of zabbix_sender_api works exactly the same with the Socket method, save for that it's arguably more efficient with system resources.  The only drawback might be if zabbix changes the sender protocol.  At that point until this library is update to support the change you can revert to the Pipe/zabbix_sender method if needed (if they change the command line switches radically there, changes will be required in this library as well).

data/bin/bundle

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+  module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_version
+    @bundler_version ||=
+      env_var_version || cli_arg_version ||
+        lockfile_version
+  end
+
+  def bundler_requirement
+    return "#{Gem::Requirement.default}.a" unless bundler_version
+
+    bundler_gem_version = Gem::Version.new(bundler_version)
+
+    requirement = bundler_gem_version.approximate_recommendation
+
+    return requirement unless Gem::Version.new(Gem::VERSION) < Gem::Version.new("2.7.0")
+
+    requirement += ".a" if bundler_gem_version.prerelease?
+
+    requirement
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    activate_bundler
+  end
+
+  def activate_bundler
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_requirement
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end

data/bin/byebug

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'byebug' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("byebug", "byebug")

data/bin/coderay

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'coderay' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("coderay", "coderay")

data/bin/example.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'example.rb' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("zabbix_sender_api", "example.rb")

data/bin/pry

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'pry' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("pry", "pry")

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/lib/zabbix_sender_api/api.rb

@@ -1,20 +1,26 @@
 module Zabbix
 require 'socket'
 require 'json'
+require 'open3'
 
 ##
 # AgentConfiguration holds data that's scraped from a zabbix_agentd config file.  It's 
-# initialized when the gem is required.  If it finds configuration you can
+# initialized when the gem is required.  You may optionally re-initialize the
+# class with your own list of paths to search.  If it finds configuration you can
 # access it with class methods.  This is not meant to be instantiated.
-
 class AgentConfiguration
-  def self.initialize 
-    @agentConfPaths = [
+  ##
+  # You may optionally pass an array of full paths to agent conf files to look for
+  # during initialization.  By default some common places are checked, but
+  # you can specify your own.  If you call this you'll re-initialize the class, which
+  # will scan for values in any of the listed files it happens to find.
+  def self.initialize(paths: [
             '/etc/zabbix/zabbix_agentd.conf',
             '/usr/local/etc/zabbix/zabbix_agentd.conf',
             '/opt/zabbix/etc/zabbix_agentd.conf',
             '/opt/zabbix/conf/zabbix_agentd.conf'
-    ]
+    ])
+    @agentConfPaths = paths
 
     @proxy = nil
     @hostname = nil
@@ -63,50 +69,155 @@ module Sender
 require 'set'
 
 ##
-# Pipe instances encapsulate communication to a running instance of zabbix_sender
-# via a pipe to STDIN.  If you want your program to send data itself (as opposed
-# to say printing stdin lines that you can then pipe to zabbix_sender yourself),
-# you'll want to make an instance of this
-#
-class Pipe
-  ##
-  # pipe file handle object
-  attr_reader :pipe
+# Connection is an abstract class that defines the basis of specific
+# connection types (Pipe, Socket).  It is not meant to be instantiated
+# on its own.
+class Connection
   ##
   # target host (server or proxy) name or ip
   attr_reader :targetHost
+  attr_reader :pipe
+  ##
+  # Initialize a new Connector object.  Proxy is optional.
+  #
+  #
+  # An attempt is made to provide sane default values.  If you have a zabbix_agentd.conf
+  # file in one of the usual places and zabbix_sender is on your path, it'll probably 
+  # just work
+  #
+  def initialize(proxy: Zabbix::AgentConfiguration.zabbixProxy)
+    @targetHost = proxy
+    @pipe = nil
+  end
+  ##
+  #  Aborts execution if directly called. Subclasses must override.
+  #
+  def open
+    abort("Call to abstract method Connection::open")
+  end
+  ##
+  # Aborts execution if directly called. Subclasses must override.
+  #
+  def sendBatch(aBatch)
+    abort("Call to abstract method Connection::sendBatch(aBatch)")
+  end
+  ##
+  # Send a Batch instance to zabbix (via zabbix_sender).  This opens the pipe,
+  # writes the data to the pipe, and closes the pipe all in one go.
+  #
+  def sendBatchAtomic(aBatch)
+    self.open
+    self.sendBatch(aBatch)
+    return self.flush
+  end
+  ##
+  # Closes the zabbix_sender pipe if it's open
+  #
+  def flush
+    if @pipe and not @pipe.closed?
+      @pipe.close
+    end
+  end
+end
+
+##
+# Socket instances enable TCPSocket based communication with a zabbix trapper server instance
+# 
+class Socket < Connection
+  attr_reader :port
+  ##
+  # Create a new socket connection object. Both proxy and port are optional.
+  #
+  # An attempt is made to provide sane default values.  If you have a zabbix_agentd.conf
+  # file in one of the usual places and zabbix_sender is on your path, it'll probably 
+  # just work
+  #
+  def initialize(proxy: Zabbix::AgentConfiguration.zabbixProxy, port: 10051)
+    super(proxy: proxy)
+    @port = port
+    @lastres = nil
+  end
+  ##
+  # Open tcp socket to target proxy/server
+  #
+  def open
+    @pipe = TCPSocket.new(@targetHost, @port)
+  end
   ##
-  # path to the zabbix_sender executable
-  attr_reader :exePath
+  # Send aBatch to zabbix via the socket.  Note that zabbix will close
+  # the connection after you send a complete message, so you
+  # *can't* do this:
+  #
+  # socket.open
+  # socket.sendBatch(a)
+  # socket.sendBatch(b)  <-- this will blow up
+  # socket.flush
+  #
+  # ...as you can with Zabbix::Sender::Pipe. You're really best off
+  # just using sendBatchAtomic for sockets.
+  #
+  # This assumes that the socket is already open.
+  #
+  def sendBatch(aBatch)
+    header = %Q(ZBXD\x01)
+    data = aBatch.to_senderstruct.to_json
+    blob = %Q(#{header}#{[data.bytesize].pack("Q").force_encoding("UTF-8")}#{data})
+    @pipe.write(blob)
+    respHeader = @pipe.read(header.bytesize + 8)
+    datalen = respHeader[header.bytesize, 8].unpack("Q")[0]
+    @lastres = JSON.parse(@pipe.read(datalen))
+  end
 
+  def flush
+    super
+    return @lastres
+  end
+end
+
+##
+# Pipe instances utilize communication to a running instance of zabbix_sender
+# via a pipe to STDIN.  If you want your program to send data itself (as opposed
+# to say printing stdin lines that you can then pipe to zabbix_sender yourself),
+# you'll want to make an instance of this
+#
+class Pipe < Connection
 
   ##
-  # Initialize a new Sender object.  Both proxy: and path: are optional.
+  # Create a new Pipe object.  Both proxy: and path: are optional.
   #
   # An attempt is made to provide sane default values.  If you have a zabbix_agentd.conf
   # file in one of the usual places and zabbix_sender is on your path, it'll probably 
   # just work
   #
   def initialize(proxy: Zabbix::AgentConfiguration.zabbixProxy, path: 'zabbix_sender')
-    @targetHost = proxy
+    super(proxy: proxy)
+    @wait_thr = @stdout = @stderr = nil
     @exePath = path
-    @pipe = nil
   end
 
   ##
   # Opens a pipe to the zabbix_sender command with appropriate options specified.
   # If the pipe is already opened when this command is called, it is first closed
   # via a call to flush
+  #
   def open
     self.flush
-    @pipe = IO.popen(%Q(#{@exePath} -z #{@targetHost} -vv -T -i-),'w')
+    #@pipe = IO.popen(%Q(#{@exePath} -z #{@targetHost} -vv -T -i-),'w')
+    cmd = %Q(#{@exePath} -z #{@targetHost} -vv -T -i-)
+    @pipe,@stdout,@stderr,@wait_thr = Open3.popen3(cmd)
   end
 
   ##
-  # Closes the zabbix_sender pipe if it's open
+  # Closes the open3 pipe stuff.  We need this override method as
+  # closing an open3 pipe requires some extra work.
   def flush
     if @pipe and not @pipe.closed?
       @pipe.close
+      stdout = @stdout.read
+      stderr = @stderr.read
+      @stdout.close
+      @stderr.close
+      return {stdout: stdout, stderr: stderr, success: @wait_thr.value.success?}
     end
   end
 
@@ -118,14 +229,6 @@ class Pipe
     @pipe.puts(aBatch.to_senderline)
   end
 
-  ##
-  # Send a Batch instance to zabbix (via zabbix_sender).  This opens the pipe,
-  # writes the data to the pipe, and closes the pipe all in one go.
-  def sendBatchAtomic(aBatch)
-    self.open
-    self.sendBatch(aBatch)
-    self.flush
-  end
 
 end
 
@@ -165,6 +268,21 @@ class ItemData
     end
     return %Q("#{@hostname}" #{@key} #{@timestamp.to_i} #{@value}\n)
   end
+  ##
+  # Render the ItemData instance as an object suitable for conversion to json, for socket transmission
+  def to_senderstruct
+    if @timestamp.to_i == 0
+      puts %Q("#{@hostname}" #{@key} #{@timestamp.to_i} #{@value}\n)
+      abort("Attempt was made to render a timestamp of zero.  You DO NOT want this - it can kill db performance. Fix it.")
+    else
+      return item = {
+        host: @hostname,
+        key: @key,
+        value: @value,
+        clock: @timestamp.to_i
+      }
+    end
+  end
 end
 
 ##
@@ -198,12 +316,25 @@ class Discovery < ItemData
     @entities.add(zabbified)
   end
   ##
-  # Render this discovery instance as a zabbix_sender line.
+  # Render this discovery as the structure an external discovery script should return.  You can use this
+  # if you're writing custom external discovery logic
   #
-  def to_senderline
+  def to_discodata
     disco = { 'data'=>Array.new }
     disco['data'] = @entities.to_a
-    @value = disco.to_json
+    return disco
+  end
+  ##
+  # Render this discovery instance as a zabbix_sender line.
+  #
+  def to_senderline
+    @value = self.to_discodata.to_json
+    super
+  end
+  ##
+  # Render this discovery instance as an object suitable for conversion to json for socket transmission
+  def to_senderstruct
+    @value = self.to_discodata
     super
   end
 end
@@ -262,6 +393,12 @@ class Batch
     @data.unshift(aDiscovery)
   end
 
+  ##
+  #  Append another batch's data into this one.
+  def appendBatch(aBatch)
+    @data.append(*aBatch.data)
+  end
+
   ##
   # Render this batch of data as a sequence of lines of text appropriate
   # for sending into zabbix_sender
@@ -269,6 +406,16 @@ class Batch
   def to_senderline
     @data.collect {|line| line.to_senderline}.join
   end
+  ##
+  # Render this batch as a json object
+  #
+  def to_senderstruct
+    return batch = {
+      request: "sender data",
+      data: @data.collect {|item| item.to_senderstruct},
+      clock: @time.to_i
+    }
+  end
 end
 
 end # module Sender