# Command Logging and Progress
- [GAM Configuration](gam.cfg)
- [Command Logging](#command-logging)
- [Command Progress](#command-progress)

## Command Logging
The following keywords in `gam.cfg` control logging of GAM commands.
```
cmdlog
        Path to GAM Log file; there is no logging if cmdlog is empty
        Default: ''
cmdlog_max_backups
        Maximum number of backup log files
        Default: 5
        Range: 1 - 10
cmdlog_max_kilo_bytes
        Maximum kilobytes per log file
        Default: 1000
        Range: 100 - 10000
```

If `cmdlog` specifies a relative file path, it is appended to `config_dir` in the current section if defined or `config_dir` in `[DEFAULT]`.
This makes it easy to have distinct log files when you have multiple clients/tenants defined in `gam.cfg`

You use the `cmdlog_max_kilo_bytes` and `cmdlog_max_backups` values to cause the log file to rollover at a predetermined size.
When the log file is nearly `cmdlog_max_kilo_bytes` in length, it is closed and a new log file is silently opened for output.
The system will save old log files by appending `.N`, to the filename. For example, with a `cmdlog_max_backups` of 5 and a base log file name of `gam.log`, you would get `gam.log`, `gam.log.1`, `gam.log.2`, up to `gam.log.5`.
The log file being written to is always `gam.log`. When this log file is filled, it is closed and renamed to `gam.log.1`, and if files `gam.log.1`, `gam.log.2`, etc. exist, then they are renamed to `gam.log.2`, `gam.log.3` etc. respectively.

Commands are logged at completion with a timestamp, return code and the command line
```
2021-08-01T19:350:30.777-07:00,0,/Users/admin/bin/gam7/gam info domain
```

Commands that generate sub-commands, `gam batch|tbatch|csv|loop`, log the initial command with a return code of `*`,
the sub-command lines and the initial command with a numeric return code.
```
$ gam redirect stdout usernames.csv multiprocess redirect stderr stdout csv users.csv gam info user "~primaryEmail" quick name
2021-08-01T19:50:38.151-07:00,0/6,Using 6 processes...
$ more ~/.gam/gam.log
2021-08-01T19:50:38.120-07:00,*,/Users/admin/bin/gam7/gam redirect stdout usernames.csv multiprocess redirect stderr stdout csv users.csv showcmds false gam info user "~primaryEmail" quick name
2021-08-01T19:50:39.144-07:00,0,gam info user testuser2 quick name
2021-08-01T19:50:39.358-07:00,0,gam info user testuser3 quick name
2021-08-01T19:50:39.358-07:00,0,gam info user testuser1 quick name
2021-08-01T19:50:39.401-07:00,0,gam info user testuser5 quick name
2021-08-01T19:50:39.459-07:00,56,gam info user testuserx quick name
2021-08-01T19:50:39.470-07:00,0,gam info user testuser4 quick name
2021-08-01T19:50:39.483-07:00,0,/Users/admin/bin/gam7/gam redirect stdout usernames.csv multiprocess redirect stderr stdout csv users.csv showcmds false gam info user "~primaryEmail" quick name
```

## Command Progress
Added the following keyword to `gam.cfg` to display sub-commands to stderr when executing `gam batch|tbatch|csv|loop`.
The commands are displayed when initiated/completed so you can monitor GAM's progress.
```
show_commands
        Display commands to stderr when executing `gam batch|tbatch|csv|loop`.
        Default: False
```
This value will be used when not overridden by the `showcmds [<Boolean>]` command line option; see [Bulk Processing](Bulk-Processing).

Sub-commands are displayed at initiation with a timestamp, index/total, Start, 0 and the sub-command line.

Sub-commands are displayed at completion with a timestamp, index/total, End, return code and the sub-command line.

```
$ gam redirect stdout usernames.csv multiprocess redirect stderr stdout csv users.csv showcmds true gam info user "~primaryEmail" quick name
2021-08-01T19:46:07.845-07:00,0/6,Using 6 processes...
2021-08-01T19:46:07.846-07:00,1/6,Start,0,gam info user testuser1 quick name
2021-08-01T19:46:07.846-07:00,2/6,Start,0,gam info user testuser2 quick name
2021-08-01T19:46:07.846-07:00,3/6,Start,0,gam info user testuser3 quick name
2021-08-01T19:46:07.846-07:00,4/6,Start,0,gam info user testuser4 quick name
2021-08-01T19:46:07.846-07:00,5/6,Start,0,gam info user testuser5 quick name
2021-08-01T19:46:07.846-07:00,6/6,Start,0,gam info user testuserx quick name
2021-08-01T19:46:08.827-07:00,3/6,End,0,gam info user testuser3 quick name
2021-08-01T19:46:08.983-07:00,2/6,End,0,gam info user testuser2 quick name
2021-08-01T19:46:08.983-07:00,1/6,End,0,gam info user testuser1 quick name
2021-08-01T19:46:09.049-07:00,6/6,End,56,gam info user testuserx quick name
2021-08-01T19:46:09.059-07:00,5/6,End,0,gam info user testuser5 quick name
2021-08-01T19:46:09.079-07:00,4/6,End,0,gam info user testuser4 quick name
2021-08-01T19:46:09.083-07:00,0/6,Complete
```