Snap Agent Development Library

Snap Agent plugins gather useful metrics from Docker containers, Kubernetes clusters, mongoDB databases, and several other Integrations possibilities. If you need to pull data from a system that's not listed as one of the official SolarWinds Integrations and cannot be found in the Community Plugin Catalog, you can write your own custom plugin using the Snap plugin library.

Snap plugin library

The Snap plugin library (https://github.com/solarwinds/snap-plugin-lib) is a framework that helps developers write plugins to work within the Snap environment. It handles the communication between your environment and Snap and it simplifies common operations, such as adding metrics, processing configuration, and filtering.

While the library is developed for the Go language, Python and C# plugins can take advantage of the library through Cgo integration. The currently active and maintained version of the Snap plugin library is v2.

Useful links

For a comprehensive tutorial covering the majority of the main features, visit https://github.com/solarwinds/snap-plugin-lib/tree/master/v2#content.

For examples of streaming collectors, publishers, and other plugins:

• https://github.com/solarwinds/snap-plugin-lib/tree/master/examples/v2 for Go examples

• https://github.com/solarwinds/snap-plugin-lib/tree/master/v2/bindings for C# and Python examples.

Writing a custom collector

Code

Writing a simple plugin using Go is very straightforward. In the following code sample, the Collect method will be triggered by snap, based on interval defined in task configuration (usually every 1 minute).

package mainimport (
    "github.com/solarwinds/snap-plugin-lib-go/v2/plugin"
    "github.com/solarwinds/snap-plugin-lib-go/v2/runner"
)
type myCollector struct {}
func (c *myCollector) Collect(ctx plugin.CollectContext) error {
    _ = ctx.AddMetric("/example/static/value", 34)
    return nil
}
func main() {
    runner.StartCollector(&myCollector{}, "example-collector", "1.0.0")
}

Installation

Compiling source code

To compile the sample plugin, execute the following command:

go build -o snap-plugin-collector-example

Signing plugin

By default, all plugins executed by Snap must be signed with a proper certificate. For the details, see the topic Signing plugins. 

If you are working in an environment that can operate with reduced security, such as a non-production environment, you can modify config.yaml to disable signing validation. See Security - Signed plugins for more information and instructions.

Add executable to bin folder.

Move your compiled code to the Snap binaries folders.

sudo mv snap-plugin-collector-example /opt/SolarWinds/Snap/bin
sudo chown solarwinds:solarwinds /opt/SolarWinds/Snap/bin/snap-plugin-collector-example

Create task

Create a new yaml file for the compiled plugin in the tasks-autoload.d folder. The following task-example.yaml file was created for the snap-plugin-collector-example sample plugin.

---
version: 2
schedule:
  type: cron
  interval: "0 * * * * *"
plugins:
  - plugin_name: example
    binary_name: snap-plugin-collector-example
    config:
    metrics:
      - /example/static/value
    publish:
      - plugin_name: publisher-appoptics

Validate if custom task is running

Restart the Snap service to enable the new task. You can validate the setup is correct by executing the following commands:

swisnap plugin list
swisnap task list

The first command lists all running plugins. If everything was set up correctly it will list example-collector. The second command lists all running tasks and should include task-example.yaml.

Enabling custom metrics in AppOptics

Metrics from custom plugins are filtered out by AppOptics by default. To change this behavior, login to AppOptics and go to the Integrations page. The example-collector plugin should be listed under Community Plugins.

Click on the example-collector plugin to expand the details pane. In the details pane, click Enable Plugin. Once enabled, AppOptics will start accepting the metric /example/static/value.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.