# Logging cookbook

The Atomica logger is named `'atomica'`. Typically, the logger is accessed via

    import atomica
    logger = atomica.logger
    
Loggers are stored globally by name, so you can alternatively retrieve the logger from anywhere using

	import logging
	logger = logging.getLogger('atomica')

### Changing the amount of output

Once you have the logger object (e.g. in your own script) you can change the logging level to control the amount of output displayed. The most common levels are

Level | Command
--- | ---
Show warnings or worse only | `logger.setLevel('WARNING')`
**Default** - Show normal output | `logger.setLevel('INFO')`
Show extra detailed output | `logger.setLevel('DEBUG')`

When writing code for Atomica, set the level of the message accordingly e.g. in the code you are writing, use

	logger.warning('This should be displayed as a warning')
	logger.info('This is information that the user will normally see')
	logger.debug('This is extra-verbose output')

Note that the use of `logger.debug` means that you do not need to set `verbose` flags and `if` statements - instead, just set the logging level to `debug`.

Note also that the default logging level is set in `atomica/__init__.py` so normally you should set the logging level in your script _after_ importing Atomica e.g.

	import atomica as at
	at.logger.setLevel('DEBUG')

### Dumping output to a log file

A common task is storing the log messages for a simulation run. This can be accomplished easily using the `at.start_logging` function:

    import atomica as at
    at.start_logging('logfile.txt')
   
This will automatically create the log file, and prepend version information (normally not printed). Log messages replicate the messages printed
by Atomica. The traceback for any unhandled errors that occur will also be logged. The log messages are gated by the logger level in Atomica, 
so the verbosity can be changed by using `at.logger.setLevel`.

The key items that will NOT be captured in the file log are

- Output generated by a `print` statement. Instead of using `print`, use
  `at.logger.info('message')` which will both print and log the output
- Output generated by worker processes e.g. if using `run_sampled_sims(parallel=True)`

You can stop logging and close the file by using

    at.stop_logging()
    
The optional `reset` argument to `at.start_logging()` allows you to close any existing file loggers, and clear any existing log file with the requested filename. For instance,

    at.start_logging('logfile.txt', reset=True)
    
is equivalent to 

    at.stop_logging()
    at.start_logging('logfile.txt')
    
such that any existing file logs will be closed, and if `logfile.txt` already exists, it will be cleared. Otherwise, if a file logger has already been created, starting logging will have no effect. For example,

    at.start_logging('logfile.txt')
    at.start_logging('logfile2.txt')
    
The second command will not have any effect and only `logfile.txt` will be created.