Document silent drops and where the log callback runs

README.md

@@ -121,6 +121,15 @@ client never generates one, never writes one, and sends nothing.
 
 Each request has a 5 s timeout.
 
+The `log` callback runs on whichever thread hit the problem: the caller's for
+a report dropped in `Report` and for an installation ID file that fails in the
+constructor, and the client's background thread for a failed delivery and for
+the count of reports `Close()` gave up on. Keep it quick and thread-safe, and
+do not touch main-thread-only APIs from it, such as a Unity object. A slow
+callback holds up `Report` on the path that logs. Messages for a failed delivery
+include the report's JSON body, which holds its tags and any installation ID;
+the client does not write the key into any message.
+
 ## Turning it off
 
 Reporting is **opt-out**, and the person running the program always has the
@@ -164,10 +173,12 @@ distribution.
 {"application":"my-game","name":"level-complete","value":42,"tags":{"version":"1.4.0","install":"0f8b6c1e-3a52-4c8e-9a0d-6e2f1b7c4d90"}}
 ```
 
-`value` is omitted when not given, and `tags` always holds at least
+`value` is omitted when not given, and when it is NaN or infinite (JSON has no
+such numbers; the event is still sent), and `tags` always holds at least
 `version`, plus `install` when the program gave the client an
 [installation ID](#every-event-carries-a-random-installation-id). `value` is written with the invariant culture, so a German locale
-still sends `2.5`. The server assigns
+still sends `2.5`. An event with a null or blank `name` is not sent at all, and
+nothing is logged for it. The server assigns
 the timestamp. A `201` is success; anything else is logged and dropped.
 
 **Keep the application name ASCII.** It goes into the `User-Agent` header as

src/TraceClient/TraceClient.cs

@@ -139,7 +139,9 @@ public sealed class TraceClient : IDisposable
         /// on every event unless the event carries its own.</param>
         /// <param name="key">The program's write key. Without one the client is a no-op.</param>
         /// <param name="enabled">The program's own opt-out. <c>false</c> yields a client that reports nothing.</param>
-        /// <param name="log">Where dropped reports are mentioned. Optional; treat as debug-level.</param>
+        /// <param name="log">Where dropped reports are mentioned. Optional; treat as debug-level.
+        /// Called on the caller's thread or on the client's background thread, so it must be
+        /// quick and thread-safe. A failed delivery's message includes the report's JSON body.</param>
         /// <param name="installId">The installation's ID, sent as the tag <c>install</c> on every
         /// event. It should be random -- e.g. a <see cref="Guid.NewGuid"/> the program stores in its
         /// own settings -- and never derived from a person, account or address. Trimmed; <c>null</c>
@@ -376,7 +378,9 @@ private static bool IsYes(string value)
         /// would pass <see cref="MaxTags"/>; <paramref name="tags"/> itself is
         /// never modified. A report the server would reject for its size -- more than
         /// <see cref="MaxTags"/> tags, or a string longer than <see cref="MaxLength"/> --
-        /// is dropped here instead of being sent.
+        /// is dropped here instead of being sent. A null or blank <paramref name="name"/>
+        /// sends nothing and logs nothing. A NaN or infinite <paramref name="value"/> is
+        /// left out of the event, which is still sent.
         /// </summary>
         public void Report(string name, double? value = null, IEnumerable<KeyValuePair<string, string>> tags = null)
         {