Wez Furlong
fe4b11b8d6
Summary: Adds a `warning` field to the response struct. If present, it conveys a warning that should be reported back to the user. We currently only set this warning state if a recrawl is triggered. The warning output links to new documentation about what a recrawl is and how to avoid it. We maintain a recrawl counter but don't expose this in a structured way to the client. Not sure how big a deal this really is; given @sid0's recent change to heal for non IN_Q_OVERFLOW conditions, this should only trigger when the inotify resources are not tuned properly and thus this should be pretty much a binary condition. Test Plan: `make integration`; tests that trigger recrawls assert that we set the warning info. The warning field looks like this: ``` Recrawled this watch 1 times, most recently because: /private/var/tmp/bwx0ydi87bscgkc0: debug-recrawl To resolve, please review the information on https://facebook.github.io/watchman/troubleshooting.html#recrawl ``` Reviewers: fsilva, sid0 Reviewed By: sid0 Subscribers: sid0, jimp, dreiss Differential Revision: https://phabricator.fb.com/D1488381
2.9 KiB
id, title, layout, category, permalink
| id | title | layout | category | permalink |
|---|---|---|---|---|
| socket-interface | Socket Interface | docs | Invocation | docs/socket-interface.html |
Most simple uses of Watchman will invoke the watchman binary and process its output. Sometimes it is desirable to avoid the overhead of an extra process and talk directly to your watchman service.
The watchman service runs as a single long-lived process per user. The watchman binary will take care of spawning the server process if necessary.
The server will create a unix domain socket for communication with its clients.
The location of the socket depends on compile time options and command line
flags. It is recommended that you invoke watchman get-sockname to discover
the location, or if you are being invoked via a trigger (since version 2.9.7)
you will find the location in the $WATCHMAN_SOCK environmental variable.
Watchman Protocol
The unix socket implements a request-response protocol with PDUs encoded in
either JSON or BSER representation. Some watchman commands (notably
subscribe and log-level) allow the watchman service to unilaterally send
any number of PDUs to the client, and require more stateful handling.
JSON encoding
The JSON encoding represents a request or a response as a single line of compact JSON encoded data. The newline is used to detect the end of the PDU.
Requests from the client are always represented as a JSON array.
Responses from the server are always represented as a JSON object.
Sending the since command is simply a matter of formatting it as JSON. Note
that the JSON text must be a single line (don't send a pretty printed version
of it!) and be followed by a newline \n character:
["since", "/path/to/src", "n:c_srcs", "*.c"] <NEWLINE>
BSER encoding
BSER is a local-only binary serialization format that can represent the same data types as JSON, but in a more compact form and not be limited to UTF-8 representation of strings.
When you make a request using BSER, the server will respond in BSER encoding.
You can read more about BSER in the BSER specification.
Reporting Errors and Warnings
If a Response includes a field named error it indicates that the request was
not successful. The error field, if present, is a string value that can be
presented to the user.
If a Response includes a field named warning it indicates that there is some
condition that should be reported back to the user so that the system can
operate more effectively. Tools should display this to the user as an
advisory. At the time of writing, this can be triggered due to overflowing the
system limits on file watching resources. These are important to address so
that events are not missed and thus so that correctness and system performance
are maintained.
The warning message contains a link to this documentation that provides advice on tuning and resolving the issue.