diff --git a/docs/changes.rst b/docs/changes.rst index 9a604853..8315e5f3 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -42,6 +42,9 @@ Released: not yet **Enhancements:** +* Docs: Added a section about the size of captured terminal output and log + files. (issue #528) + **Cleanup:** **Known issues:** diff --git a/docs/usage.rst b/docs/usage.rst index ec52f10c..ce905b44 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -97,7 +97,7 @@ The ``zhmc_prometheus_exporter`` command supports the following arguments: -m METRICS_FILE path name of metric definition file. Use --help-metrics for details. Default: /etc/zhmc-prometheus-exporter/metrics.yaml - -p PORT port for exporting. Default: prometheus.port in HMC credentials file. + -p PORT port for exporting. Default: prometheus.port in HMC credentials file --log DEST enable logging and set a log destination (stderr, syslog, FILE). Default: no logging @@ -105,19 +105,54 @@ The ``zhmc_prometheus_exporter`` command supports the following arguments: --log-comp COMP[=LEVEL] set a logging level (error, warning, info, debug, off, default: warning) for a component (exporter, hmc, jms, all). May be specified multiple - times; options add to the default of: all=warning + times; options add to the default of: all=warning. Note that using log + levels 'info' or 'debug' will produce continuously growing log output. --syslog-facility TEXT syslog facility (user, local0, local1, local2, local3, local4, local5, local6, local7) when logging to the system log. Default: user - --verbose, -v increase the verbosity level (max: 2) + --verbose, -v increase the verbosity level of terminal output during startup of the + exporter (max: 2). After the exporter is up and running, no more terminal + output will be produced, except in the case of warnings or connection + issues. + + --version show versions of exporter and zhmcclient library and exit --help-creds show help for HMC credentials file and exit --help-metrics show help for metric definition file and exit +Size of log files and terminal output +------------------------------------- + +Since the exporter is a long-running process, the size of log files and +of any captured terminal output is important to understand. + +The amount of terminal output during startup of the exporter can be controlled +using the ``-v`` / ``--verbose`` option. Once the exporter is up and running, +no more terminal output will be produced (independent of the verbosity level), +except in the case of warnings or connection issues. + +When running the exporter in a container, the container tools usually provide +ways to limit the size of the log files with captured terminal output. +For example, Docker provides the ``--log-opt max-size`` and ``--log-opt max-file`` +options. Even though the exporter should not produce continuously growing +terminal output, it may still be a good idea to use such options, just to be on +the safe side. + +If logging is enabled (with the ``--log`` option of the forwarder), the amount +of log entries can be controlled with the ``--log-comp`` option. Log levels +``info`` and ``debug`` will produce log entries upon each data collection by +Prometheus, and therefore will produce continuously growing log output. + +If you experience continuously growing terminal or log output when it should +not be growing according to the above, please open an +`issue `_ +and provide the captured terminal output or the log file that is growing. + + Setting up the HMC ------------------ diff --git a/zhmc_prometheus_exporter/zhmc_prometheus_exporter.py b/zhmc_prometheus_exporter/zhmc_prometheus_exporter.py index 15a716fc..475a6316 100755 --- a/zhmc_prometheus_exporter/zhmc_prometheus_exporter.py +++ b/zhmc_prometheus_exporter/zhmc_prometheus_exporter.py @@ -237,7 +237,8 @@ def parse_args(args): help="set a logging level ({levels}, default: " "{def_level}) for a component ({comps}). May be " "specified multiple times; options add to the default " - "of: {def_comp}". + "of: {def_comp}. Note that using log levels 'info' or " + "'debug' will produce continuously growing log output.". format(levels=', '.join(VALID_LOG_LEVELS), comps=', '.join(VALID_LOG_COMPONENTS), def_level=DEFAULT_LOG_LEVEL, @@ -249,7 +250,11 @@ def parse_args(args): format(slfs=', '.join(VALID_SYSLOG_FACILITIES), def_slf=DEFAULT_SYSLOG_FACILITY)) parser.add_argument("--verbose", "-v", action='count', default=0, - help="increase the verbosity level (max: 2)") + help="increase the verbosity level of terminal output " + "during startup of the exporter (max: 2). After the " + "exporter is up and running, no more terminal output " + "will be produced, except in the case of warnings or " + "connection issues.") parser.add_argument("--version", action='store_true', help="show versions of exporter and zhmcclient library " "and exit")