Documentation forAppOptics

Snap Agent Development Library

Snap Agent plug-ins 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 plug-in using the Snap plug-in library.

Snap plug-in library

The Snap plug-in library (https://github.com/solarwinds/snap-plugin-lib) is a framework that helps developers write plug-ins 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# plug-ins can take advantage of the library through Cgo integration. The currently active and maintained version of the Snap plug-in 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 plug-ins:

Writing a custom collector

Code

Writing a simple plug-in 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).

Copy
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 plug-in, execute the following command:

Copy
go build -o snap-plugin-collector-example

If the plug-in will be run on a Windows system, add the file extension .exe

Signing plug-in

By default, all plug-ins 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.

Copy
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 plug-in in the tasks-autoload.d folder. The following task-example.yaml file was created for the snap-plugin-collector-example sample plug-in.

Copy
---
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:

Copy
swisnap plugin list
swisnap task list

The first command lists all running plug-ins. 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 plug-ins are filtered out by AppOptics by default. To change this behavior, login to AppOptics and go to the Integrations page. The example-collector plug-in should be listed under Community Plugins.

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

When the APM Integrated Experience is enabled, AppOptics shares a common navigation and settings with the other integrated experiences' products. How you navigate AppOptics and access its features may vary from these instructions. For more information, go to the APM Integrated Experience documentation.

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.