Merge lp:~evilnick/clouddocs/logging into lp:~jujudocs/clouddocs/trunk

[Nick Veitch]

expanded logging section

=== modified file 'Admin/Logging-Juju.md'
--- Admin/Logging-Juju.md	2014-04-28 22:58:36 +0000
+++ Admin/Logging-Juju.md	2014-04-30 23:25:12 +0000
@@ -1,24 +1,69 @@
 Title: Logging - Juju
 Status: In Progress
 
-# Logging - Juju
-
-## Introduction
-
-**TODO**
-
-## Scope
-
-**TODO**
+# Logging 
+
+Logging is set up to occur on each instance. This includes the normal service logs
+for whichever services are deployed on that particular instance. For example,
+if you deploy the apache2 service, the logs will appear on that instance in 
+`/var/log/apache2/` as one might expect.
+To examine instance level logs, you can simply use ssh to connect to a given 
+machine:
+```
+juju ssh <machine number>
+```
+The same directory also contains the juju logs for that service, located in 
+`/var/log/juju`.
+However, it is often more useful to view the systemwide logs for Juju. Juju uses
+rsyslogd to aggregate all logs to get a better systemwide view of Juju's 
+activity.
+
 
 ## Connecting to rsyslogd
-
-Juju already uses `rsyslogd` for the aggregation of all logs into one centralized log. The
-target of this logging is the file `/var/log/juju/all-machines.log`. You can directly
+The target of the aggregated log is the file `/var/log/juju/all-machines.log`. You can directly
 access it using the command:
 
-````
-$ juju debug-log
-````
+```
+juju debug-log [-n <number>] [-n +<number>] [-e <environment>]
+```
+
+Where the -n switch is given and followed by a number, the log will be tailed from that many lines in the past (i.e., those number of existing lines in the log will be included in the output, along with any subsequent output).
+
+Where the -n switch is given and followed by a '+' and a number, the log will be tailed starting from that specific line in the log file.
+
+This somewhat unusual syntax has been chosen so that the command behaves like the standard Unix tail command. In fact, it is analagous to running tail -f [options] /var/log/juju/all-machines.log on the bootstrap node.
+Examples:
+
+To read the ten most recent log entries and follow any subsequent entries to the log:
+
+
+```
+juju debug-log
+```
+
+To read the thirty most recent log entries and follow any subsequent entries to the log:
+
+
+```
+juju debug-log -n 30
+```
+
+To read all the log entries and follow any subsequent entries to the log:
+
+```
+juju debug-log -n +1
+```
+
+And of course it is possible to combine the command with other shell tools to make the 
+output more useful, e.g. to filter the whole log for lines matching 'INFO':
+
+```
+juju debug-log -n +1  | grep 'INFO'
+```
+
+!!!Note: As the command uses the follow behaviour of tail by default, you do not need to 
+specify the -f switch. You will also need to end the session with Control-C
+
+
 
 **TODO** Describe a way to redirect this log to a central rsyslogd server.