DISCONTINUATION OF PROJECT.
This project will no longer be maintained by Intel.
This project has been identified as having known security escapes.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this 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.
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.
- golang 1.5+ - needed only for building
All OSs currently supported by Snap:
- Linux/amd64
You can get the pre-built binaries for your OS and architecture at Snap's Github Releases page.
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.
-
Set up the Snap framework.
-
Create the configuration file (called
setfile) using the examples below under setfile structure or by example inexamples/setfiles/. -
Create a Snap Global Config, which is a requirement for this plugin.
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.
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.
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.
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.
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 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.
To walk through a working example of snap-plugin-collector-exec, follow these steps:
-
Create a configuration file (setfile) or copy the example file at
examples/setfiles/. -
Copy the example Setfile and then set the correct path to the configuration file as the field
setfilealong with a max time for the process to execute as the fieldexecution_timeoutin Global Config (examples/configs/). -
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
- 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
- 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"
}
}
]
}
}
}
- 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
- And watch the metrics populate:
$ snapctl task watch ef720332-8f0f-4cd7-84f8-73219d403c35
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.
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.
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.
Snap, along with this plugin, is an Open Source software released under the Apache 2.0 License.
- Author: Katarzyna Kujawa