diff options
Diffstat (limited to 'research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src')
| -rw-r--r-- | research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md new file mode 100644 index 0000000..e1d6022 --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Logging/docs/src/index.md @@ -0,0 +1,311 @@ +# Logging + +The [`Logging`](@ref Logging.Logging) module provides a way to record the history and progress of a +computation as a log of events. Events are created by inserting a logging +statement into the source code, for example: + +```julia +@warn "Abandon printf debugging, all ye who enter here!" +┌ Warning: Abandon printf debugging, all ye who enter here! +└ @ Main REPL[1]:1 +``` + +The system provides several advantages over peppering your source code with +calls to `println()`. First, it allows you to control the visibility and +presentation of messages without editing the source code. For example, in +contrast to the `@warn` above + +```julia +@debug "The sum of some values $(sum(rand(100)))" +``` + +will produce no output by default. Furthermore, it's very cheap to leave debug +statements like this in the source code because the system avoids evaluating +the message if it would later be ignored. In this case `sum(rand(100))` and +the associated string processing will never be executed unless debug logging is +enabled. + +Second, the logging tools allow you to attach arbitrary data to each event as a +set of key--value pairs. This allows you to capture local variables and other +program state for later analysis. For example, to attach the local array +variable `A` and the sum of a vector `v` as the key `s` you can use + +```jldoctest +A = ones(Int, 4, 4) +v = ones(100) +@info "Some variables" A s=sum(v) + +# output +┌ Info: Some variables +│ A = +│ 4×4 Matrix{Int64}: +│ 1 1 1 1 +│ 1 1 1 1 +│ 1 1 1 1 +│ 1 1 1 1 +└ s = 100.0 +``` + +All of the logging macros `@debug`, `@info`, `@warn` and `@error` share common +features that are described in detail in the documentation for the more +general macro [`@logmsg`](@ref). + +## Log event structure + +Each event generates several pieces of data, some provided by the user and some +automatically extracted. Let's examine the user-defined data first: + +* The *log level* is a broad category for the message that is used for early + filtering. There are several standard levels of type [`LogLevel`](@ref); + user-defined levels are also possible. + Each is distinct in purpose: + - `Debug` is information intended for the developer of the program. + These events are disabled by default. + - `Info` is for general information to the user. + Think of it as an alternative to using `println` directly. + - `Warn` means something is wrong and action is likely required + but that for now the program is still working. + - `Error` means something is wrong and it is unlikely to be recovered, + at least by this part of the code. + Often this log-level is unneeded as throwing an exception can convey + all the required information. + +* The *message* is an object describing the event. By convention + `AbstractString`s passed as messages are assumed to be in markdown format. + Other types will be displayed using `print(io, obj)` or `string(obj)` for + text-based output and possibly `show(io,mime,obj)` for other multimedia + displays used in the installed logger. +* Optional *key--value pairs* allow arbitrary data to be attached to each event. + Some keys have conventional meaning that can affect the way an event is + interpreted (see [`@logmsg`](@ref)). + +The system also generates some standard information for each event: + +* The `module` in which the logging macro was expanded. +* The `file` and `line` where the logging macro occurs in the source code. +* A message `id` that is a unique, fixed identifier for the *source code + statement* where the logging macro appears. This identifier is designed to be + fairly stable even if the source code of the file changes, as long as the + logging statement itself remains the same. +* A `group` for the event, which is set to the base name of the file by default, + without extension. This can be used to group messages into categories more + finely than the log level (for example, all deprecation warnings have group + `:depwarn`), or into logical groupings across or within modules. + +Notice that some useful information such as the event time is not included by +default. This is because such information can be expensive to extract and is +also *dynamically* available to the current logger. It's simple to define a +[custom logger](@ref AbstractLogger-interface) to augment event data with the +time, backtrace, values of global variables and other useful information as +required. + + +## Processing log events + +As you can see in the examples, logging statements make no mention of +where log events go or how they are processed. This is a key design feature +that makes the system composable and natural for concurrent use. It does this +by separating two different concerns: + +* *Creating* log events is the concern of the module author who needs to + decide where events are triggered and which information to include. +* *Processing* of log events — that is, display, filtering, aggregation and + recording — is the concern of the application author who needs to bring + multiple modules together into a cooperating application. + +### Loggers + +Processing of events is performed by a *logger*, which is the first piece of +user configurable code to see the event. All loggers must be subtypes of +[`AbstractLogger`](@ref). + +When an event is triggered, the appropriate logger is found by looking for a +task-local logger with the global logger as fallback. The idea here is that +the application code knows how log events should be processed and exists +somewhere at the top of the call stack. So we should look up through the call +stack to discover the logger — that is, the logger should be *dynamically +scoped*. (This is a point of contrast with logging frameworks where the +logger is *lexically scoped*; provided explicitly by the module author or as a +simple global variable. In such a system it's awkward to control logging while +composing functionality from multiple modules.) + +The global logger may be set with [`global_logger`](@ref), and task-local +loggers controlled using [`with_logger`](@ref). Newly spawned tasks inherit +the logger of the parent task. + +There are three logger types provided by the library. [`ConsoleLogger`](@ref) +is the default logger you see when starting the REPL. It displays events in a +readable text format and tries to give simple but user friendly control over +formatting and filtering. [`NullLogger`](@ref) is a convenient way to drop all +messages where necessary; it is the logging equivalent of the [`devnull`](@ref) +stream. [`SimpleLogger`](@ref) is a very simplistic text formatting logger, +mainly useful for debugging the logging system itself. + +Custom loggers should come with overloads for the functions described in the +[reference section](@ref AbstractLogger-interface). + +### Early filtering and message handling + +When an event occurs, a few steps of early filtering occur to avoid generating +messages that will be discarded: + +1. The message log level is checked against a global minimum level (set via + [`disable_logging`](@ref)). This is a crude but extremely cheap global + setting. +2. The current logger state is looked up and the message level checked against the + logger's cached minimum level, as found by calling [`Logging.min_enabled_level`](@ref). + This behavior can be overridden via environment variables (more on this later). +3. The [`Logging.shouldlog`](@ref) function is called with the current logger, taking + some minimal information (level, module, group, id) which can be computed + statically. Most usefully, `shouldlog` is passed an event `id` which can be + used to discard events early based on a cached predicate. + +If all these checks pass, the message and key--value pairs are evaluated in full +and passed to the current logger via the [`Logging.handle_message`](@ref) function. +`handle_message()` may perform additional filtering as required and display the +event to the screen, save it to a file, etc. + +Exceptions that occur while generating the log event are captured and logged +by default. This prevents individual broken events from crashing the +application, which is helpful when enabling little-used debug events in a +production system. This behavior can be customized per logger type by +extending [`Logging.catch_exceptions`](@ref). + +## Testing log events + +Log events are a side effect of running normal code, but you might find +yourself wanting to test particular informational messages and warnings. The +`Test` module provides a [`@test_logs`](@ref) macro that can be used to +pattern match against the log event stream. + +## Environment variables + +Message filtering can be influenced through the `JULIA_DEBUG` environment +variable, and serves as an easy way to enable debug logging for a file or +module. For example, loading julia with `JULIA_DEBUG=loading` will activate +`@debug` log messages in `loading.jl`: + +``` +$ JULIA_DEBUG=loading julia -e 'using OhMyREPL' +┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an invalid cache header +└ @ Base loading.jl:1328 +[ Info: Recompiling stale cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji for module OhMyREPL +┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/Tokenize.ji due to it containing an invalid cache header +└ @ Base loading.jl:1328 +... +``` + +Similarly, the environment variable can be used to enable debug logging of +modules, such as `Pkg`, or module roots (see [`Base.moduleroot`](@ref)). To +enable all debug logging, use the special value `all`. + +To turn debug logging on from the REPL, set `ENV["JULIA_DEBUG"]` to the +name of the module of interest. Functions defined in the REPL belong to +module `Main`; logging for them can be enabled like this: +```julia-repl +julia> foo() = @debug "foo" +foo (generic function with 1 method) + +julia> foo() + +julia> ENV["JULIA_DEBUG"] = Main +Main + +julia> foo() +┌ Debug: foo +└ @ Main REPL[1]:1 + +``` + +## Writing log events to a file + +Sometimes it can be useful to write log events to a file. Here is an example +of how to use a task-local and global logger to write information to a text +file: + +```julia-repl +# Load the logging module +julia> using Logging + +# Open a textfile for writing +julia> io = open("log.txt", "w+") +IOStream(<file log.txt>) + +# Create a simple logger +julia> logger = SimpleLogger(io) +SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}()) + +# Log a task-specific message +julia> with_logger(logger) do + @info("a context specific log message") + end + +# Write all buffered messages to the file +julia> flush(io) + +# Set the global logger to logger +julia> global_logger(logger) +SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}()) + +# This message will now also be written to the file +julia> @info("a global log message") + +# Close the file +julia> close(io) +``` + + +## Reference + +### Logging module +```@docs +Logging.Logging +``` + +### Creating events + +```@docs +Logging.@logmsg +Logging.LogLevel +``` + +### [Processing events with AbstractLogger](@id AbstractLogger-interface) + +Event processing is controlled by overriding functions associated with +`AbstractLogger`: + +| Methods to implement | | Brief description | +|:----------------------------------- |:---------------------- |:---------------------------------------- | +| [`Logging.handle_message`](@ref) | | Handle a log event | +| [`Logging.shouldlog`](@ref) | | Early filtering of events | +| [`Logging.min_enabled_level`](@ref) | | Lower bound for log level of accepted events | +| **Optional methods** | **Default definition** | **Brief description** | +| [`Logging.catch_exceptions`](@ref) | `true` | Catch exceptions during event evaluation | + + +```@docs +Logging.AbstractLogger +Logging.handle_message +Logging.shouldlog +Logging.min_enabled_level +Logging.catch_exceptions +Logging.disable_logging +``` + +### Using Loggers + +Logger installation and inspection: + +```@docs +Logging.global_logger +Logging.with_logger +Logging.current_logger +``` + +Loggers that are supplied with the system: + +```@docs +Logging.NullLogger +Logging.ConsoleLogger +Logging.SimpleLogger +``` |