{"id":21470038,"url":"https://github.com/sensu-plugins/sensu-plugin","last_synced_at":"2025-05-16T04:03:42.022Z","repository":{"id":1782940,"uuid":"2706701","full_name":"sensu-plugins/sensu-plugin","owner":"sensu-plugins","description":"A framework for writing Sensu plugins \u0026 handlers with Ruby.","archived":false,"fork":false,"pushed_at":"2021-10-12T23:42:06.000Z","size":270,"stargazers_count":126,"open_issues_count":13,"forks_count":117,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-08T14:07:16.901Z","etag":null,"topics":["library","monitoring","ruby"],"latest_commit_sha":null,"homepage":"http://sensuapp.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"9apps/pgRDS","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sensu-plugins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-11-04T02:23:36.000Z","updated_at":"2024-05-31T08:21:43.000Z","dependencies_parsed_at":"2022-08-20T17:10:25.146Z","dependency_job_id":null,"html_url":"https://github.com/sensu-plugins/sensu-plugin","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensu-plugins%2Fsensu-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensu-plugins%2Fsensu-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensu-plugins%2Fsensu-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sensu-plugins%2Fsensu-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sensu-plugins","download_url":"https://codeload.github.com/sensu-plugins/sensu-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464891,"owners_count":22075570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","monitoring","ruby"],"created_at":"2024-11-23T09:21:22.022Z","updated_at":"2025-05-16T04:03:42.001Z","avatar_url":"https://github.com/sensu-plugins.png","language":"Ruby","readme":"# Sensu Plugin\n\n[![Build Status](https://travis-ci.org/sensu-plugins/sensu-plugin.svg?branch=master)](https://travis-ci.org/sensu-plugins/sensu-plugin)\n[![Gem Version](https://badge.fury.io/rb/sensu-plugin.svg)](http://badge.fury.io/rb/sensu-plugin)\n[![Dependency Status](https://gemnasium.com/sensu-plugins/sensu-plugin.svg)](https://gemnasium.com/sensu-plugins/sensu-plugin)\n[![pullreminders](https://pullreminders.com/badge.svg)](https://pullreminders.com?ref=badge)\n\nThis is a framework for writing your own Sensu plugins and handlers.\nIt's not required to write a plugin (most Nagios plugins will work\nwithout modification); it just makes it easier.\n\nExamples of plugins written with and without it can be found in\nthe `sensu-plugins` organization.\n\n## Checks and Metrics\n\nTo implement your own check, subclass `Sensu::Plugin::Check::CLI`, like\nthis:\n\n```ruby\nrequire 'sensu-plugin/check/cli'\n\nclass MyCheck \u003c Sensu::Plugin::Check::CLI\n\n  check_name 'my_awesome_check' # defaults to class name\n  option :foo, :short =\u003e '-f' # Mixlib::CLI is included\n\n  def run\n    ok \"All is well\"\n  end\n\nend\n```\n\nThis will output the string \"my_awesome_check OK: All is well\" (like a\nNagios plugin), and exit with a code of 0. The available exit methods,\nwhich will immediately end the process, are:\n\n * `ok`\n * `warning`\n * `critical`\n * `unknown`\n\nYou can also call `message` first to set the message, then call an exit\nmethod without any arguments (for example, if you want to choose between\nWARNING and CRITICAL based on a threshold, but use the same message in\nboth cases).\n\nFor a metric, you can subclass one of the following:\n\n * `Sensu::Plugin::Metric::CLI::JSON`\n * `Sensu::Plugin::Metric::CLI::Graphite`\n * `Sensu::Plugin::Metric::CLI::Statsd`\n * `Sensu::Plugin::Metric::CLI::Dogstatsd`\n * `Sensu::Plugin::Metric::CLI::Influxdb`\n * `Sensu::Plugin::Metric::CLI::Generic`\n\nInstead of outputting a Nagios-style line of text, these classes will output\ndifferently formated messages depending on the class you chose.\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyJSONMetric \u003c Sensu::Plugin::Metric::CLI::JSON\n\n  def run\n    ok 'foo' =\u003e 1, 'bar' =\u003e 'anything'\n  end\n\nend\n```\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyGraphiteMetric \u003c Sensu::Plugin::Metric::CLI::Graphite\n\n  def run\n    ok 'sensu.baz', 42\n  end\n\nend\n```\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyStatsdMetric \u003c Sensu::Plugin::Metric::CLI::Statsd\n\n  def run\n    ok 'sensu.baz', 42, 'g'\n  end\n\nend\n```\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyDogstatsdMetric \u003c Sensu::Plugin::Metric::CLI::Dogstatsd\n\n  def run\n    ok 'sensu.baz', 42, 'g', 'env:prod,myservice,location:us-midwest'\n  end\n\nend\n```\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyInfluxdbMetric \u003c Sensu::Plugin::Metric::CLI::Influxdb\n\n  def run\n    ok 'sensu', 'baz=42', 'env=prod,location=us-midwest'\n  end\n\nend\n```\n\n```ruby\nrequire 'sensu-plugin/metric/cli'\n\nclass MyInfluxdbMetric \u003c Sensu::Plugin::Metric::CLI::Generic\n\n  def run\n    ok metric_name: 'metric.name', value: 0\n  end\n\nend\n```\n\n**JSON output** takes one argument (the object), and adds a 'timestamp'\nkey if missing. **Graphite output** takes two arguments, the metric path\nand the value, and optionally the timestamp as a third argument.\n`Time.now.to_i` is used for the timestamp if it is not\nspecified. **Statsd output** takes three arguments, the metric path, the\nvalue and the type.  **Dogstatsd output** takes three arguments, the\nmetric path, the value, the type and optionally a comma separated list\nof tags, use colons for key/value tags, i.e.  `env:prod`.  **Influxdb\noutput** takes two arguments, the measurement name and the value or a\ncomma separated list of values, use `=` for field/value,\ni.e. `value=42`, optionally you can also pass a comma separated list of\ntags and a timestamp `Time.now.to_i` is used for the timestamp if it is\nnot specified.  **Generic output** takes a dictionary and can provide\nrequested output format with same logic. And inherited class will have a\n`--metric_format` option to switch between different output formats.\n\nExit codes do not affect metric output, but they can still be used by\nyour handlers.\n\nSome metrics may want to output multiple values in a run. To do this,\nuse the `output` method, with the same arguments as the exit methods, as\nmany times as you want, then call an exit method without any arguments.\n\nFor either checks or metrics, you can override `output` if you want\nsomething other than these formats.\n\n### Options\n\nFor help on setting up options, see the `mixlib-cli` documentation.\nCommand line arguments that are not parsed as options are available via\nthe `argv` method.\n\n### Utilities\n\nVarious utility methods will be collected under Sensu::Plugin::Util.\nThese won't depend on any extra gems or include actual CLI checks; it's\njust for common things that many checks might want to do.\n\n## Handlers\n\nFor your own handler, subclass `Sensu::Handler`. It looks much like\nchecks and metrics; see the `handlers` directory for examples. Your class\nshould implement `handle`. The instance variable `@event` will be set\nfor you if a JSON event can be read from stdin; otherwise, the handler\nwill abort. Output to stdout will go to the log.\n\nYou can decide if you want to handle the event by overriding the\n`filter` method; but this also isn't documented yet (see the source; the\nbuilt in method does some important filtering, so you probably want to\ncall it with `super`).\n\n### Important!\n\nFiltering of events is now deprecated in `Sensu::Handler` and disabled\nby default as of version 2.0.\n\nEvent filtering in this library may be enabled on a per-check basis by setting\nthe value of the check's `enable_deprecated_filtering` attribute to `true`.\n\nThese built-in filters will be removed in a future release. See\n[this blog post](https://sensuapp.org/blog/2016/07/07/sensu-plugin-filter-deprecation.html)\nfor more detail.\n\n\n## Mutator\n\nFor your own mutator, subclass `Sensu::Mutator`. It looks much like\nchecks and metrics; Your class should implement `mutate`. The instance variable\n`@event` will be set for you if a JSON event can be read from stdin; otherwise,\nthe mutator will abort. Output to stdout will then be piped through to the\nhandler.  As described in the docs if a mutator fails to run the event will\nnot be handled.\n\nThe example mutator found [here](https://sensuapp.org/docs/latest/mutators) will\nlook like so:\n\n```ruby\nrequire 'sensu-mutator'\n\nclass MyMutator \u003c Sensu::Mutator\n\n  def mutate\n    @event.merge!(:mutated =\u003e true)\n  end\n\nend\n```\n\n## Plugin settings\n\nWhether you are writing a check, handler or mutator, Sensu's configuration\nsettings are available with the `settings` method (loaded automatically\nwhen the plugin runs). We recommend you put your custom plugin settings\nin a JSON file in `/etc/sensu/conf.d`, with a unique top-level key,\ne.g. `my_custom_plugin`:\n\n```json\n{\n  \"my_custom_plugin\": {\n    \"foo\": true,\n    \"bar\": false\n  }\n}\n```\n\nAnd access them in your plugin like so:\n\n```ruby\ndef foo_enabled?\n  settings['my_custom_plugin']['foo']\nend\n```\n\n## Sensu Go enablement\n\nThis plugin provides basic Sensu Go enablement support to make it possible to continue to use existing Sensu plugin handlers and mutators for Sensu Core 1.x event model in a backwards compatible fashion.\n\n### Sensu Go event mapping\n\nThe provided mutator command `mutator-sensu-go-into-ruby.rb` will mutate the Sensu Go event into a form compatible for handlers written to consume Sensu Core 1.x events.  Users may find this mutator useful until such time that community plugin handler are updated to support Sensu Go event model directly.\n\nSensu plugins which provide either mutators or handlers can benefit from provided Sensu Go enablement support in the form of mixin commandline option support.  Once plugins update to the latest sensu-plugin version, all mutator and handler commands will automatically grow an additional commandline argument `--map_go_event_into_ruby`\n\n### Custom attributes\n\nFor backwards compatibility, you can store custom entity and check attributes as a json string in a specially named annotation. By default the annotation key is `sensu.io.json_attributes`, but can be overridden using the environment variable `MAP_ANNOTATION`.  The json string stored in the `MAP_ANNOTATION` key will be converted into a ruby hash and merged into the ruby event hash object as part of the event mapping.  \n\n## Contributing\n\n * Fork repository\n * Add functionality and any applicable tests\n * Ensure all tests pass by executing `bundle exec rake test`\n * Open a pull request\n\nYou may run individual tests by executing `bundle exec rake test TEST=test/external_handler_test.rb`\n\n# License\n\nCopyright 2011 Decklin Foster\n\nReleased under the same terms as Sensu (the MIT license); see LICENSE\nfor details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsensu-plugins%2Fsensu-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsensu-plugins%2Fsensu-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsensu-plugins%2Fsensu-plugin/lists"}