Skip to content

Latest commit

 

History

History
121 lines (86 loc) · 6.42 KB

README.md

File metadata and controls

121 lines (86 loc) · 6.42 KB

Snap Plugin Library for Go Build Status Go Report Card

This is a library for writing plugins in Go for the Snap telemetry framework.

Notice: Due to standarization which was made in the Logrus project, its import path has been changed from Sirupsen to sirupsen. If you see case-sensitive import collision reporting by glide after updating your plugin to the latest snap-plugin-lib-go, please do the following steps:

  • change every import of Logrus to lower case: github./com/sirupsen/logrus,
  • delete folder vendor/github.com/Sirupsen,
  • rename references in glide.yaml and glide.lock
  • clear glide cache (glide -c),
  • update dependencies (glide update)

More information can be found in Logrus GitHub repo.

Table of Contents

  1. Writing a Plugin
  2. Brief Overview of Snap Architecture
  3. Example Plugins
  4. Plugin Flags

Writing a Plugin

Snap has four different plugin types. Instructions on how to write each type of a plugin can be found in the following locations: collector, processor, publisher, and streaming collector.

Before writing a Snap plugin:

If you do decide to write a plugin reference plugin authoring docs and let us know you are working on one!

Brief Overview of Snap Architecture:

Snap is an open and modular telemetry framework designed to simplify the collection, processing and publishing of data through a single HTTP based API. Plugins provide the functionality of collection, processing and publishing, and can be loaded/unloaded, upgraded and swapped without requiring a restart of the Snap daemon.

A Snap plugin is a program that responds to a set of well defined gRPC services with parameters and return types specified as protocol buffer messages (see plugin.proto). The Snap daemon handshakes with the plugin over stdout and then communicates over gRPC.

Snap Plugin Go Library Examples:

You will find example plugins that cover the basics for writing collector, processor, publisher, and streaming collector plugins in the examples folder.

Plugin Flags:

For specific details and to see all the options available, run the plugin with the -help flag. The flag options are:

GLOBAL OPTIONS:
   --config value            config to use in JSON format
   --port value              port GRPC will listen on
   --pprof                   enable pprof
   --tls                     enable TLS
   --cert-path value         necessary to provide when TLS enabled
   --key-path value          necessary to provide when TLS enabled
   --root-cert-paths value   root paths separated by ':'
   --stand-alone             enable stand alone plugin
   --stand-alone-port value  specify http port when stand-alone is set (default: 8181)
   --log-level value         log level - 0:panic 1:fatal 2:error 3:warn 4:info 5:debug (default: 2)
   --required-config         Plugin requires config passed in
   --help, -h                show help
   --version, -v             print the version

Additionally, plugin authors can add custom flags as described here

Custom Config:

Users can provide their own config with the -config flag. If a config is required for the plugin to load, diagnostics will show a warning describing which keys are required but not provided.

When using the -config flag, it expects a parameter in the form of a JSON. This is of the form '{}'. An example config is: -config '{\"key\":\"kelly\", \"spirit-animal\":\"coatimundi\"}'.

Plugin Diagnostics:

Snap plugins using plugin-lib-go can be run independent of Snap to show their current running diagnostics.

Running plugin diagnostics is easy! Simply build the plugin, then run the executable $./build/${GOOS}/${GOARCH}/<plugin binary>.

Diagnostic information includes:

  • Runtime details
    • Plugin version
    • RPC type and version
    • OS, architecture
    • Golang version
  • Warning if dependencies not met
  • Config policy (for collector plugins only)
    • Warning if config items required and not provided
  • Collectable metrics (for collector plugins only)
  • How long it took to run each of these diagnostics

Currently Snap Plugin Diagnostics is only available for collector plugins.

Custom Flags

Plugins authors using snap-plugin-lib-go have the ability to create customized runtime flags. These flags are written using urfave/cli. An example of a custom flag in a plugin can be found in the snap-plugin-collector-rand example.

Flags can be added with the following syntax:

plugin.AddFlag(
		cli.BoolFlag{
			Name:        "required-config",
			Hidden:      false,
			Usage:       "Plugin requires config passed in",
			Destination: &req,
		},
	)

More information about types of cli flags and options for each flag can be found in the documentation for urfave/cli

As always, if you have any questions, please reach out to the Snap team via Slack or by opening an issue in github.