You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/en/docs/logging.jlmd
+59-4Lines changed: 59 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -10,6 +10,36 @@ order: 21
10
10
11
11
To help with debugging your code, Pluto supports showing messages printed with the [standard library Logging module](https://docs.julialang.org/en/v1/stdlib/Logging/). This can be done using the `@info`, `@warn` and `@error` macro.
12
12
13
+
For example, you can use `@info` somewhere in your code to see the value of a variable while your code runs:
14
+
15
+
```julia
16
+
begin
17
+
result = 0
18
+
19
+
for i in 1:5
20
+
x = i^2
21
+
@info("Current value", x)
22
+
result += x
23
+
end
24
+
result
25
+
end
26
+
```
27
+
28
+
<img alt="Screenshot of the log messages from the previous code example." src="$(root_url)/assets/img/log simple.png" width="1040" height="730" style="max-width: 500px;">
29
+
30
+
31
+
You can give `@info` as many arguments as you want. The first argument is a message, and the other arguments are key-value pairs that will be shown in the logs. For example, we can add `i` to the log.
32
+
33
+
34
+
<img alt="Screenshot of the log messages with 'i' added." src="$(root_url)/assets/img/log simple i.png" width="1040" height="822" style="max-width: 500px;">
Each log message can have a _level_ or _severity_. This makes it easy to distinguish between different types of log messages. To change the log level, you can use the corresponding macro: `@debug`, `@warn` or `@error` instead of `@info`.
38
+
39
+
40
+
<img alt="Screenshot of different log levels displayed in different colors." src="$(root_url)/assets/img/log levels.png" width="1040" height="1106" style="max-width: 500px;">
41
+
42
+
`@debug` is useful when sharing your work as a package. `@debug` logs will only display in your notebook, but not when someone else imports your code/package.
13
43
14
44
15
45
<!--
@@ -21,18 +51,43 @@ A simple way to disable all logs for a notebook is to change the global logger o
21
51
22
52
-->
23
53
24
-
### Disabling logs for a cell
54
+
## Special log arguments
55
+
Pluto will use its rich object inspector to display the arguments of log messages. This means that you can log complex objects like `Dict`s, `DataFrame`s, or even `plot`s, and they will be displayed in a nice way in the logs.
56
+
57
+
Here is an example of logging a `Vector`, and an `Exception`:
58
+
59
+
<img alt="Screenshot of a log message containing a Vector and an Exception." src="$(root_url)/assets/img/log arguments inspector.png" width="1040" height="1106" style="max-width: 500px;">
60
+
61
+
62
+
## Hiding logs for a cell
25
63
26
64
If a package logs warnings or info messages that you want to hide (especially in the static export of the notebook), then the option to hide logs can be toggled by clicking on the cell menu (the three dots on the right).
<img alt="Screenshot of button to hide logs." src="$(root_url)/assets/img/log hiding.png" width="1040" height="352" style="max-width: 500px;">
29
67
30
-
### Logging progress
68
+
To filter logs more specifically, you can use a package like [LoggingExtras.jl](https://github.com/JuliaLogging/LoggingExtras.jl).
69
+
70
+
71
+
## Logging progress
31
72
32
73
Pluto supports an integration with the [ProgressLogging.jl](https://github.com/JuliaLogging/ProgressLogging.jl) package which can be used to display a progress bar in the log message area:
33
74
34
75
<img alt="Screen recording of a Progress log going from 0% to 100%." src="$(root_url)/assets/img/progress log demo.gif" width="826" height="572" style="max-width: 400px;">
35
76
36
77
## Writing to standard output
78
+
You can also use Julia functions like `println`, `display`, `@show` or `show`, which will write information to the **standard output stream**. This is the "old" way of logging information, but it is still supported in Pluto in case you need it.
We recommend using Logging instead of `println`. There are many advantages of using Logging instead of writing to standard output:
86
+
- Logging works when writing multi-threaded code. `println` will mix different threads' output together, making it unreadable.
87
+
- Logging allows for more structured information (from the 2nd argument onwards). For example, you can log a `Dict` and inspect it in Pluto. You can even log `plot(data)` and see the plot!
88
+
- Logging can be easily filtered/disabled by the caller of a function. This is useful when writing packages. It can improve the experience and performance of your package.
89
+
90
+
### Disable capturing of standard output
91
+
By default, Pluto captures the standard output stream and shows it in the notebook. To disable this, and show it inside the terminal instead, the `capture_stdout=false` option can be provided to `Pluto.run` when launching Pluto. Learn more about [configuring Pluto](../configuration/).
92
+
37
93
38
-
To disable capturing and showing standard output inside Pluto and show it inside the terminal instead the `capture_stdout=false` option can be provided to `Pluto.run` when launching Pluto.
0 commit comments