From 80b60542fa7f719e1111127bf8a32e854bbd5a93 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Tue, 7 Nov 2017 13:54:36 -0800 Subject: [PATCH] Update contributing documentation --- CONTRIBUTING.md | 49 +++++++++++++++---------------- Makefile | 2 +- plugins/inputs/webhooks/README.md | 2 +- scripts/circle-test.sh | 2 +- 4 files changed, 27 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e94daff4..21ae5738e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ but any information you can provide on how the data will look is appreciated. See the [OpenTSDB output](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/opentsdb) for a good example. 1. **Optional:** Help users of your plugin by including example queries for populating dashboards. Include these sample queries in the `README.md` for the plugin. -1. **Optional:** Write a [tickscript](https://docs.influxdata.com/kapacitor/v1.0/tick/syntax/) for your plugin and add it to [Kapacitor](https://github.com/influxdata/kapacitor/tree/master/examples/telegraf). Or mention @jackzampolin in a PR comment with some common queries that you would want to alert on and he will write one for you. +1. **Optional:** Write a [tickscript](https://docs.influxdata.com/kapacitor/v1.0/tick/syntax/) for your plugin and add it to [Kapacitor](https://github.com/influxdata/kapacitor/tree/master/examples/telegraf). ## GoDoc @@ -52,7 +52,7 @@ See below for a quick example. * Input Plugins must be added to the `github.com/influxdata/telegraf/plugins/inputs/all/all.go` file. * The `SampleConfig` function should return valid toml that describes how the -plugin can be configured. This is include in `telegraf -sample-config`. +plugin can be configured. This is include in `telegraf config`. * The `Description` function should say in one line what this plugin does. Let's say you've written a plugin that emits metrics about processes on the @@ -183,7 +183,7 @@ See below for a quick example. * To be available within Telegraf itself, plugins must add themselves to the `github.com/influxdata/telegraf/plugins/outputs/all/all.go` file. * The `SampleConfig` function should return valid toml that describes how the -output can be configured. This is include in `telegraf -sample-config`. +output can be configured. This is include in `telegraf config`. * The `Description` function should say in one line what this output does. ### Output Example @@ -287,7 +287,7 @@ See below for a quick example. * To be available within Telegraf itself, plugins must add themselves to the `github.com/influxdata/telegraf/plugins/processors/all/all.go` file. * The `SampleConfig` function should return valid toml that describes how the -processor can be configured. This is include in `telegraf -sample-config`. +processor can be configured. This is include in the output of `telegraf config`. * The `Description` function should say in one line what this processor does. ### Processor Example @@ -344,7 +344,7 @@ See below for a quick example. * To be available within Telegraf itself, plugins must add themselves to the `github.com/influxdata/telegraf/plugins/aggregators/all/all.go` file. * The `SampleConfig` function should return valid toml that describes how the -aggregator can be configured. This is include in `telegraf -sample-config`. +aggregator can be configured. This is include in `telegraf config`. * The `Description` function should say in one line what this aggregator does. * The Aggregator plugin will need to keep caches of metrics that have passed through it. This should be done using the builtin `HashID()` function of each @@ -457,29 +457,28 @@ func init() { ## Unit Tests +Before opening a pull request you should run the linter checks and +the short tests. + +### Execute linter + +execute `make lint` + ### Execute short tests -execute `make test-short` +execute `make test` -### Execute long tests +### Execute integration tests -As Telegraf collects metrics from several third-party services it becomes a -difficult task to mock each service as some of them have complicated protocols -which would take some time to replicate. +Running the integration tests requires several docker containers to be +running. You can start the containers with: +``` +make docker-run +``` -To overcome this situation we've decided to use docker containers to provide a -fast and reproducible environment to test those services which require it. -For other situations -(i.e: https://github.com/influxdata/telegraf/blob/master/plugins/inputs/redis/redis_test.go) -a simple mock will suffice. +And run the full test suite with: +``` +make test-all +``` -To execute Telegraf tests follow these simple steps: - -- Install docker following [these](https://docs.docker.com/installation/) -instructions -- execute `make test` - -### Unit test troubleshooting - -Try cleaning up your test environment by executing `make docker-kill` and -re-running +Use `make docker-kill` to stop the containers. diff --git a/Makefile b/Makefile index 3908be1d1..d316cbb8b 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,6 @@ ifdef VERSION LDFLAGS += -X main.version=$(VERSION) endif - all: $(MAKE) deps $(MAKE) telegraf @@ -50,6 +49,7 @@ test-all: lint package: ./scripts/build.py --package --platform=all --arch=all + clean: -rm -f telegraf -rm -f telegraf.exe diff --git a/plugins/inputs/webhooks/README.md b/plugins/inputs/webhooks/README.md index 8b789e338..e6af86621 100644 --- a/plugins/inputs/webhooks/README.md +++ b/plugins/inputs/webhooks/README.md @@ -3,7 +3,7 @@ This is a Telegraf service plugin that start an http server and register multiple webhook listeners. ```sh -$ telegraf -sample-config -input-filter webhooks -output-filter influxdb > config.conf.new +$ telegraf config -input-filter webhooks -output-filter influxdb > config.conf.new ``` Change the config file to point to the InfluxDB server you are using and adjust the settings to match your environment. Once that is complete: diff --git a/scripts/circle-test.sh b/scripts/circle-test.sh index eb2df00e3..735e66cc7 100755 --- a/scripts/circle-test.sh +++ b/scripts/circle-test.sh @@ -63,7 +63,7 @@ exit_if_fail go test -race ./... # Simple Integration Tests # check that one test cpu & mem output work tmpdir=$(mktemp -d) -./telegraf -sample-config > $tmpdir/config.toml +./telegraf config > $tmpdir/config.toml exit_if_fail ./telegraf -config $tmpdir/config.toml \ -test -input-filter cpu:mem