branch: externals/emacs-gc-stats
commit 5de4b6590a978bbc5815251c0e740926c877738b
Author: Ihor Radchenko <yanta...@posteo.net>
Commit: Ihor Radchenko <yanta...@posteo.net>
Update README
* README.org (Usage): Add new customizations to usage instructions.
Document the reminder functionality.
(Security considerations): Document potential security considerations
and how to control what is being logged. Update the list of logged
information.
(Version 1.3): Document changes.
---
README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++------
README.org | 54 ++++++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 100 insertions(+), 12 deletions(-)
diff --git a/README.md b/README.md
index f6443497ab..dbb658f012 100644
--- a/README.md
+++ b/README.md
@@ -9,12 +9,18 @@ Context:
See the source code for information how to contact the author.
-**Usage:**
+
+# Usage
Add
(require 'emacs-gc-stats)
- (setq emacs-gc-stats-gc-defaults 'emacs-defaults) ; optional
+ ;; Optionally reset Emacs GC settings to default values (recommended)
+ (setq emacs-gc-stats-gc-defaults 'emacs-defaults)
+ ;; Optionally set reminder to upload the stats after 3 weeks.
+ (setq emacs-gc-stats-remind t) ; can also be a number of days
+ ;; Optionally disable logging the command names
+ ;; (setq emacs-gc-stats-inhibit-command-name-logging t)
(emacs-gc-stats-mode +1)
to your init file to enable the statistics acquiring.
@@ -22,10 +28,20 @@ to your init file to enable the statistics acquiring.
When you are ready to share the results, run `M-x emacs-gc-stats-save-session`
and then share the saved `emacs-gc-stats-file` (defaults to
`~/.emacs.d/emacs-gc-stats.eld`) by sending an email attachment to
-<mailto:emacs-gc-st...@gnu.org>.
+<mailto:emacs-gc-st...@gnu.org>. You can review the file before
+sharing–it is a text file.
-You can use `M-x emacs-gc-stats-clear` to clear the currently collected
-session data.
+Configure `emacs-gc-stats-remind` to make Emacs display a reminder about
+sharing the results.
+
+
+# Security considerations
+
+This package **does not** upload anything automatically. You will need to
+upload the data manually, by sending email attachment. If necessary,
+you can review `emacs-gc-stats-file` (defaults to
+`~/.emacs.d/emacs-gc-stats.eld`) before uploading–it is just a text
+file.
The following data is being collected after every command:
@@ -35,5 +51,35 @@ The following data is being collected after every command:
- Idle time and Emacs uptime
- Available OS memory (see `memory-info`)
- Emacs memory allocation/GC stats
-- Current command
+- Current command name (potentially sensitive data, can be disabled)
+- Timestamp when every GC is finished
+
+Logging the command names can be disabled by setting
+`emacs-gc-stats-inhibit-command-name-logging` customization.
+
+What exactly is being logger is controlled by
+`emacs-gc-stats-setting-vars`, `emacs-gc-stats-command-vars`, and
+`emacs-gc-stats-summary-vars`.
+
+You can use `M-x emacs-gc-stats-clear` to clear the currently collected
+session data.
+
+You can pause the logging any time by disabling `emacs-gc-stats-mode`
+(`M-x emacs-gc-stats-mode`).
+
+
+# News
+
+
+## Version 1.3
+
+- New customization: `emacs-gc-stats-inhibit-command-name-logging` to
+ disable logging current command name. Logging is enabled by default.
+
+- New customization: `emacs-gc-stats-remind` to set a reminder to share
+ the data. Reminder is disabled by default.
+
+- The data being collected is can now be customized using
+ `emacs-gc-stats-setting-vars`, `emacs-gc-stats-command-vars`, and
+ `emacs-gc-stats-summary-vars`.
diff --git a/README.org b/README.org
index 7a4a916c16..4137998dc9 100644
--- a/README.org
+++ b/README.org
@@ -11,12 +11,17 @@ Context:
See the source code for information how to contact the author.
-*Usage:*
+* Usage
Add
#+begin_src emacs-lisp
(require 'emacs-gc-stats)
-(setq emacs-gc-stats-gc-defaults 'emacs-defaults) ; optional
+;; Optionally reset Emacs GC settings to default values (recommended)
+(setq emacs-gc-stats-gc-defaults 'emacs-defaults)
+;; Optionally set reminder to upload the stats after 3 weeks.
+(setq emacs-gc-stats-remind t) ; can also be a number of days
+;; Optionally disable logging the command names
+;; (setq emacs-gc-stats-inhibit-command-name-logging t)
(emacs-gc-stats-mode +1)
#+end_src
to your init file to enable the statistics acquiring.
@@ -24,10 +29,19 @@ to your init file to enable the statistics acquiring.
When you are ready to share the results, run =M-x emacs-gc-stats-save-session=
and then share the saved ~emacs-gc-stats-file~ (defaults to
=~/.emacs.d/emacs-gc-stats.eld=) by sending an email attachment to
-mailto:emacs-gc-st...@gnu.org.
+mailto:emacs-gc-st...@gnu.org. You can review the file before
+sharing--it is a text file.
-You can use =M-x emacs-gc-stats-clear= to clear the currently collected
-session data.
+Configure ~emacs-gc-stats-remind~ to make Emacs display a reminder about
+sharing the results.
+
+* Security considerations
+
+This package *does not* upload anything automatically. You will need to
+upload the data manually, by sending email attachment. If necessary,
+you can review ~emacs-gc-stats-file~ (defaults to
+=~/.emacs.d/emacs-gc-stats.eld=) before uploading--it is just a text
+file.
The following data is being collected after every command:
- GC settings ~gc-cons-threshold~ and ~gc-cons-percentage~
@@ -36,4 +50,32 @@ The following data is being collected after every command:
- Idle time and Emacs uptime
- Available OS memory (see ~memory-info~)
- Emacs memory allocation/GC stats
-- Current command
+- Current command name (potentially sensitive data, can be disabled)
+- Timestamp when every GC is finished
+
+Logging the command names can be disabled by setting
+~emacs-gc-stats-inhibit-command-name-logging~ customization.
+
+What exactly is being logger is controlled by
+~emacs-gc-stats-setting-vars~, ~emacs-gc-stats-command-vars~, and
+~emacs-gc-stats-summary-vars~.
+
+You can use =M-x emacs-gc-stats-clear= to clear the currently collected
+session data.
+
+You can pause the logging any time by disabling ~emacs-gc-stats-mode~
+(=M-x emacs-gc-stats-mode=).
+
+* News
+
+** Version 1.3
+
+- New customization: ~emacs-gc-stats-inhibit-command-name-logging~ to
+ disable logging current command name. Logging is enabled by default.
+
+- New customization: ~emacs-gc-stats-remind~ to set a reminder to share
+ the data. Reminder is disabled by default.
+
+- The data being collected is can now be customized using
+ ~emacs-gc-stats-setting-vars~, ~emacs-gc-stats-command-vars~, and
+ ~emacs-gc-stats-summary-vars~.
