Skip to content

Latest commit

 

History

History
129 lines (94 loc) · 4.84 KB

WINDOWS_SERVICE.md

File metadata and controls

129 lines (94 loc) · 4.84 KB
Raw

Running Telegraf as a Windows Service

Telegraf natively supports running as a Windows Service. Outlined below is are the general steps to set it up.

  1. Obtain the telegraf windows distribution

  2. Create the directory C:\Program Files\Telegraf or use a custom directory if desired

  3. Place the telegraf.exe and the telegraf.conf config file into the directory, either C:\Program Files\Telegraf or the custom directory of your choice. If you install in a different location simply specify the --config parameter with the desired location.

  4. To install the service into the Windows Service Manager, run the command as administrator. Make sure to wrap parameters containing spaces in double quotes:

    > "C:Program Files\Telegraf\telegraf.exe" service install

  5. Edit the configuration file to meet your needs

  6. To check that it works, run:

    > "C:\Program Files\Telegraf\telegraf.exe" --config "C:\Program Files\Telegraf\telegraf.conf" --test

  7. To start collecting data, run:

    > net start telegraf

    or

    > "C:\Program Files\Telegraf\telegraf.exe" service start

    or use the Windows service manager to start the service

Please also check the Windows event log or your configured log-file for errors during startup.

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:

    > "C:\Program Files\Telegraf\telegraf.exe" --config C:\"Program Files"\Telegraf\telegraf.conf --config-directory C:\"Program Files"\Telegraf\telegraf.d service install

Other supported operations

Telegraf can manage its own service through the --service flag:

Command Effect
telegraf.exe service install Install telegraf as a service
telegraf.exe service uninstall Remove the telegraf service
telegraf.exe service start Start the telegraf service
telegraf.exe service stop Stop the telegraf service
telegraf.exe service status Query the status of the telegraf service

Install multiple services

Running multiple instances of Telegraf is seldom needed, as you can run multiple instances of each plugin and route metric flow using the metric 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 --display-name flags to give the services unique names:

> "C:\Program Files\Telegraf\telegraf.exe" --service-name telegraf-1 service install --display-name "Telegraf 1"
> "C:\Program Files\Telegraf\telegraf.exe" --service-name telegraf-2 service install --display-name "Telegraf 2"

Auto restart and restart delay

By default the service will not automatically restart on failure. Providing the --auto-restart flag during installation will always restart the service with a default delay of 5 minutes. To modify this to for example 3 minutes, additionally provide --restart-delay 3m flag. The delay can be any valid time.Duration string.

Troubleshooting

When Telegraf runs as a Windows service, Telegraf logs all messages concerning the service startup to the Windows event log. All messages and errors occuring during runtime will be logged to the log-target you configured. Check the event log for errors reported by the telegraf service (or the service-name you configured) during service startup: Event Viewer -> Windows Logs -> Application

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. Use

> "C:\Program Files\Telegraf\telegraf.exe" --config "C:\MyConfigs\telegraf.conf" service install

instead of

> "C:\Program Files\Telegraf\telegraf.exe" --config "telegraf.conf" service install

Service is killed during shutdown

When shuting down Windows the Telegraf service tries to cleanly stop when receiving the corresponding notification from the Windows service manager. The exit process involves stopping all inputs, processors and aggregators and finally to flush all remaining metrics to the output(s). In case many metrics are not yet flushed this final step might take some time. However, Windows will kill the service and the corresponding process after a predefined timeout (usually 5 seconds).

You can change that timeout in the registry under

HKLM\SYSTEM\CurrentControlSet\Control\WaitToKillServiceTimeout
```

**NOTE:** The value is in milliseconds and applies to **all** services!