GoogleDriveManagement/docs/Command-Logging-Progress.md
Ross Scroggs 896f7f5d37
Some checks failed
Build and test GAM / build (Win64, build, 9, VC-WIN64A, windows-2022) (push) Waiting to run
Build and test GAM / build (aarch64, build, 3, linux-aarch64, [self-hosted linux arm64]) (push) Waiting to run
Build and test GAM / build (aarch64, build, 5, linux-aarch64, [self-hosted linux arm64], yes) (push) Waiting to run
Build and test GAM / build (aarch64, build, 7, darwin64-arm64, macos-14) (push) Waiting to run
Build and test GAM / build (x86_64, build, 1, linux-x86_64, ubuntu-22.04) (push) Waiting to run
Build and test GAM / build (x86_64, build, 2, linux-x86_64, ubuntu-20.04) (push) Waiting to run
Build and test GAM / build (x86_64, build, 4, linux-x86_64, ubuntu-20.04, yes) (push) Waiting to run
Build and test GAM / build (x86_64, build, 6, darwin64-x86_64, macos-13) (push) Waiting to run
Build and test GAM / build (x86_64, test, 10, ubuntu-22.04, 3.13) (push) Waiting to run
Build and test GAM / build (x86_64, test, 11, ubuntu-22.04, 3.9) (push) Waiting to run
Build and test GAM / build (x86_64, test, 12, ubuntu-22.04, 3.10) (push) Waiting to run
Build and test GAM / build (x86_64, test, 8, ubuntu-22.04, 3.11) (push) Waiting to run
Build and test GAM / merge (push) Blocked by required conditions
Build and test GAM / publish (push) Blocked by required conditions
Check for Google Root CA Updates / check-apis (push) Waiting to run
CodeQL / Analyze (python) (push) Has been cancelled
Initial limited access, api_call_tries_limit new max
2024-09-29 21:05:40 -07:00

89 lines
4.8 KiB
Markdown

# Command Logging and Progress
- [Introduction](#introduction)
- [GAM Configuration](gam.cfg)
- [Command Logging](#command-logging)
- [Command Progress](#command-progress)
## Introduction
Starting with version 6.07.00, GAM can log its commands to a file.
Display of `gam batch|tbatch|csv|loop` progress messages has been improved.
## 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
```