From e60abdf8eadc17742fca88a72dfcecbf2fff3e15 Mon Sep 17 00:00:00 2001
From: Daniel Nelson <daniel@wavesofdawn.com>
Date: Mon, 26 Mar 2018 19:11:08 -0700
Subject: [PATCH] Update passenger input documentation (#3938)
---
plugins/inputs/passenger/README.md | 166 ++++++++++++-----------------
1 file changed, 68 insertions(+), 98 deletions(-)
diff --git a/plugins/inputs/passenger/README.md b/plugins/inputs/passenger/README.md
index 90c0a2d8..688f4e69 100644
--- a/plugins/inputs/passenger/README.md
+++ b/plugins/inputs/passenger/README.md
@@ -1,57 +1,78 @@
-# Telegraf plugin: passenger
-
-Get phusion passenger stat using their command line utility
-`passenger-status`
-
-# Measurements
-
-Meta:
-
-- tags:
-
- * name
- * passenger_version
- * pid
- * code_revision
+# Passenger Input Plugin
+
+Gather [Phusion Passenger](https://www.phusionpassenger.com/) metrics using the `passenger-status` command line utility.
+
+**Series Cardinality Warning**
+
+Depending on your environment, this `passenger_process` measurement of this
+plugin can quickly create a high number of series which, when unchecked, can
+cause high load on your database. You can use the following techniques to
+manage your series cardinality:
+
+- Use the
+ [measurement filtering](https://docs.influxdata.com/telegraf/latest/administration/configuration/#measurement-filtering)
+ options to exclude unneeded tags. In some environments, you may wish to use
+ `tagexclude` to remove the `pid` and `process_group_id` tags.
+- Write to a database with an appropriate
+ [retention policy](https://docs.influxdata.com/influxdb/latest/guides/downsampling_and_retention/).
+- Limit series cardinality in your database using the
+ [`max-series-per-database`](https://docs.influxdata.com/influxdb/latest/administration/config/#max-series-per-database-1000000) and
+ [`max-values-per-tag`](https://docs.influxdata.com/influxdb/latest/administration/config/#max-values-per-tag-100000) settings.
+- Consider using the
+ [Time Series Index](https://docs.influxdata.com/influxdb/latest/concepts/time-series-index/).
+- Monitor your databases
+ [series cardinality](https://docs.influxdata.com/influxdb/latest/query_language/spec/#show-cardinality).
+
+### Configuration
+
+```toml
+# Read metrics of passenger using passenger-status
+[[inputs.passenger]]
+ ## Path of passenger-status.
+ ##
+ ## Plugin gather metric via parsing XML output of passenger-status
+ ## More information about the tool:
+ ## https://www.phusionpassenger.com/library/admin/apache/overall_status_report.html
+ ##
+ ## If no path is specified, then the plugin simply execute passenger-status
+ ## hopefully it can be found in your PATH
+ command = "passenger-status -v --show=xml"
+```
-Measurement names:
+#### Permissions:
-- passenger:
+Telegraf must have permission to execute the `passenger-status` command. On most systems, Telegraf runs as the `telegraf` user.
- * Tags: `passenger_version`
- * Fields:
+### Metrics:
+- passenger
+ - tags:
+ - passenger_version
+ - fields:
- process_count
- - max
- - capacity_used
- - get_wait_list_size
-
-- passenger_supergroup:
-
- * Tags: `name`
- * Fields:
-
- - get_wait_list_size
- - capacity_used
-
-- passenger_group:
+ - max
+ - capacity_used
+ - get_wait_list_size
- * Tags:
+- passenger_supergroup
+ - tags:
+ - name
+ - fields:
+ - get_wait_list_size
+ - capacity_used
+- passenger_group
+ - tags:
- name
- app_root
- app_type
-
- * Fields:
-
+ - fields:
- get_wait_list_size
- capacity_used
- processes_being_spawned
-- passenger_process:
-
- * Tags:
-
+- passenger_process
+ - tags:
- group_name
- app_root
- supergroup_name
@@ -59,9 +80,7 @@ Measurement names:
- code_revision
- life_status
- process_group_id
-
- * Field:
-
+ - fields:
- concurrency
- sessions
- busyness
@@ -79,60 +98,11 @@ Measurement names:
- real_memory
- vmsize
-# Example output
-
-Using this configuration:
-
-```
-[[inputs.passenger]]
- # Path of passenger-status.
- #
- # Plugin gather metric via parsing XML output of passenger-status
- # More information about the tool:
- # https://www.phusionpassenger.com/library/admin/apache/overall_status_report.html
- #
- #
- # If no path is specified, then the plugin simply execute passenger-status
- # hopefully it can be found in your PATH
- command = "passenger-status -v --show=xml"
-```
-
-When run with:
-
-```
-./telegraf --config telegraf.conf --input-filter passenger --test
-```
-
-It produces:
-
-```
-> passenger,passenger_version=5.0.17 capacity_used=23i,get_wait_list_size=0i,max=23i,process_count=23i 1452984112799414257
-> passenger_supergroup,name=/var/app/current/public capacity_used=23i,get_wait_list_size=0i 1452984112799496977
-> passenger_group,app_root=/var/app/current,app_type=rack,name=/var/app/current/public capacity_used=23i,get_wait_list_size=0i,processes_being_spawned=0i 1452984112799527021
-> passenger_process,app_root=/var/app/current,code_revision=899ac7f,group_name=/var/app/current/public,life_status=ALIVE,pid=11553,process_group_id=13608,supergroup_name=/var/app/current/public busyness=0i,concurrency=1i,cpu=58i,last_used=1452747071764940i,private_dirty=314900i,processed=951i,pss=319391i,real_memory=314900i,rss=418548i,sessions=0i,spawn_end_time=1452746845013365i,spawn_start_time=1452746844946982i,spawner_creation_time=1452746835922747i,swap=0i,uptime=226i,vmsize=1563580i 1452984112799571490
-> passenger_process,app_root=/var/app/current,code_revision=899ac7f,group_name=/var/app/current/public,life_status=ALIVE,pid=11563,process_group_id=13608,supergroup_name=/var/app/current/public busyness=2147483647i,concurrency=1i,cpu=47i,last_used=1452747071709179i,private_dirty=309240i,processed=756i,pss=314036i,real_memory=309240i,rss=418296i,sessions=1i,spawn_end_time=1452746845172460i,spawn_start_time=1452746845136882i,spawner_creation_time=1452746835922747i,swap=0i,uptime=226i,vmsize=1563608i 1452984112799638581
+### Example Output:
```
-
-# Note
-
-You have to ensure that you can run the `passenger-status` command under
-telegraf user. Depend on how you install and configure passenger, this
-maybe an issue for you. If you are using passenger standlone, or compile
-yourself, it is straight forward. However, if you are using gem and
-`rvm`, it maybe harder to get this right.
-
-Such as with `rvm`, you can use this command:
-
+passenger,passenger_version=5.0.17 capacity_used=23i,get_wait_list_size=0i,max=23i,process_count=23i 1452984112799414257
+passenger_supergroup,name=/var/app/current/public capacity_used=23i,get_wait_list_size=0i 1452984112799496977
+passenger_group,app_root=/var/app/current,app_type=rack,name=/var/app/current/public capacity_used=23i,get_wait_list_size=0i,processes_being_spawned=0i 1452984112799527021
+passenger_process,app_root=/var/app/current,code_revision=899ac7f,group_name=/var/app/current/public,life_status=ALIVE,pid=11553,process_group_id=13608,supergroup_name=/var/app/current/public busyness=0i,concurrency=1i,cpu=58i,last_used=1452747071764940i,private_dirty=314900i,processed=951i,pss=319391i,real_memory=314900i,rss=418548i,sessions=0i,spawn_end_time=1452746845013365i,spawn_start_time=1452746844946982i,spawner_creation_time=1452746835922747i,swap=0i,uptime=226i,vmsize=1563580i 1452984112799571490
+passenger_process,app_root=/var/app/current,code_revision=899ac7f,group_name=/var/app/current/public,life_status=ALIVE,pid=11563,process_group_id=13608,supergroup_name=/var/app/current/public busyness=2147483647i,concurrency=1i,cpu=47i,last_used=1452747071709179i,private_dirty=309240i,processed=756i,pss=314036i,real_memory=309240i,rss=418296i,sessions=1i,spawn_end_time=1452746845172460i,spawn_start_time=1452746845136882i,spawner_creation_time=1452746835922747i,swap=0i,uptime=226i,vmsize=1563608i 1452984112799638581
```
-~/.rvm/bin/rvm default do passenger-status -v --show=xml
-```
-
-You can use `&` and `;` in the shell command to run comlicated shell command
-in order to get the passenger-status such as load the rvm shell, source the
-path
-```
-command = "source .rvm/scripts/rvm && passenger-status -v --show=xml"
-```
-
-Anyway, just ensure that you can run the command under `telegraf` user, and it
-has to produce XML output.
--
GitLab