Skip to content

Commit 4b341f2

Browse files
committed
docs(logging): move the logging description from README to the docs
1 parent 5cc3fb7 commit 4b341f2

2 files changed

Lines changed: 47 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -41,46 +41,10 @@ OpenSemanticLab data model.
4141

4242
## Logging
4343

44-
osw reports what it is doing through the standard `logging` module, on the
45-
`osw` logger, at INFO by default:
46-
47-
```python
48-
import osw
49-
50-
osw.set_log_level("WARNING") # see less
51-
osw.set_log_level("DEBUG") # see more
52-
osw.disable_logging() # detach the handler osw attached
53-
```
54-
55-
Set `OSW_LOG_LEVEL` to a level name, a level number, or `OFF` to choose the
56-
level before the package is imported. `OFF` silences osw everywhere, including
57-
in your own handlers.
58-
59-
### Collecting osw's records in your application
60-
61-
Configure logging the way you normally would and osw's records arrive there,
62-
once:
63-
64-
```python
65-
import logging
66-
import osw
67-
68-
logging.basicConfig(level=logging.INFO, filename="app.log")
69-
```
70-
71-
The `osw` logger propagates at all times, so the records reach your handlers
72-
whatever else happens. osw's own handler notices that something above it is
73-
listening, detaches itself so nothing is written twice, and gives back the
74-
level it had picked, so your level applies from then on. It makes no difference
75-
whether you configure logging before or after importing osw.
76-
77-
A level you asked for is kept across that hand-over, so `set_log_level("DEBUG")`
78-
or `OSW_LOG_LEVEL=DEBUG` is how you pull osw's debug records into an aggregated
79-
setup while the rest of your application stays quieter.
80-
81-
One case osw cannot detect is a handler added to the `osw` logger itself, since
82-
that is indistinguishable from one of its own. Call `disable_logging()` first if
83-
you do that.
44+
osw reports what it is doing on the `osw` logger at INFO by default. Levels,
45+
the `OSW_LOG_LEVEL` environment variable and how to collect the records in your
46+
own logging setup are described in the
47+
[Get Started guide](https://opensemanticlab.github.io/osw-python/get-started/#logging).
8448

8549
## Contributing
8650

‎docs/get-started.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,49 @@ Credentials are resolved from the environment variables `OSW_USERNAME` /
6464
credentials file, or via an interactive prompt - and are held in memory
6565
only, never written to disk; see [Authentication](api/auth.md).
6666

67+
## Logging
68+
69+
osw reports what it is doing through the standard `logging` module, on the
70+
`osw` logger, at INFO by default:
71+
72+
```python
73+
import osw
74+
75+
osw.set_log_level("WARNING") # see less
76+
osw.set_log_level("DEBUG") # see more
77+
osw.disable_logging() # detach the handler osw attached
78+
```
79+
80+
Set `OSW_LOG_LEVEL` to a level name, a level number, or `OFF` to choose the
81+
level before the package is imported. `OFF` silences osw everywhere, including
82+
in your own handlers.
83+
84+
### Collecting osw's records in your application
85+
86+
Configure logging the way you normally would and osw's records arrive there,
87+
once:
88+
89+
```python
90+
import logging
91+
import osw
92+
93+
logging.basicConfig(level=logging.INFO, filename="app.log")
94+
```
95+
96+
The `osw` logger propagates at all times, so the records reach your handlers
97+
whatever else happens. osw's own handler notices that something above it is
98+
listening, detaches itself so nothing is written twice, and gives back the
99+
level it had picked, so your level applies from then on. It makes no difference
100+
whether you configure logging before or after importing osw.
101+
102+
A level you asked for is kept across that hand-over, so `set_log_level("DEBUG")`
103+
or `OSW_LOG_LEVEL=DEBUG` is how you pull osw's debug records into an aggregated
104+
setup while the rest of your application stays quieter.
105+
106+
One case osw cannot detect is a handler added to the `osw` logger itself, since
107+
that is indistinguishable from one of its own. Call `disable_logging()` first if
108+
you do that.
109+
67110
## Examples and tutorials
68111

69112
- Runnable scripts in

0 commit comments

Comments
 (0)