Skip to content

chore(users): update flags for logging #948

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
calmh merged 2 commits into from
Aug 8, 2025
Merged

chore(users): update flags for logging #948

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d63a3e7
chore(users): update flags for logging
calmh Aug 6, 2025
dcf2e50
wip
calmh Aug 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 1 addition & 7 deletions dev/debugging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,11 @@ quite silent about it. A number of environment variables can be used to
set the logging to verbose for various parts of the program, and to
enable profiling.

Enabling any of the STTRACE facilities will also change the log format to
include microsecond timestamps and file names plus line numbers. This
can be used to enable this extra information on the normal logging
level, without enabling any debugging: ``STTRACE=somethingnonexistent``
for example.

Under Unix (including Mac) the easiest way to run Syncthing with an
environment variable set is to prepend the variable to the command line.
I.e:

``$ STTRACE=model syncthing``
``$ STTRACE=model,syncthing``
Copy link
Member

@rasa rasa Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@calmh This is gonna set STTRACE to model,syncthing.
To run syncthing with STTRACE set to model, revert to

Suggested change
``$ STTRACE=model,syncthing``
``$ STTRACE=model syncthing``

Copy link
Member Author

@calmh calmh Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah my bad, I misread what this was doing to begin with (thought it was trying to set tracing for the model and syncthing packages, which is a thing...)

Copy link
Member Author

@calmh calmh Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a followup.


On windows, it needs to be set prior to running Syncthing.

Expand Down
96 changes: 33 additions & 63 deletions includes/env-vars.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,67 +1,37 @@
STTRACE
Used to increase the debugging verbosity in specific or all facilities,
generally mapping to a Go package. Enabling any of these also enables
microsecond timestamps, file names plus line numbers. Enter a
comma-separated string of facilities to trace. ``syncthing --help`` always
outputs an up-to-date list. The valid facility strings are:

Main and operational facilities:
config
Configuration loading and saving.
main
Main package.
model
The root hub; the largest chunk of the system. File pulling, index
transmission and requests for chunks.
scanner
File change detection and hashing.
versioner
File versioning.

Networking facilities:
beacon
Multicast and broadcast UDP discovery packets: Selected interfaces
and addresses.
connections
Connection handling.
dialer
Dialing connections.
discover
Remote device discovery requests, replies and registration of
devices.
nat
NAT discovery and port mapping.
pmp
NAT-PMP discovery and port mapping.
protocol
The BEP protocol.
relay
Relay interaction (``strelaysrv``).
upnp
UPnP discovery and port mapping.

Other facilities:
fs
Filesystem access.
events
Event generation and logging.
http
REST API.
sha256
SHA256 hashing package (this facility currently unused).
sqlite
The SQLite database
stats
Persistent device and folder statistics.
sync
Mutexes. Used for debugging race conditions and deadlocks.
upgrade
Binary upgrades.
walkfs
Filesystem access while walking.

all
All of the above.
Used to increase the debugging verbosity in specific facilities,
generally mapping to a Go package. Enter a comma-separated string of
facilities to trace: ``api,beacon``. Optionally, a log level can be
given per facility to specify something other than DEBUG:
``api:WARN,beacon:ERR``, potentially overriding a global ``--log-level``
adjustment.

The valid facility strings are listed below; additionally, ``syncthing
serve --help`` always outputs the most up-to-date list.

api - REST API
beacon - Multicast and broadcast discovery
config - Configuration loading and saving
connections - Connection handling
db/sqlite - SQLite database
dialer - Dialing connections
discover - Remote device discovery
events - Event generation and logging
fs - Filesystem access
main - Main package
model - The root hub
nat - NAT discovery and port mapping
pmp - NAT-PMP discovery and port mapping
protocol - The BEP protocol
relay/client - Relay client
scanner - File change detection and hashing
stun - STUN functionality
syncthing - Main run facility
upgrade - Binary upgrades
upnp - UPnP discovery and port mapping
ur - Usage reporting
versioner - File versioning
watchaggregator - Filesystem event watcher

STLOCKTHRESHOLD
Used for debugging internal deadlocks; sets debug sensitivity. Use only
Expand Down
24 changes: 7 additions & 17 deletions users/syncthing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Synopsis
[--db-maintenance-interval=<interval>]
[--db-delete-retention-interval=<interval>]
[--gui-address=<address>] [--gui-apikey=<key>]
[--logfile=<filename>] [--logflags=<flags>]
[--log-level=<level>] [--log-file=<filename>]
[--log-max-old-files=<num>] [--log-max-size=<num>]
[--no-browser] [--no-console]
[--no-port-probing] [--no-restart] [--no-upgrade]
Expand Down Expand Up @@ -149,25 +149,15 @@ Serve options

Override the API key needed to access the GUI / REST API.

.. cmdoption:: --logfile=<filename>
.. cmdoption:: --log-level=<level>

Set destination filename for logging (use ``"-"`` for stdout, which is the
default option).

.. cmdoption:: --logflags=<flags>
Set the log level for all packages. Valid levels are DEBUG, INFO, WARN,
and ERROR.

Select information in log line prefix. The ``--logflags`` value is a sum of
the following:
.. cmdoption:: --log-file=<filename>

- 1: Date
- 2: Time
- 4: Microsecond time
- 8: Long filename
- 16: Short filename

To prefix each log line with date and time, set ``--logflags=3`` (1 + 2 from
above). The value 0 is used to disable all of the above. The default is to
show time only (2).
Set destination filename for logging (use ``"-"`` for stdout, which is the
default option).

.. cmdoption:: --log-max-old-files=<num>

Expand Down