From dae889d87beee28a7a6d5ef1304aa0aa16935bc5 Mon Sep 17 00:00:00 2001 From: xiang17 Date: Tue, 25 Jan 2022 15:09:19 -0800 Subject: [PATCH] Update Self-Diagnostics troubleshooting readme (#2810) --- src/OpenTelemetry/README.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/src/OpenTelemetry/README.md b/src/OpenTelemetry/README.md index 03d8b75da02..57eacf89671 100644 --- a/src/OpenTelemetry/README.md +++ b/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