Update Self-Diagnostics troubleshooting readme (#2810)

Author: xiang17

src/OpenTelemetry/README.md

@@ -329,8 +329,11 @@ this SDK also ships a "self-diagnostics feature", which helps troubleshooting.
 When enabled, internal events generated by OpenTelemetry will be written to a
 log file.
 
-The self-diagnostics feature can be enabled/disabled while the process
-is running.
+The self-diagnostics feature can be enabled/changed/disabled while the process
+is running. The SDK will attempt to read the configuration file every `10` seconds
+in non-exclusive read-only mode. The SDK will create or overwrite a file
+with new logs according to the configuration. This file will not exceed the
+configured max size and will be overwritten in a circular way.
 
 To enable self-diagnostics, go to the
 [current working directory](https://en.wikipedia.org/wiki/Working_directory) of
@@ -362,7 +365,10 @@ You can also find the exact directory by calling these methods from your code.
    can be an absolute path or a relative path to the current directory.
 
 2. `FileSize` is a positive integer, which specifies the log file size in
-   [KiB](https://en.wikipedia.org/wiki/Kibibyte).
+   [KiB](https://en.wikipedia.org/wiki/Kibibyte). This value must be between 1 MiB
+   and 128 MiB (inclusive), or it will be rounded to the closest upper or lower
+   limit. The log file will never exceed this configured size, and will be
+   overwritten in a circular way.
 
 3. `LogLevel` is the lowest level of the events to be captured. It has to be one
    of the
@@ -379,19 +385,19 @@ A `FileSize`-KiB log file named as `ExecutableName.ProcessId.log` (e.g.
 `foobar.exe.12345.log`) will be generated at the specified directory
 `LogDirectory`, into which logs are written to.
 
-The SDK will attempt to open the configuration file in non-exclusive read-only
-mode, read the file and parse it as the configuration file every 10 seconds. If
-the SDK fails to parse the `LogDirectory`, `FileSize` or `LogLevel` fields as
+If the SDK fails to parse the `LogDirectory`, `FileSize` or `LogLevel` fields as
 the specified format, the configuration file will be treated as invalid and no
-log file would be generated. Otherwise, it will create or overwrite the log file
-as described above.
-
-Note that the `FileSize` has to be between 1 MiB and 128 MiB (inclusive), or it
-will be rounded to the closest upper or lower limit. When the `LogDirectory` or
-`FileSize` is found to be changed, the SDK will create or overwrite a file with
-new logs according to the new configuration. The configuration file has to be no
-more than 4 KiB. In case the file is larger than 4 KiB, only the first 4 KiB of
-content will be read.
+log file would be generated.
+
+When the `LogDirectory` or `FileSize` is found to be changed, the SDK will create
+or overwrite a file with new logs according to the new configuration. The
+configuration file has to be no more than 4 KiB. In case the file is larger than
+4 KiB, only the first 4 KiB of content will be read.
+
+The log file might not be a proper text file format to achieve the goal of having
+minimal overhead and bounded resource usage: it may have trailing `NUL`s if log
+text is less than configured size; once write operation reaches the end, it will
+start from beginning and overwrite existing text.
 
 ## References