From ccb6b3c64b42568cfe2cc926c6602661e0e7e0f4 Mon Sep 17 00:00:00 2001 From: Cameron Sparr Date: Sat, 13 Feb 2016 11:50:43 -0700 Subject: [PATCH] Small readme formattings --- CONTRIBUTING.md | 119 ++++++------------ DATA_FORMATS_OUTPUT.md | 17 ++- .../prometheus_client_test.go | 2 + 3 files changed, 50 insertions(+), 88 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 16749fcbc..7eb08a2d5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,13 @@ 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. +## GoDoc + +Public interfaces for inputs, outputs, metrics, and the accumulator can be found +on the GoDoc + +[![GoDoc](https://godoc.org/github.com/influxdata/telegraf?status.svg)](https://godoc.org/github.com/influxdata/telegraf) + ## Sign the CLA Before we can merge a pull request, you will need to sign the CLA, @@ -29,7 +36,7 @@ Assuming you can already build the project, run these in the telegraf directory: This section is for developers who want to create new collection inputs. Telegraf is entirely plugin driven. This interface allows for operators to -pick and chose what is gathered as well as makes it easy for developers +pick and chose what is gathered and makes it easy for developers to create new ways of generating metrics. Plugin authorship is kept as simple as possible to promote people to develop @@ -46,49 +53,8 @@ See below for a quick example. plugin can be configured. This is include in `telegraf -sample-config`. * The `Description` function should say in one line what this plugin does. -### Input interface - -```go -type Input interface { - SampleConfig() string - Description() string - Gather(Accumulator) error -} - -type Accumulator interface { - Add(measurement string, - value interface{}, - tags map[string]string, - timestamp ...time.Time) - AddFields(measurement string, - fields map[string]interface{}, - tags map[string]string, - timestamp ...time.Time) -} -``` - -### Accumulator - -The way that a plugin emits metrics is by interacting with the Accumulator. - -The `Add` function takes 3 arguments: -* **measurement**: A string description of the metric. For instance `bytes_read` or ` -faults`. -* **value**: A value for the metric. This accepts 5 different types of value: - * **int**: The most common type. All int types are accepted but favor using `int64` - Useful for counters, etc. - * **float**: Favor `float64`, useful for gauges, percentages, etc. - * **bool**: `true` or `false`, useful to indicate the presence of a state. `light_on`, - etc. - * **string**: Typically used to indicate a message, or some kind of freeform - information. - * **time.Time**: Useful for indicating when a state last occurred, for instance ` - light_on_since`. -* **tags**: This is a map of strings to strings to describe the where or who -about the metric. For instance, the `net` plugin adds a tag named `"interface"` -set to the name of the network interface, like `"eth0"`. - -Let's say you've written a plugin that emits metrics about processes on the current host. +Let's say you've written a plugin that emits metrics about processes on the +current host. ### Input Plugin Example @@ -194,18 +160,6 @@ and `Stop()` methods. * Same as the `Plugin` guidelines, except that they must conform to the `inputs.ServiceInput` interface. -### Service Plugin interface - -```go -type ServicePlugin interface { - SampleConfig() string - Description() string - Gather(Accumulator) error - Start() error - Stop() -} -``` - ## Output Plugins This section is for developers who want to create a new output sink. Outputs @@ -223,18 +177,6 @@ See below for a quick example. output can be configured. This is include in `telegraf -sample-config`. * The `Description` function should say in one line what this output does. -### Output interface - -```go -type Output interface { - Connect() error - Close() error - Description() string - SampleConfig() string - Write(metrics []telegraf.Metric) error -} -``` - ### Output Example ```go @@ -282,6 +224,33 @@ func init() { ``` +## Output Plugins Writing Arbitrary Data Formats + +Some output plugins (such as +[file](https://github.com/influxdata/telegraf/tree/master/plugins/outputs/file)) +can write arbitrary output data formats. An overview of these data formats can +be found +[here](https://github.com/influxdata/telegraf/blob/master/DATA_FORMATS_OUTPUT.md). + +In order to enable this, you must specify a +`SetSerializer(serializer serializers.Serializer)` +function on the plugin object (see the file plugin for an example), as well as +defining `serializer` as a field of the object. + +You can then utilize the serializer internally in your plugin, serializing data +before it's written. Telegraf's configuration layer will take care of +instantiating and creating the `Serializer` object. + +You should also add the following to your SampleConfig() return: + +```toml + ### Data format to output. This can be "influx" or "graphite" + ### Each data format has it's own unique set of configuration options, read + ### more about them here: + ### https://github.com/influxdata/telegraf/blob/master/DATA_FORMATS_OUTPUT.md + data_format = "influx" +``` + ## Service Output Plugins This section is for developers who want to create new "service" output. A @@ -297,20 +266,6 @@ and `Stop()` methods. * Same as the `Output` guidelines, except that they must conform to the `output.ServiceOutput` interface. -### Service Output interface - -```go -type ServiceOutput interface { - Connect() error - Close() error - Description() string - SampleConfig() string - Write(metrics []telegraf.Metric) error - Start() error - Stop() -} -``` - ## Unit Tests ### Execute short tests diff --git a/DATA_FORMATS_OUTPUT.md b/DATA_FORMATS_OUTPUT.md index 7dca85a4c..0ad019b10 100644 --- a/DATA_FORMATS_OUTPUT.md +++ b/DATA_FORMATS_OUTPUT.md @@ -10,19 +10,24 @@ are a combination of four basic parts: 1. Timestamp In InfluxDB line protocol, these 4 parts are easily defined in textual form: -`measurement_name[,tag1=val1,...] field1=val1[,field2=val2,...] [timestamp]` + +``` +measurement_name[,tag1=val1,...] field1=val1[,field2=val2,...] [timestamp] +``` For Telegraf outputs that write textual data (such as `kafka`, `mqtt`, and `file`), InfluxDB line protocol was originally the only available output format. But now -we are normalizing telegraf metric "serializers" into a plugin-like format across -all output plugins that can support it. You will be able to identify a plugin -that supports different data formats by the presence of a `data_format` -config option, for example, in the file plugin: +we are normalizing telegraf metric "serializers" into a +[plugin-like interface](https://github.com/influxdata/telegraf/tree/master/plugins/serializers) +across all output plugins that can support it. +You will be able to identify a plugin that supports different data formats +by the presence of a `data_format` +config option, for example, in the `file` output plugin: ```toml [[outputs.file]] ### Files to write to, "stdout" is a specially handled file. - files = ["stdout", "/tmp/metrics.out"] + files = ["stdout"] ### Data format to output. This can be "influx" or "graphite" ### Each data format has it's own unique set of configuration options, read diff --git a/plugins/outputs/prometheus_client/prometheus_client_test.go b/plugins/outputs/prometheus_client/prometheus_client_test.go index adcdf9c5f..16414a8e4 100644 --- a/plugins/outputs/prometheus_client/prometheus_client_test.go +++ b/plugins/outputs/prometheus_client/prometheus_client_test.go @@ -2,6 +2,7 @@ package prometheus_client import ( "testing" + "time" "github.com/stretchr/testify/require" @@ -18,6 +19,7 @@ func TestPrometheusWritePointEmptyTag(t *testing.T) { } pTesting = &PrometheusClient{Listen: "localhost:9127"} err := pTesting.Start() + time.Sleep(time.Millisecond * 200) require.NoError(t, err) defer pTesting.Stop()