snap plugin for collecting outputs of executable files
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

DISCONTINUATION OF PROJECT

This project will no longer be maintained by Intel. Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates. Patches to this project are no longer accepted by Intel. If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the community, please create your own fork of the project.

snap plugin collector - exec

A generic plugin to launch executable files and collects their outputs.

WARNING: This plugin gives the power to run any program on the server. Running this plugin with root privileges may be extremely dangerous and it is not advised.

  1. Getting Started
  1. Documentation
  1. Community Support
  2. Contributing
  3. License
  4. Acknowledgements

Getting Started

System Requirements

Operating systems

All OSs currently supported by Snap:

  • Linux/amd64

Installation

Download exec plugin binary:

You can get the pre-built binaries for your OS and architecture at Snap's Github Releases page.

To build the plugin binary:

Fork https://github.com/intelsdi-x/snap-plugin-collector-exec

Clone repo into $GOPATH/src/github/intelsdi-x/:

$ git clone https://github.com/<yourGithubID>/snap-plugin-collector-exec

Build the plugin by running make in repo:

$ make

This builds the plugin in /build/rootfs.

Configuration and Usage

Why Snap Global Config is required

Notice that this plugin is a generic plugin. It cannot work without configuration, because there is no reasonable default behavior. Errors in configuration or in execution of the commands run by this plugin will block collecting of metrics and will show up in plugin log files.

A Note on Security

The Setfile contains configuration which should be protected. It is advised to limit access for this configuration and regularly audit its content.

It is not advised to use dynamic query notation in task manifest for exec plugin. Users should consciously make decision on the executing command to avoid unexpected changes to the system.

Other important notes on usage

The executable file which is used to collect metrics must write its output (value of metric) to standard output (stdout) in plain form, without unnecessary white characters.

User interaction cannot be needed by executable file. Some commands or programs require special privileges to execute, so be aware of configuration to ensure successful runs.

The executable file will launch a process for each metric gathered and will be launch at the interval set in the Task Manifest (or through snaptel). Processes are expected to end and clean up any used resources between runs. This behavior may have impact on system performance.

Documentation

Collected Metrics

The plugin collects the outputs of executable files as metrics in the namespace /intel/exec/<metric_name>/.

Each metrics's name is defined in the Setfile. Metrics can be any of the following data types: float64, float32, int64, int32, int16, int8, uint64, uint32, uint16, uint8, string.

Snap's Global Config

Global configuration files are described in snap's documentation. A section is required, titled "exec" in "collector", with the following options:

  • "setfile" - path to exec plugin configuration file (path to Setfile),
  • "execution_timeout" - max time for command/program execution in seconds (default value: 10 sec).

See example Global Config in examples/cfg/.

Setfile structure

Setfile contains a JSON structure which is used to define metrics. Each metric is defined as JSON object in following format:

  "<metric_name>": {
            "exec": "<executable_file>",
            "type": "<data_type>",
            "args": [ "<arg1>", "<arg2>", "<arg3>"]
    }

Where:

  • metric_name - metric name which is used in metric's namespace (required),
  • executable_file - path to executable file which should by launch to collect metric (required),
  • data_type - metric data type (required)
  • arg1, arg2, arg3 - arguments needed by executable file which is used to collect metric (optional).

For example 'echo_metric' metric for the 'echo' program is available in '/bin' with arguments '-n', '1.1' and results in a float64 data type should have the following definition:

  "echo_metric": {
            "exec": "/bin/echo",
            "type": "float64",
            "args": ["-n", "1.1"]
    }

The metric defined above has the following namespace /intel/exec/echo_metric.

If the running process returns metric with additional information, it will require another tool to extract the target values from the output. For example, the below example shows extraction of numeric data from output of echo:

"echo_metric": {
				"exec": "/bin/sh",
				"type": "int64",
				"args": [ "-c", "echo  \"test:1775\" | awk -F':' '{printf $2}' | tr -d \"\n\""]
		}

As you can see, exec in setfile could be defined as a combination of commands.

Note: If your command returns result with a newline, you can use tr -d \"\n\" to delete newline characters.

Examples

To walk through a working example of snap-plugin-collector-exec, follow these steps:

  1. Create a configuration file (setfile) or copy the example file at examples/setfiles/.

  2. Copy the example Setfile and then set the correct path to the configuration file as the field setfile along with a max time for the process to execute as the field execution_timeout in Global Config (examples/configs/).

  3. In one terminal window, start snapteld, the Snap daemon, (in this case with logging set to 1, trust disabled and global configuration saved in config.json ):

$ snapteld -l 1 -t 0 --config config.json
  1. In another terminal window:

Load snap-plugin-collector-exec plugin

$ snaptel plugin load snap-plugin-collector-exec

Load file plugin for publishing:

$ snaptel plugin load snap-plugin-publisher-file

See available metrics for your system

$ snaptel metric list
  1. Write a Task Manifest (example in examples/tasks/):
{
{
    "version": 1,
    "schedule": {
        "type": "simple",
        "interval": "5s"
    },
    "workflow": {
        "collect": {
            "metrics": {
                "/intel/exec/metric0": {},
                "/intel/exec/metric1": {},
                "/intel/exec/metric2": {},
                "/intel/exec/metric3": {},
                "/intel/exec/metric4": {}
           },
            "config": {
            },
            "process": null,
            "publish": [
                {
                    "plugin_name": "file",
                    "config": {
                        "file": "/tmp/published_exec"
                    }
                }
            ]
        }
    }
}
  1. Now create the task from the Task Manifest:
$ snapctl task create -t task.json
ID: ef720332-8f0f-4cd7-84f8-73219d403c35
Name: Task-ef720332-8f0f-4cd7-84f8-73219d403c35
State: Running
  1. And watch the metrics populate:
$ snapctl task watch ef720332-8f0f-4cd7-84f8-73219d403c35

Roadmap

There isn't a current roadmap for this plugin, but it is in active development. As we launch this plugin, we do not have any outstanding requirements for the next release.

If you have a feature request, please add it as an issue and feel free to then submit a pull request.

Community Support

This repository is one of many plugins in Snap, the open telemetry framework. See the full project at http://github.com/intelsdi-x/snap. To reach out to other users, head to the main framework.

Contributing

We love contributions!

There's more than one way to give back, from examples to blogs to code updates. See our recommended process in CONTRIBUTING.md.

And thank you! Your contribution, through code and participation, is incredibly important to us.

License

Snap, along with this plugin, is an Open Source software released under the Apache 2.0 License.

Acknowledgements