Commit 462d196c authored by Marcin Krolik's avatar Marcin Krolik Committed by GitHub

Merge pull request #23 from marcin-krolik/update/docs

Updated doc and example
parents c9d32cc1 951f01c9
# snap-plugin-collector-df
# Snap plugin collector - df
snap plugin for collecting free space metrics from df linux tool
Snap plugin for collecting free space metrics from df linux tool
1. [Getting Started](#getting-started)
* [System Requirements](#system-requirements)
......@@ -25,121 +25,96 @@ snap plugin for collecting free space metrics from df linux tool
* Linux system with df command
### Operating systems
All OSs currently supported by snap:
All OSs currently supported by Snap:
* Linux/amd64
### Installation
#### Download df plugin binary:
You can get the pre-built binaries for your OS and architecture at snap's [Github Releases](https://github.com/intelsdi-x/snap/releases) page.
#### Download the plugin binary:
You can get the pre-built binaries for your OS and architecture from the plugin's [GitHub Releases](https://github.com/intelsdi-x/snap-plugin-collector-df/releases) page. Download the plugin from the latest release and load it into `snapd` (`/opt/snap/plugins` is the default location for snap packages).
#### To build the plugin binary:
Fork https://github.com/intelsdi-x/snap-plugin-collector-df
Clone repo into `$GOPATH/src/github/intelsdi-x/`:
Fork https://github.com/intelsdi-x/snap-plugin-collector-df
Clone repo into `$GOPATH/src/github.com/intelsdi-x/`:
```
$ git clone https://github.com/<yourGithubID>/snap-plugin-collector-df
$ git clone https://github.com/<yourGithubID>/snap-plugin-collector-df.git
```
Build the plugin by running make in repo:
Build the snap df plugin by running make within the cloned repo:
```
$ make
```
This builds the plugin in `/build/rootfs`
This builds the plugin in `./build/`
### Configuration and Usage
* Set up the [snap framework](https://github.com/intelsdi-x/snap/blob/master/README.md#getting-started).
* Load the plugin and create a task, see example in [Examples](https://github.com/intelsdi-x/snap-plugin-collector-df/blob/master/README.md#examples).
* Set up the [Snap framework](https://github.com/intelsdi-x/snap#getting-started).
* Load the plugin and create a task, see example in [Examples](#examples).
## Documentation
### Collected Metrics
List of collected metrics is described in [METRICS.md](https://github.com/intelsdi-x/snap-plugin-collector-df/blob/master/METRICS.md).
List of collected metrics is described in [METRICS.md](METRICS.md).
### Examples
Example running snap-plugin-collector-df plugin and writing data to a file.
Make sure that your `$SNAP_PATH` is set, if not:
```
$ export SNAP_PATH=<snapDirectoryPath>/build
```
Other paths to files should be set according to your configuration, using a file you should indicate where it is located.
Ensure [snap daemon is running](https://github.com/intelsdi-x/snap#running-snap):
* initd: `service snap-telemetry start`
* systemd: `sysctl start snap-telemetry`
* command line: `snapd -l 1 -t 0 &`
In one terminal window, open the snap daemon (in this case with logging set to 1, trust disabled):
Download and load snap plugins:
```
$ $SNAP_PATH/bin/snapd -l 1 -t 0
$ wget http://snap.ci.snap-telemetry.io/plugins/snap-plugin-collector-df/latest/linux/x86_64/snap-plugin-collector-df
$ wget http://snap.ci.snap-telemetry.io/plugins/snap-plugin-publisher-file/latest/linux/x86_64/snap-plugin-publisher-file
$ chmod 755 snap-plugin-*
$ snapctl plugin load snap-plugin-collector-df
$ snapctl plugin load snap-plugin-publisher-file
```
In another terminal window:
Load snap-plugin-collector-df plugin:
See all available metrics:
```
$ $SNAP_PATH/bin/snapctl plugin load snap-plugin-collector-df
$ snapctl metric list
```
Load file plugin for publishing:
Download an [example task file](examples/tasks/df-file.json) and load it:
```
$ $SNAP_PATH/bin/snapctl plugin load $SNAP_PATH/plugin/snap-publisher-file
$ curl -sfLO https://raw.githubusercontent.com/intelsdi-x/snap-plugin-collector-df/master/examples/tasks/df-file.json
$ snapctl task create -t df-file.json
Using task manifest to create task
Task created
ID: 480323af-15b0-4af8-a526-eb2ca6d8ae67
Name: Task-480323af-15b0-4af8-a526-eb2ca6d8ae67
State: Running
```
See available metrics:
See realtime output from `snapctl task watch <task_id>` (CTRL+C to exit)
```
$ $SNAP_PATH/bin/snapctl metric list
$ snapctl task watch 480323af-15b0-4af8-a526-eb2ca6d8ae67
```
Create a task manifest file to use snap-plugin-collector-df plugin (exemplary file in [examples/task/] (https://github.com/intelsdi-x/snap-plugin-collector-df/blob/master/examples/task/)):
```
{
"version": 1,
"schedule": {
"type": "simple",
"interval": "5s"
},
"workflow": {
"collect": {
"metrics": {
"/intel/procfs/filesystem/*/space_free": {},
"/intel/procfs/filesystem/*/space_reserved": {},
"/intel/procfs/filesystem/*/inodes_percent_free": {},
"/intel/procfs/filesystem/*/inodes_percent_used": {},
"/intel/procfs/filesystem/*/device_name": {},
"/intel/procfs/filesystem/*/inodes_used": {}
},
"config": {
"/intel/procfs/filesystem": {
"proc_path": "/proc",
"keep_original_mountpoint": true,
"excluded_fs_names": "/proc/sys/fs/binfmt_misc,/var/lib/docker/aufs",
"excluded_fs_types": "proc,binfmt_misc,fuse.gvfsd-fuse,sysfs,cgroup,fusectl,pstore,debugfs,securityfs,devpts,mqueue,hugetlbfs,nsfs,rpc_pipefs,devtmpfs,none,tmpfs,aufs"
}
},
"process": null,
"publish": [
{
"plugin_name": "file",
"config": {
"file": "/tmp/published_df.log"
}
}
]
}
}
}
This data is published to a file `/tmp/published_df.log` per task specification
Stop task:
```
Create a task:
```
$ $SNAP_PATH/bin/snapctl task create -t df-file.json
$ snapctl task stop 480323af-15b0-4af8-a526-eb2ca6d8ae67
Task stopped:
ID: 480323af-15b0-4af8-a526-eb2ca6d8ae67
```
### 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](https://github.com/intelsdi-x/snap-plugin-collector-users/issues) and/or submit a [pull request](https://github.com/intelsdi-x/snap-plugin-collector-users/pulls).
If you have a feature request, please add it as an [issue](https://github.com/intelsdi-x/snap-plugin-collector-df/issues) and/or submit a [pull request](https://github.com/intelsdi-x/snap-plugin-collector-df/pulls).
## Community Support
This repository is one of **many** plugins in **snap**, a powerful telemetry framework. See the full project at http://github.com/intelsdi-x/snap To reach out to other users, head to the [main framework](https://github.com/intelsdi-x/snap#community-support) or visit [snap Gitter channel](https://gitter.im/intelsdi-x/snap).
This repository is one of **many** plugins in **Snap**, a powerful telemetry framework. See the full project at http://github.com/intelsdi-x/snap To reach out to other users, head to the [main framework](https://github.com/intelsdi-x/snap#community-support) or visit [Slack](http://slack.snap-telemetry.io).
## Contributing
We love contributions!
......@@ -149,7 +124,7 @@ There's more than one way to give back, from examples to blogs to code updates.
And **thank you!** Your contribution, through code and participation, is incredibly important to us.
## License
[snap](http://github.com/intelsdi-x/snap), along with this plugin, is an Open Source software released under the Apache 2.0 [License](LICENSE).
[Snap](http://github.com/intelsdi-x/snap), along with this plugin, is an Open Source software released under the Apache 2.0 [License](LICENSE).
## Acknowledgements
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment