Task File

Overview

SWISnap works based on tasks. Tasks are the manifests for work to be done by the plugins and are required by SWISnap to actually start collecting data. For example, a task defines that apache plugin will be collecting metrics and those metrics will be sent to AppOptics by AppOptics publisher. Tasks can be written using YAML (default) or JSON syntax. Two types of tasks are supported:

• legacy tasks that are used for plugins compatible with V1 plugins API
• new tasks that are used for plugins compatible with V2 plugins API

Schedule

The schedule defines how often and for how long tasks should be processed. SWISnap supports four types of schedules.

Simple

It allows defining intervals in which data should be collected. By default, such schedule runs forever, but by setting count user can specify number of executions.

"schedule":
  type: simple
  interval: "1s"
  # count: 1

Cron

Very similar as a simple schedule, but supports cron like syntax in interval setting. It does not allow to specify count.

"schedule":
  type: cron
  interval: "0 * * * * *"

Windowed

It allows to define start/stop time, interval and count for executing task.

schedule:
  type: windowed
  interval: "10s"
  count: 10
  start_timestamp: "2020-01-30T16:00:00+01:00"
  stop_timestamp: "2020-01-30T16:30:00+01:00"

By not specifying count, the task will be executed until time window will end.

By not specifying start_timestamp, the task will start immediately.

By not specifying stop_timestamp, the task will run forever if count was also not specified.

Streaming

It is dedicated for streaming plugins. Such plugins wait (listen) for the data and report data immediately after it's available, not using any predefined schedule.

schedule:
type: streaming

Task Structure

The version setting in task specifies which task structure is used. The schedule section is common for tasks version 1 and 2.

New Tasks - Version 2

New task format allows to easily define everything what is needed to execute a task. It includes schedule, list of collectors and publishers with their configurations, list of metrics and tags:

---
## Version specifies task file structure.
version: 2
 
## Optional parameters
# name: "my system task"
# deadline: "55s"
# start: true
# max-failures: -1
# max-collect-duration: "10s"
# max-metrics-buffer: 0
 
## Schedule describes type and interval for running the task.
schedule:
 type: simple
 interval: "60s"
 
## List of plugins to be used for this task.
## Each entry needs to specify collector and publisher plugin.
plugins:
 
 - plugin_name: system
   # binary_name: snap-plugin-collector-aosystem
   # plugin_version: "1.0.0"
 
   ## Plugin configuration needed to execute task.
   config:
     mount_points:
       - /dev
 
   ## List of metrics requested for collection.
   metrics:
     - /system/cpu/guest
     - /system/cpu/idle
     - /system/cpu/interrupt
 
   ## Tags that will be added to collected metrics.
   tags:
     /:
       environment: production
     /system/cpu/interrupt:
       type: important
 
   ## List of publishers which will be sending out metrics from collector.
   publish:
     - plugin_name: publisher-appoptics
       # binary_name: snap-plugin-publisher-appoptics
       # plugin_version: "2.0.0"
      
       ## Publisher configuration needed to execute task.
       config:
 
 - plugin_name: processes
   config:
     aggregation: system
   metrics:
     # List of metrics requested for collection.
     - /processes/[process_name]/memory
     - /processes/[process_name]/uptime
   tags:
     aggregation_type: system
 
   publish:
     - plugin_name: publisher-processes

• version specifies version of task syntax.
• name specifies custom name for a task visible. For example, in swisnap task list command output. It is optional setting and SWISnap will generate task name based on file name.
• deadline specifies in what time whole task collect operations should be completed. By default it is set to 55s.
• start specifies if task should be started on loading. Used when loading with SWISnap REST API. With autoload always true.
• max-failures specifies number of max collect failures after which task will be disabled. By default set to -1.
• max-collect-duration specifies time required for collect operations to finish. It needs to be smaller or equal to deadline. By default set to 10s.
• max-metrics-buffer specifies if plugin should wait until buffer is filled with number of metrics before sending. Used when streaming schedule is selected. Default is 0, send immediately.
• schedule section specifies how task shuld be run.
• plugins section lists collectors/publishers that will be requested to collect/send data.
  • plugin_name specifies name of plugin. This setting is mandatory.
  • binary_name specifies the plugin binary that needs to bin in SWISnap bin folder. If not specified, SWISnap will detect the binary based on plugin_name setting, where for collectors it will be snap-plugin-collector-<plugin_name> and for publishers it will be snap-plugin-publisher-<plugin_name>.
  • plugin_version specifies version of plugin that needs to be used. If not specified, latest version of plugin will be used.
  • config section contains configuration specific for a given plugin. Comparing to legacy task files, full YAML/JSON configuration syntax is supported. This configuration will be merged with plugin configuration template. We use this feature especially for plugins that are commonly used with the same configuration, like publisher-appoptics, where in configuration template token is set.
  • metrics section contains a list of metrics that should be collected. If not specified, collector will return all metrics that it reports. Refer to metrics format for more details.
  • tags section specifies additional tags that will be set for each collected metrics. If not specified, no additional tags will be added.
  • publish section contains a list of publisher plugins used for sending out data. Similar settings as for collectors are available. Usually, publisher configuration is specified in plugin configuration template.

Legacy Tasks - Version 1

For detailed description of task format, please refer to Snap Telemetry Framework 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.