Skip to content

Commit 18c6f52

Browse files
acul71acul71
authored
Feat/issue 605 debug logging via env variable (#608)
* feat: Debug Logging via Environment Variable * refactor: deleted libp2p/utils.py * fix: double messages logging fix * doc: add logging info to getting_started.rst
1 parent 4a53fc3 commit 18c6f52

File tree

11 files changed

+655
-28
lines changed

11 files changed

+655
-28
lines changed

‎docs/getting_started.rst

Lines changed: 97 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -94,14 +94,106 @@ For Python, you can use the bootstrap list to connect to known peers:
9494
Debugging
9595
---------
9696

97-
When running libp2p you may want to see what things are happening behind the scenes. You can enable debug logging by setting the appropriate log level:
97+
When running libp2p you may want to see what things are happening behind the scenes. You can enable debug logging using the `LIBP2P_DEBUG` environment variable. This allows for fine-grained control over which modules log at which levels.
9898

99-
.. code:: python
99+
Basic Usage
100+
~~~~~~~~~~~
101+
102+
To enable debug logging for all modules:
103+
104+
.. code:: bash
105+
106+
# Method 1: Using export (persists for the shell session)
107+
# On Unix-like systems (Linux, macOS):
108+
export LIBP2P_DEBUG=DEBUG
109+
# On Windows (Command Prompt):
110+
set LIBP2P_DEBUG=DEBUG
111+
# On Windows (PowerShell):
112+
$env:LIBP2P_DEBUG="DEBUG"
113+
114+
# Method 2: Setting for a single command
115+
# On Unix-like systems:
116+
LIBP2P_DEBUG=DEBUG python your_script.py
117+
# On Windows (Command Prompt):
118+
set LIBP2P_DEBUG=DEBUG && python your_script.py
119+
# On Windows (PowerShell):
120+
$env:LIBP2P_DEBUG="DEBUG"; python your_script.py
121+
122+
# Method 3: Redirect logs to /dev/null to suppress console output
123+
# On Unix-like systems:
124+
LIBP2P_DEBUG=DEBUG python your_script.py 2>/dev/null
125+
# On Windows (Command Prompt):
126+
set LIBP2P_DEBUG=DEBUG && python your_script.py >nul 2>&1
127+
# On Windows (PowerShell):
128+
$env:LIBP2P_DEBUG="DEBUG"; python your_script.py *> $null
129+
130+
To enable debug logging for specific modules:
131+
132+
.. code:: bash
133+
134+
# Debug logging for identity module only
135+
# On Unix-like systems:
136+
export LIBP2P_DEBUG=identity.identify:DEBUG
137+
# On Windows (Command Prompt):
138+
set LIBP2P_DEBUG=identity.identify:DEBUG
139+
# On Windows (PowerShell):
140+
$env:LIBP2P_DEBUG="identity.identify:DEBUG"
141+
142+
# Multiple modules with different levels
143+
# On Unix-like systems:
144+
export LIBP2P_DEBUG=identity.identify:DEBUG,transport:INFO
145+
# On Windows (Command Prompt):
146+
set LIBP2P_DEBUG=identity.identify:DEBUG,transport:INFO
147+
# On Windows (PowerShell):
148+
$env:LIBP2P_DEBUG="identity.identify:DEBUG,transport:INFO"
149+
150+
Log Files
151+
~~~~~~~~~
152+
153+
By default, logs are written to a file in the system's temporary directory with a timestamp and unique identifier. The file path is printed to stderr when logging starts.
154+
155+
When no custom log file is specified:
156+
- Logs are written to both a default file and to stderr (console output)
157+
- The default file path is printed to stderr when logging starts
158+
159+
When a custom log file is specified:
160+
- Logs are written only to the specified file
161+
- No console output is generated
162+
163+
To specify a custom log file location:
164+
165+
.. code:: bash
166+
167+
# Method 1: Using export (persists for the shell session)
168+
# On Unix-like systems:
169+
export LIBP2P_DEBUG_FILE=/path/to/your/logfile.log
170+
# On Windows (Command Prompt):
171+
set LIBP2P_DEBUG_FILE=C:\path\to\your\logfile.log
172+
# On Windows (PowerShell):
173+
$env:LIBP2P_DEBUG_FILE="C:\path\to\your\logfile.log"
174+
175+
# Method 2: Setting for a single command
176+
# On Unix-like systems:
177+
LIBP2P_DEBUG=DEBUG LIBP2P_DEBUG_FILE=/path/to/your/logfile.log python your_script.py
178+
# On Windows (Command Prompt):
179+
set LIBP2P_DEBUG=DEBUG && set LIBP2P_DEBUG_FILE=C:\path\to\your\logfile.log && python your_script.py
180+
# On Windows (PowerShell):
181+
$env:LIBP2P_DEBUG="DEBUG"; $env:LIBP2P_DEBUG_FILE="C:\path\to\your\logfile.log"; python your_script.py
182+
183+
Log Format
184+
~~~~~~~~~~
185+
186+
Log messages follow this format:
187+
188+
.. code:: text
189+
190+
timestamp - module_name - level - message
191+
192+
Example output:
100193

101-
import logging
194+
.. code:: text
102195
103-
# Set debug level for libp2p
104-
logging.getLogger('libp2p').setLevel(logging.DEBUG)
196+
2024-01-01 12:00:00,123 - libp2p.identity.identify - DEBUG - Starting identify protocol
105197
106198
What's Next
107199
-----------

‎docs/libp2p.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Subpackages
1919
libp2p.stream_muxer
2020
libp2p.tools
2121
libp2p.transport
22+
libp2p.utils
2223

2324
Submodules
2425
----------

‎docs/libp2p.utils.rst

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
libp2p.utils package
2+
====================
3+
4+
Submodules
5+
----------
6+
7+
libp2p.utils.logging module
8+
---------------------------
9+
10+
.. automodule:: libp2p.utils.logging
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
libp2p.utils.varint module
16+
--------------------------
17+
18+
.. automodule:: libp2p.utils.varint
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
libp2p.utils.version module
24+
---------------------------
25+
26+
.. automodule:: libp2p.utils.version
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:

‎libp2p/__init__.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,12 @@
4747
from libp2p.transport.upgrader import (
4848
TransportUpgrader,
4949
)
50+
from libp2p.utils.logging import (
51+
setup_logging,
52+
)
53+
54+
# Initialize logging configuration
55+
setup_logging()
5056

5157

5258
def generate_new_rsa_identity() -> KeyPair:

‎libp2p/utils/__init__.py

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
"""Utility functions for libp2p."""
2+
3+
from libp2p.utils.varint import (
4+
decode_uvarint_from_stream,
5+
encode_delim,
6+
encode_uvarint,
7+
encode_varint_prefixed,
8+
read_delim,
9+
read_varint_prefixed_bytes,
10+
)
11+
from libp2p.utils.version import (
12+
get_agent_version,
13+
)
14+
15+
__all__ = [
16+
"decode_uvarint_from_stream",
17+
"encode_delim",
18+
"encode_uvarint",
19+
"encode_varint_prefixed",
20+
"get_agent_version",
21+
"read_delim",
22+
"read_varint_prefixed_bytes",
23+
]

0 commit comments

Comments
 (0)