chore: clean up all markdown lint errors in second half of docs directory (#10156)
This commit is contained in:
Joshua Powers
GitHub
parent
d5d1f310da
commit
97826bdc73
|
|
@ -1,8 +1,8 @@
|
|||
### Processor Plugins
|
||||
# Processor Plugins
|
||||
|
||||
This section is for developers who want to create a new processor plugin.
|
||||
|
||||
### Processor Plugin Guidelines
|
||||
## Processor Plugin Guidelines
|
||||
|
||||
* A processor must conform to the [telegraf.Processor][] interface.
|
||||
* Processors should call `processors.Add` in their `init` function to register
|
||||
|
|
@ -12,13 +12,13 @@ This section is for developers who want to create a new processor plugin.
|
|||
* The `SampleConfig` function should return valid toml that describes how the
|
||||
processor can be configured. This is include in the output of `telegraf
|
||||
config`.
|
||||
- The `SampleConfig` function should return valid toml that describes how the
|
||||
* The `SampleConfig` function should return valid toml that describes how the
|
||||
plugin can be configured. This is included in `telegraf config`. Please
|
||||
consult the [Sample Config][] page for the latest style guidelines.
|
||||
* The `Description` function should say in one line what this processor does.
|
||||
- Follow the recommended [Code Style][].
|
||||
* Follow the recommended [Code Style][].
|
||||
|
||||
### Processor Plugin Example
|
||||
## Processor Plugin Example
|
||||
|
||||
```go
|
||||
package printer
|
||||
|
|
@ -26,47 +26,47 @@ package printer
|
|||
// printer.go
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"fmt"
|
||||
|
||||
"github.com/influxdata/telegraf"
|
||||
"github.com/influxdata/telegraf/plugins/processors"
|
||||
"github.com/influxdata/telegraf"
|
||||
"github.com/influxdata/telegraf/plugins/processors"
|
||||
)
|
||||
|
||||
type Printer struct {
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
}
|
||||
|
||||
var sampleConfig = `
|
||||
`
|
||||
|
||||
func (p *Printer) SampleConfig() string {
|
||||
return sampleConfig
|
||||
return sampleConfig
|
||||
}
|
||||
|
||||
func (p *Printer) Description() string {
|
||||
return "Print all metrics that pass through this filter."
|
||||
return "Print all metrics that pass through this filter."
|
||||
}
|
||||
|
||||
// Init is for setup, and validating config.
|
||||
func (p *Printer) Init() error {
|
||||
return nil
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Printer) Apply(in ...telegraf.Metric) []telegraf.Metric {
|
||||
for _, metric := range in {
|
||||
fmt.Println(metric.String())
|
||||
}
|
||||
return in
|
||||
for _, metric := range in {
|
||||
fmt.Println(metric.String())
|
||||
}
|
||||
return in
|
||||
}
|
||||
|
||||
func init() {
|
||||
processors.Add("printer", func() telegraf.Processor {
|
||||
return &Printer{}
|
||||
})
|
||||
processors.Add("printer", func() telegraf.Processor {
|
||||
return &Printer{}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming Processors
|
||||
## Streaming Processors
|
||||
|
||||
Streaming processors are a new processor type available to you. They are
|
||||
particularly useful to implement processor types that use background processes
|
||||
|
|
@ -84,7 +84,7 @@ Some differences from classic Processors:
|
|||
* Processors should call `processors.AddStreaming` in their `init` function to register
|
||||
themselves. See below for a quick example.
|
||||
|
||||
### Streaming Processor Example
|
||||
## Streaming Processor Example
|
||||
|
||||
```go
|
||||
package printer
|
||||
|
|
@ -92,30 +92,30 @@ package printer
|
|||
// printer.go
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"fmt"
|
||||
|
||||
"github.com/influxdata/telegraf"
|
||||
"github.com/influxdata/telegraf/plugins/processors"
|
||||
"github.com/influxdata/telegraf"
|
||||
"github.com/influxdata/telegraf/plugins/processors"
|
||||
)
|
||||
|
||||
type Printer struct {
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
}
|
||||
|
||||
var sampleConfig = `
|
||||
`
|
||||
|
||||
func (p *Printer) SampleConfig() string {
|
||||
return sampleConfig
|
||||
return sampleConfig
|
||||
}
|
||||
|
||||
func (p *Printer) Description() string {
|
||||
return "Print all metrics that pass through this filter."
|
||||
return "Print all metrics that pass through this filter."
|
||||
}
|
||||
|
||||
// Init is for setup, and validating config.
|
||||
func (p *Printer) Init() error {
|
||||
return nil
|
||||
return nil
|
||||
}
|
||||
|
||||
// Start is called once when the plugin starts; it is only called once per
|
||||
|
|
@ -135,13 +135,13 @@ func (p *Printer) Start(acc telegraf.Accumulator) error {
|
|||
// Metrics you don't want to pass downstream should have metric.Drop() called,
|
||||
// rather than simply omitting the acc.AddMetric() call
|
||||
func (p *Printer) Add(metric telegraf.Metric, acc telegraf.Accumulator) error {
|
||||
// print!
|
||||
fmt.Println(metric.String())
|
||||
// pass the metric downstream, or metric.Drop() it.
|
||||
// Metric will be dropped if this function returns an error.
|
||||
acc.AddMetric(metric)
|
||||
// print!
|
||||
fmt.Println(metric.String())
|
||||
// pass the metric downstream, or metric.Drop() it.
|
||||
// Metric will be dropped if this function returns an error.
|
||||
acc.AddMetric(metric)
|
||||
|
||||
return nil
|
||||
return nil
|
||||
}
|
||||
|
||||
// Stop gives you an opportunity to gracefully shut down the processor.
|
||||
|
|
@ -154,9 +154,9 @@ func (p *Printer) Stop() error {
|
|||
}
|
||||
|
||||
func init() {
|
||||
processors.AddStreaming("printer", func() telegraf.StreamingProcessor {
|
||||
return &Printer{}
|
||||
})
|
||||
processors.AddStreaming("printer", func() telegraf.StreamingProcessor {
|
||||
return &Printer{}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ By default, the profiling is turned off.
|
|||
|
||||
To enable profiling you need to specify address to config parameter `pprof-addr`, for example:
|
||||
|
||||
```
|
||||
```shell
|
||||
telegraf --config telegraf.conf --pprof-addr localhost:6060
|
||||
```
|
||||
|
||||
|
|
@ -21,4 +21,3 @@ or to look at a 30-second CPU profile:
|
|||
`go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30`
|
||||
|
||||
To view all available profiles, open `http://localhost:6060/debug/pprof/` in your browser.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,4 +21,4 @@
|
|||
[profiling]: /docs/PROFILING.md
|
||||
[winsvc]: /docs/WINDOWS_SERVICE.md
|
||||
[faq]: /docs/FAQ.md
|
||||
[nightlies]: /docs/NIGHTLIES.md
|
||||
[nightlies]: /docs/NIGHTLIES.md
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ might change between versions. Please check the driver documentation for availab
|
|||
|
||||
database | driver | aliases | example DSN | comment
|
||||
---------------------| ------------------------------------------------------| --------------- | -------------------------------------------------------------------------------------- | -------
|
||||
CockroachDB | [cockroach](https://github.com/jackc/pgx) | postgres<br>pgx | see _postgres_ driver | uses PostgresQL driver
|
||||
CockroachDB | [cockroach](https://github.com/jackc/pgx) | postgres or pgx | see _postgres_ driver | uses PostgresQL driver
|
||||
MariaDB | [maria](https://github.com/go-sql-driver/mysql) | mysql | see _mysql_ driver | uses MySQL driver
|
||||
Microsoft SQL Server | [sqlserver](https://github.com/denisenkom/go-mssqldb) | mssql | `username:password@host/instance?param1=value¶m2=value` | uses newer _sqlserver_ driver
|
||||
MySQL | [mysql](https://github.com/go-sql-driver/mysql) | | `[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...¶mN=valueN]` | see [driver docs](https://github.com/go-sql-driver/mysql) for more information
|
||||
|
|
@ -16,28 +16,35 @@ TiDB | [tidb](https://github.com/go-sql-driver/mysql) | m
|
|||
## Comments
|
||||
|
||||
### Driver aliases
|
||||
|
||||
Some database drivers are supported though another driver (e.g. CockroachDB). For other databases we provide a more
|
||||
obvious name (e.g. postgres) compared to the driver name. For all of those drivers you might use an _alias_ name
|
||||
during configuration.
|
||||
|
||||
### Example data-source-name DSN
|
||||
|
||||
The given examples are just that, so please check the driver documentation for the exact format
|
||||
and available options and parameters. Please note that the format of a DSN might also change
|
||||
between driver version.
|
||||
|
||||
### Type conversions
|
||||
|
||||
Telegraf relies on type conversion of the database driver and/or the golang sql framework. In case you find
|
||||
any problem, please open an issue!
|
||||
|
||||
## Help
|
||||
|
||||
If nothing seems to work, you might find help in the telegraf forum or in the chat.
|
||||
|
||||
### The documentation is wrong
|
||||
|
||||
Please open an issue or even better send a pull-request!
|
||||
|
||||
### I found a bug
|
||||
|
||||
Please open an issue or even better send a pull-request!
|
||||
|
||||
### My database is not supported
|
||||
|
||||
We currently cannot support CGO drivers in telegraf! Please check if a **pure Go** driver for the [golang sql framework](https://golang.org/pkg/database/sql/) exists.
|
||||
If you found such a driver, please let us know by opening an issue or even better by sending a pull-request!
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ Template patterns are a mini language that describes how a dot delimited
|
|||
string should be mapped to and from [metrics][].
|
||||
|
||||
A template has the form:
|
||||
```
|
||||
|
||||
```text
|
||||
"host.mytag.mytag.measurement.measurement.field*"
|
||||
```
|
||||
|
||||
|
|
@ -25,9 +26,9 @@ can also be specified multiple times.
|
|||
**NOTE:** `measurement` must be specified in your template.
|
||||
**NOTE:** `field*` cannot be used in conjunction with `measurement*`.
|
||||
|
||||
### Examples
|
||||
## Examples
|
||||
|
||||
#### Measurement & Tag Templates
|
||||
### Measurement & Tag Templates
|
||||
|
||||
The most basic template is to specify a single transformation to apply to all
|
||||
incoming metrics. So the following template:
|
||||
|
|
@ -40,7 +41,7 @@ templates = [
|
|||
|
||||
would result in the following Graphite -> Telegraf transformation.
|
||||
|
||||
```
|
||||
```text
|
||||
us.west.cpu.load 100
|
||||
=> cpu.load,region=us.west value=100
|
||||
```
|
||||
|
|
@ -55,7 +56,7 @@ templates = [
|
|||
]
|
||||
```
|
||||
|
||||
#### Field Templates
|
||||
### Field Templates
|
||||
|
||||
The field keyword tells Telegraf to give the metric that field name.
|
||||
So the following template:
|
||||
|
|
@ -69,7 +70,7 @@ templates = [
|
|||
|
||||
would result in the following Graphite -> Telegraf transformation.
|
||||
|
||||
```
|
||||
```text
|
||||
cpu.usage.idle.percent.eu-east 100
|
||||
=> cpu_usage,region=eu-east idle_percent=100
|
||||
```
|
||||
|
|
@ -86,12 +87,12 @@ templates = [
|
|||
|
||||
which would result in the following Graphite -> Telegraf transformation.
|
||||
|
||||
```
|
||||
```text
|
||||
cpu.usage.eu-east.idle.percentage 100
|
||||
=> cpu_usage,region=eu-east idle_percentage=100
|
||||
```
|
||||
|
||||
#### Filter Templates
|
||||
### Filter Templates
|
||||
|
||||
Users can also filter the template(s) to use based on the name of the bucket,
|
||||
using glob matching, like so:
|
||||
|
|
@ -105,7 +106,7 @@ templates = [
|
|||
|
||||
which would result in the following transformation:
|
||||
|
||||
```
|
||||
```text
|
||||
cpu.load.eu-east 100
|
||||
=> cpu_load,region=eu-east value=100
|
||||
|
||||
|
|
@ -113,7 +114,7 @@ mem.cached.localhost 256
|
|||
=> mem_cached,host=localhost value=256
|
||||
```
|
||||
|
||||
#### Adding Tags
|
||||
### Adding Tags
|
||||
|
||||
Additional tags can be added to a metric that don't exist on the received metric.
|
||||
You can add additional tags by specifying them after the pattern.
|
||||
|
|
@ -128,7 +129,7 @@ templates = [
|
|||
|
||||
would result in the following Graphite -> Telegraf transformation.
|
||||
|
||||
```
|
||||
```text
|
||||
cpu.usage.idle.eu-east 100
|
||||
=> cpu_usage,region=eu-east,datacenter=1a idle=100
|
||||
```
|
||||
|
|
|
|||
39
docs/TLS.md
39
docs/TLS.md
|
|
@ -5,9 +5,10 @@ possible, plugins will provide the standard settings described below. With the
|
|||
exception of the advanced configuration available TLS settings will be
|
||||
documented in the sample configuration.
|
||||
|
||||
### Client Configuration
|
||||
## Client Configuration
|
||||
|
||||
For client TLS support we have the following options:
|
||||
|
||||
```toml
|
||||
## Root certificates for verifying server certificates encoded in PEM format.
|
||||
# tls_ca = "/etc/telegraf/ca.pem"
|
||||
|
|
@ -52,23 +53,23 @@ for the interest of brevity.
|
|||
## Define list of allowed ciphers suites. If not defined the default ciphers
|
||||
## supported by Go will be used.
|
||||
## ex: tls_cipher_suites = [
|
||||
## "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
|
||||
## "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
|
||||
## "TLS_RSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_RSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_RSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_RSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_RSA_WITH_AES_256_CBC_SHA"
|
||||
## "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305",
|
||||
## "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
|
||||
## "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA",
|
||||
## "TLS_RSA_WITH_AES_128_GCM_SHA256",
|
||||
## "TLS_RSA_WITH_AES_256_GCM_SHA384",
|
||||
## "TLS_RSA_WITH_AES_128_CBC_SHA256",
|
||||
## "TLS_RSA_WITH_AES_128_CBC_SHA",
|
||||
## "TLS_RSA_WITH_AES_256_CBC_SHA"
|
||||
## ]
|
||||
# tls_cipher_suites = []
|
||||
|
||||
|
|
@ -80,6 +81,7 @@ for the interest of brevity.
|
|||
```
|
||||
|
||||
Cipher suites for use with `tls_cipher_suites`:
|
||||
|
||||
- `TLS_RSA_WITH_RC4_128_SHA`
|
||||
- `TLS_RSA_WITH_3DES_EDE_CBC_SHA`
|
||||
- `TLS_RSA_WITH_AES_128_CBC_SHA`
|
||||
|
|
@ -107,6 +109,7 @@ Cipher suites for use with `tls_cipher_suites`:
|
|||
- `TLS_CHACHA20_POLY1305_SHA256`
|
||||
|
||||
TLS versions for use with `tls_min_version` or `tls_max_version`:
|
||||
|
||||
- `TLS10`
|
||||
- `TLS11`
|
||||
- `TLS12`
|
||||
|
|
|
|||
|
|
@ -9,29 +9,31 @@ the general steps to set it up.
|
|||
3. Place the telegraf.exe and the telegraf.conf config file into `C:\Program Files\Telegraf`
|
||||
4. To install the service into the Windows Service Manager, run the following in PowerShell as an administrator (If necessary, you can wrap any spaces in the file paths in double quotes ""):
|
||||
|
||||
```
|
||||
```shell
|
||||
> C:\"Program Files"\Telegraf\telegraf.exe --service install
|
||||
```
|
||||
|
||||
5. Edit the configuration file to meet your needs
|
||||
6. To check that it works, run:
|
||||
|
||||
```
|
||||
```shell
|
||||
> C:\"Program Files"\Telegraf\telegraf.exe --config C:\"Program Files"\Telegraf\telegraf.conf --test
|
||||
```
|
||||
|
||||
7. To start collecting data, run:
|
||||
|
||||
```
|
||||
```shell
|
||||
> net start telegraf
|
||||
```
|
||||
|
||||
## Config Directory
|
||||
|
||||
You can also specify a `--config-directory` for the service to use:
|
||||
|
||||
1. Create a directory for config snippets: `C:\Program Files\Telegraf\telegraf.d`
|
||||
2. Include the `--config-directory` option when registering the service:
|
||||
```
|
||||
|
||||
```shell
|
||||
> C:\"Program Files"\Telegraf\telegraf.exe --service install --config C:\"Program Files"\Telegraf\telegraf.conf --config-directory C:\"Program Files"\Telegraf\telegraf.d
|
||||
```
|
||||
|
||||
|
|
@ -54,7 +56,7 @@ filtering options. However, if you do need to run multiple telegraf instances
|
|||
on a single system, you can install the service with the `--service-name` and
|
||||
`--service-display-name` flags to give the services unique names:
|
||||
|
||||
```
|
||||
```shell
|
||||
> C:\"Program Files"\Telegraf\telegraf.exe --service install --service-name telegraf-1 --service-display-name "Telegraf 1"
|
||||
> C:\"Program Files"\Telegraf\telegraf.exe --service install --service-name telegraf-2 --service-display-name "Telegraf 2"
|
||||
```
|
||||
|
|
@ -64,7 +66,7 @@ on a single system, you can install the service with the `--service-name` and
|
|||
When Telegraf runs as a Windows service, Telegraf logs messages to Windows events log before configuration file with logging settings is loaded.
|
||||
Check event log for an error reported by `telegraf` service in case of Telegraf service reports failure on its start: Event Viewer->Windows Logs->Application
|
||||
|
||||
**Troubleshooting common error #1067**
|
||||
### common error #1067
|
||||
|
||||
When installing as service in Windows, always double check to specify full path of the config file, otherwise windows service will fail to start
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
# Code Style
|
||||
|
||||
Code is required to be formatted using `gofmt`, this covers most code style
|
||||
requirements. It is also highly recommended to use `goimports` to
|
||||
automatically order imports.
|
||||
|
||||
Please try to keep lines length under 80 characters, the exact number of
|
||||
Please try to keep lines length under 80 characters, the exact number of
|
||||
characters is not strict but it generally helps with readability.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
# Deprecation
|
||||
|
||||
Deprecation is the primary tool for making changes in Telegraf. A deprecation
|
||||
indicates that the community should move away from using a feature, and
|
||||
documents that the feature will be removed in the next major update (2.0).
|
||||
|
|
@ -36,14 +37,17 @@ Add the deprecation warning to the plugin's README:
|
|||
Log a warning message if the plugin is used. If the plugin is a
|
||||
ServiceInput, place this in the `Start()` function, for regular Input's log it only the first
|
||||
time the `Gather` function is called.
|
||||
|
||||
```go
|
||||
log.Println("W! [inputs.logparser] The logparser plugin is deprecated in 1.10. " +
|
||||
"Please use the tail plugin with the grok data_format as a replacement.")
|
||||
"Please use the tail plugin with the grok data_format as a replacement.")
|
||||
```
|
||||
|
||||
## Deprecate options
|
||||
|
||||
Mark the option as deprecated in the sample config, include the deprecation
|
||||
version and any replacement.
|
||||
|
||||
```toml
|
||||
## Broker URL
|
||||
## deprecated in 1.7; use the brokers option
|
||||
|
|
@ -54,17 +58,19 @@ In the plugins configuration struct, mention that the option is deprecated:
|
|||
|
||||
```go
|
||||
type AMQPConsumer struct {
|
||||
URL string `toml:"url"` // deprecated in 1.7; use brokers
|
||||
URL string `toml:"url"` // deprecated in 1.7; use brokers
|
||||
}
|
||||
```
|
||||
|
||||
Finally, use the plugin's `Init() error` method to display a log message at warn level. The message should include the offending configuration option and any suggested replacement:
|
||||
|
||||
```go
|
||||
func (a *AMQPConsumer) Init() error {
|
||||
if p.URL != "" {
|
||||
p.Log.Warnf("Use of deprecated configuration: 'url'; please use the 'brokers' option")
|
||||
}
|
||||
return nil
|
||||
if p.URL != "" {
|
||||
p.Log.Warnf("Use of deprecated configuration: 'url'; please use the 'brokers' option")
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -8,12 +8,13 @@ need to be specified for each log call.
|
|||
|
||||
```go
|
||||
type MyPlugin struct {
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
Log telegraf.Logger `toml:"-"`
|
||||
}
|
||||
```
|
||||
|
||||
You can then use this Logger in the plugin. Use the method corresponding to
|
||||
the log level of the message.
|
||||
|
||||
```go
|
||||
p.Log.Errorf("Unable to write to file: %v", err)
|
||||
```
|
||||
|
|
@ -22,6 +23,7 @@ p.Log.Errorf("Unable to write to file: %v", err)
|
|||
|
||||
In other sections of the code it is required to add the log level and module
|
||||
manually:
|
||||
|
||||
```go
|
||||
log.Printf("E! [agent] Error writing to %s: %v", output.LogName(), err)
|
||||
```
|
||||
|
|
@ -37,6 +39,7 @@ support setting the log level on a per module basis, it is especially important
|
|||
to not over do it with debug logging.
|
||||
|
||||
If the plugin is listening on a socket, log a message with the address of the socket:
|
||||
|
||||
```go
|
||||
p.log.InfoF("Listening on %s://%s", protocol, l.Addr())
|
||||
```
|
||||
|
|
@ -59,6 +62,7 @@ normal on some systems.
|
|||
|
||||
The log level is indicated by a single character at the start of the log
|
||||
message. Adding this prefix is not required when using the Plugin Logger.
|
||||
|
||||
- `D!` Debug
|
||||
- `I!` Info
|
||||
- `W!` Warning
|
||||
|
|
|
|||
|
|
@ -3,14 +3,17 @@
|
|||
When making changes to an existing input plugin, care must be taken not to change the metric format in ways that will cause trouble for existing users. This document helps developers understand how to make metric format changes safely.
|
||||
|
||||
## Changes can cause incompatibilities
|
||||
|
||||
If the metric format changes, data collected in the new format can be incompatible with data in the old format. Database queries designed around the old format may not work with the new format. This can cause application failures.
|
||||
|
||||
Some metric format changes don't cause incompatibilities. Also, some unsafe changes are necessary. How do you know what changes are safe and what to do if your change isn't safe?
|
||||
|
||||
## Guidelines
|
||||
|
||||
The main guideline is just to keep compatibility in mind when making changes. Often developers are focused on making a change that fixes their particular problem and they forget that many people use the existing code and will upgrade. When you're coding, keep existing users and applications in mind.
|
||||
|
||||
### Renaming, removing, reusing
|
||||
|
||||
Database queries refer to the metric and its tags and fields by name. Any Telegraf code change that changes those names has the potential to break an existing query. Similarly, removing tags or fields can break queries.
|
||||
|
||||
Changing the meaning of an existing tag value or field value or reusing an existing one in a new way isn't safe. Although queries that use these tags/field may not break, they will not work as they did before the change.
|
||||
|
|
@ -18,9 +21,11 @@ Changing the meaning of an existing tag value or field value or reusing an exist
|
|||
Adding a field doesn't break existing queries. Queries that select all fields and/or tags (like "select * from") will return an extra series but this is often useful.
|
||||
|
||||
### Performance and storage
|
||||
|
||||
Time series databases can store large amounts of data but many of them don't perform well on high cardinality data. If a metric format change includes a new tag that holds high cardinality data, database performance could be reduced enough to cause existing applications not to work as they previously did. Metric format changes that dramatically increase the number of tags or fields of a metric can increase database storage requirements unexpectedly. Both of these types of changes are unsafe.
|
||||
|
||||
### Make unsafe changes opt-in
|
||||
|
||||
If your change has the potential to seriously affect existing users, the change must be opt-in. To do this, add a plugin configuration setting that lets the user select the metric format. Make the setting's default value select the old metric format. When new users add the plugin they can choose the new format and get its benefits. When existing users upgrade, their config files won't have the new setting so the default will ensure that there is no change.
|
||||
|
||||
When adding a setting, avoid using a boolean and consider instead a string or int for future flexibility. A boolean can only handle two formats but a string can handle many. For example, compare use_new_format=true and features=["enable_foo_fields"]; the latter is much easier to extend and still very descriptive.
|
||||
|
|
@ -28,6 +33,7 @@ When adding a setting, avoid using a boolean and consider instead a string or in
|
|||
If you want to encourage existing users to use the new format you can log a warning once on startup when the old format is selected. The warning should tell users in a gentle way that they can upgrade to a better metric format. If it doesn't make sense to maintain multiple metric formats forever, you can change the default on a major release or even remove the old format completely. See [[Deprecation]] for details.
|
||||
|
||||
### Utility
|
||||
|
||||
Changes should be useful to many or most users. A change that is only useful for a small number of users may not accepted, even if it's off by default.
|
||||
|
||||
## Summary table
|
||||
|
|
@ -39,4 +45,5 @@ Changes should be useful to many or most users. A change that is only useful fo
|
|||
| field | unsafe | unsafe | ok as long as it's useful for existing users and is worth the added space |
|
||||
|
||||
## References
|
||||
|
||||
InfluxDB Documentation: "Schema and data layout"
|
||||
|
|
|
|||
|
|
@ -21,12 +21,14 @@ building the rpm/deb as it is less system dependent.
|
|||
|
||||
Pull the CI images from quay, the version corresponds to the version of Go
|
||||
that is used to build the binary:
|
||||
```
|
||||
|
||||
```shell
|
||||
docker pull quay.io/influxdb/telegraf-ci:1.9.7
|
||||
```
|
||||
|
||||
Start a shell in the container:
|
||||
```
|
||||
|
||||
```shell
|
||||
docker run -ti quay.io/influxdb/telegraf-ci:1.9.7 /bin/bash
|
||||
```
|
||||
|
||||
|
|
@ -42,6 +44,7 @@ From within the container:
|
|||
* Change `include_packages` to change what package you want, run `make help` to see possible values
|
||||
|
||||
From the host system, copy the build artifacts out of the container:
|
||||
```
|
||||
|
||||
```shell
|
||||
docker cp romantic_ptolemy:/go/src/github.com/influxdata/telegraf/build/telegraf-1.10.2-1.x86_64.rpm .
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,20 +1,24 @@
|
|||
# Profiling
|
||||
|
||||
This article describes how to collect performance traces and memory profiles
|
||||
from Telegraf. If you are submitting this for an issue, please include the
|
||||
version.txt generated below.
|
||||
|
||||
Use the `--pprof-addr` option to enable the profiler, the easiest way to do
|
||||
this may be to add this line to `/etc/default/telegraf`:
|
||||
```
|
||||
|
||||
```shell
|
||||
TELEGRAF_OPTS="--pprof-addr localhost:6060"
|
||||
```
|
||||
|
||||
Restart Telegraf to activate the profile address.
|
||||
|
||||
#### Trace Profile
|
||||
## Trace Profile
|
||||
|
||||
Collect a trace during the time where the performance issue is occurring. This
|
||||
example collects a 10 second trace and runs for 10 seconds:
|
||||
```
|
||||
|
||||
```shell
|
||||
curl 'http://localhost:6060/debug/pprof/trace?seconds=10' > trace.bin
|
||||
telegraf --version > version.txt
|
||||
go env GOOS GOARCH >> version.txt
|
||||
|
|
@ -22,34 +26,41 @@ go env GOOS GOARCH >> version.txt
|
|||
|
||||
The `trace.bin` and `version.txt` files can be sent in for analysis or, if desired, you can
|
||||
analyze the trace with:
|
||||
```
|
||||
|
||||
```shell
|
||||
go tool trace trace.bin
|
||||
```
|
||||
|
||||
#### Memory Profile
|
||||
## Memory Profile
|
||||
|
||||
Collect a heap memory profile:
|
||||
```
|
||||
|
||||
```shell
|
||||
curl 'http://localhost:6060/debug/pprof/heap' > mem.prof
|
||||
telegraf --version > version.txt
|
||||
go env GOOS GOARCH >> version.txt
|
||||
```
|
||||
|
||||
Analyze:
|
||||
```
|
||||
|
||||
```shell
|
||||
$ go tool pprof mem.prof
|
||||
(pprof) top5
|
||||
```
|
||||
|
||||
#### CPU Profile
|
||||
## CPU Profile
|
||||
|
||||
Collect a 30s CPU profile:
|
||||
```
|
||||
|
||||
```shell
|
||||
curl 'http://localhost:6060/debug/pprof/profile' > cpu.prof
|
||||
telegraf --version > version.txt
|
||||
go env GOOS GOARCH >> version.txt
|
||||
```
|
||||
|
||||
Analyze:
|
||||
```
|
||||
|
||||
```shell
|
||||
go tool pprof cpu.prof
|
||||
(pprof) top5
|
||||
```
|
||||
|
|
|
|||
|
|
@ -5,13 +5,15 @@ The sample config file is generated from a results of the `SampleConfig()` and
|
|||
|
||||
You can generate a full sample
|
||||
config:
|
||||
```
|
||||
|
||||
```shell
|
||||
telegraf config
|
||||
```
|
||||
|
||||
You can also generate the config for a particular plugin using the `-usage`
|
||||
option:
|
||||
```
|
||||
|
||||
```shell
|
||||
telegraf --usage influxdb
|
||||
```
|
||||
|
||||
|
|
@ -21,6 +23,7 @@ In the config file we use 2-space indention. Since the config is
|
|||
[TOML](https://github.com/toml-lang/toml) the indention has no meaning.
|
||||
|
||||
Documentation is double commented, full sentences, and ends with a period.
|
||||
|
||||
```toml
|
||||
## This text describes what an the exchange_type option does.
|
||||
# exchange_type = "topic"
|
||||
|
|
@ -29,14 +32,15 @@ Documentation is double commented, full sentences, and ends with a period.
|
|||
Try to give every parameter a default value whenever possible. If an
|
||||
parameter does not have a default or must frequently be changed then have it
|
||||
uncommented.
|
||||
|
||||
```toml
|
||||
## Brokers are the AMQP brokers to connect to.
|
||||
brokers = ["amqp://localhost:5672"]
|
||||
```
|
||||
|
||||
|
||||
Options where the default value is usually sufficient are normally commented
|
||||
out. The commented out value is the default.
|
||||
|
||||
```toml
|
||||
## What an exchange type is.
|
||||
# exchange_type = "topic"
|
||||
|
|
@ -44,6 +48,7 @@ out. The commented out value is the default.
|
|||
|
||||
If you want to show an example of a possible setting filled out that is
|
||||
different from the default, show both:
|
||||
|
||||
```toml
|
||||
## Static routing key. Used when no routing_tag is set or as a fallback
|
||||
## when the tag specified in routing tag is not found.
|
||||
|
|
@ -53,6 +58,7 @@ different from the default, show both:
|
|||
|
||||
Unless parameters are closely related, add a space between them. Usually
|
||||
parameters is closely related have a single description.
|
||||
|
||||
```toml
|
||||
## If true, queue will be declared as an exclusive queue.
|
||||
# queue_exclusive = false
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ For bugs you may want to add `panic`, `regression`, or `upstream` to provide
|
|||
further detail.
|
||||
|
||||
Summary of Labels:
|
||||
|
||||
| Label | Description | Purpose |
|
||||
| --- | ----------- | ---|
|
||||
| `area/*` | These labels each corresponding to a plugin or group of plugins that can be added to identify the affected plugin or group of plugins | categorization |
|
||||
|
|
@ -40,9 +41,9 @@ Summary of Labels:
|
|||
| `good first issue` | This is a smaller issue suited for getting started in Telegraf, Golang, and contributing to OSS | community |
|
||||
| `help wanted` | Request for community participation, code, contribution | community |
|
||||
| `need more info` | Issue triaged but outstanding questions remain | community |
|
||||
| `performance` | Issues or PRs that address performance issues | categorization|
|
||||
| `performance` | Issues or PRs that address performance issues | categorization|
|
||||
| `platform/*` | Issues that only apply to one platform | categorization |
|
||||
| `plugin/*` | 1. Request for new * plugins 2. Issues/PRs that are related to * plugins | categorization |
|
||||
| `plugin/*` | Request for new plugins and issues/PRs that are related to plugins | categorization |
|
||||
| `ready for final review` | Pull request has been reviewed and/or tested by multiple users and is ready for a final review | triage |
|
||||
| `rfc` | Request for comment - larger topics of discussion that are looking for feedback | community |
|
||||
| `support` |Telegraf questions, may be directed to community site or slack | triage |
|
||||
|
|
@ -66,7 +67,3 @@ We close issues for the following reasons:
|
|||
| `closed/not-reproducible` | Given the information we have we can't reproduce the issue |
|
||||
| `closed/out-of-scope` | The feature request is out of scope for Telegraf - highly unlikely to be worked on |
|
||||
| `closed/question` | This issue is a support question, directed to community site or slack |
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Before Review
|
||||
|
||||
Ensure that the CLA is signed (the `telegraf-tiger` bot performs this check). The
|
||||
Ensure that the CLA is signed (the `telegraf-tiger` bot performs this check). The
|
||||
only exemption would be non-copyrightable changes such as fixing a typo.
|
||||
|
||||
Check that all tests are passing. Due to intermittent errors in the CI tests
|
||||
|
|
@ -36,13 +36,15 @@ history and this method allows us to normalize commit messages as well as
|
|||
simplifies backporting.
|
||||
|
||||
### Rewriting the commit message
|
||||
|
||||
After selecting "Squash and Merge" you may need to rewrite the commit message.
|
||||
Usually the body of the commit messages should be cleared as well, unless it
|
||||
is well written and applies to the entire changeset.
|
||||
- Use imperative present tense for the first line of the message:
|
||||
- Use "Add tests for" (instead of "I added tests for" or "Adding tests for")
|
||||
- The default merge commit messages include the PR number at the end of the
|
||||
commit message, keep this in the final message.
|
||||
is well written and applies to the entire changeset.
|
||||
|
||||
- Use imperative present tense for the first line of the message:
|
||||
- Use "Add tests for" (instead of "I added tests for" or "Adding tests for")
|
||||
- The default merge commit messages include the PR number at the end of the
|
||||
commit message, keep this in the final message.
|
||||
- If applicable mention the plugin in the message.
|
||||
|
||||
**Example Enhancement:**
|
||||
|
|
@ -59,7 +61,8 @@ commit message, keep this in the final message.
|
|||
|
||||
If required, backport the patch and the changelog update to the current
|
||||
release branch. Usually this can be done by cherry picking the commits:
|
||||
```
|
||||
|
||||
```shell
|
||||
git cherry-pick -x aaaaaaaa bbbbbbbb
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -3,21 +3,25 @@
|
|||
## Release Branch
|
||||
|
||||
On master, update `etc/telegraf.conf` and commit:
|
||||
|
||||
```sh
|
||||
./telegraf config > etc/telegraf.conf
|
||||
```
|
||||
|
||||
Create the new release branch:
|
||||
|
||||
```sh
|
||||
git checkout -b release-1.15
|
||||
```
|
||||
|
||||
Push the changes:
|
||||
|
||||
```sh
|
||||
git push origin release-1.15 master
|
||||
```
|
||||
|
||||
Update next version strings on master:
|
||||
|
||||
```sh
|
||||
git checkout master
|
||||
echo 1.16.0 > build_version.txt
|
||||
|
|
@ -29,6 +33,7 @@ Release candidates are created only for new minor releases (ex: 1.15.0). Tags
|
|||
are created but some of the other tasks, such as adding a changelog entry are
|
||||
skipped. Packages are added to the github release page and posted to
|
||||
community but are not posted to package repos or docker hub.
|
||||
|
||||
```sh
|
||||
git checkout release-1.15
|
||||
git commit --allow-empty -m "Telegraf 1.15.0-rc1"
|
||||
|
|
@ -40,6 +45,7 @@ git push origin release-1.15 v1.15.0-rc1
|
|||
|
||||
On master, set the release date in the changelog and cherry-pick the change
|
||||
back:
|
||||
|
||||
```sh
|
||||
git checkout master
|
||||
vi CHANGELOG.md
|
||||
|
|
@ -52,6 +58,7 @@ Double check that the changelog was applied as desired, or fix it up and
|
|||
amend the change before pushing.
|
||||
|
||||
Tag the release:
|
||||
|
||||
```sh
|
||||
git checkout release-1.8
|
||||
# This just improves the `git show 1.8.0` output
|
||||
|
|
@ -61,6 +68,7 @@ git tag -s v1.8.0 -m "Telegraf 1.8.0"
|
|||
|
||||
Check that the version was set correctly, the tag can always be altered if a
|
||||
mistake is made but only before you push it to Github:
|
||||
|
||||
```sh
|
||||
make
|
||||
./telegraf --version
|
||||
|
|
@ -69,6 +77,7 @@ Telegraf v1.8.0 (git: release-1.8 aaaaaaaa)
|
|||
|
||||
When you push a branch with a tag to Github, CircleCI will be triggered to
|
||||
build the packages.
|
||||
|
||||
```sh
|
||||
git push origin master release-1.8 v1.8.0
|
||||
```
|
||||
|
|
@ -82,6 +91,7 @@ Update apt and yum repositories hosted at repos.influxdata.com.
|
|||
Update the package signatures on S3, these are used primarily by the docker images.
|
||||
|
||||
Update docker image [influxdata/influxdata-docker](https://github.com/influxdata/influxdata-docker):
|
||||
|
||||
```sh
|
||||
cd influxdata-docker
|
||||
git co master
|
||||
|
|
|
|||
Loading…
Reference in New Issue