JosiahWI commented on code in PR #13262:
URL: https://github.com/apache/trafficserver/pull/13262#discussion_r3408462725
##########
include/tscore/DiagsTypes.h:
##########
@@ -220,26 +577,295 @@ class Diags : public DebugInterface
va_end(ap);
}
+ /**
+ * @brief va_list form of error().
+ *
+ * @param[in] level DiagsLevel for routing and terminal handling.
+ * @param[in] loc Source location, or nullptr.
+ * @param[in] fmt Non-null printf-format string.
+ * @param[in] ap Initialized va_list. Consumed; caller MUST NOT reuse
+ * without va_end + va_start.
+ * @pre fmt is non-null; ap is initialized.
+ * @post Message emitted to all sinks enabled for level. For terminal
+ * levels (DL_Fatal and above), invokes cleanup_func (if set) and then
+ * terminates the process; does not return.
+ * @par Errors
+ * None signaled; I/O errors absorbed.
+ * @par Thread safety
+ * Safe to call concurrently from any thread.
+ */
virtual void error_va(DiagsLevel level, const SourceLocation *loc, const
char *fmt, va_list ap) const;
+ /**
+ * @brief Print the current Diags configuration to fp.
+ *
+ * @param[in] fp Destination FILE *; defaults to stdout.
+ * @pre fp is a valid open stream.
+ * @post Configuration summary written to fp.
+ * @par Errors
+ * I/O errors on fp are not signaled.
+ * @par Thread safety
+ * Not thread-safe. Reads config fields (enable state,
+ * outputs, base_debug_tags, base_action_tags) without holding
+ * tag_table_lock. Concurrent reconfiguration may produce
+ * interleaved or inconsistent output.
+ */
void dump(FILE *fp = stdout) const;
+ /**
+ * @brief Enable tags matching the given PCRE2 pattern for the given mode.
+ *
+ * @param[in] taglist PCRE2 regex string, or nullptr. If nullptr, the stored
+ * pattern is unchanged.
+ * @param[in] mode DiagsTagType_Debug or DiagsTagType_Action.
+ * @pre None (null taglist and invalid PCRE2 patterns are both safe; see
+ * @post for the invalid-pattern case). The regex engine is PCRE2, not
+ * POSIX ERE.
+ * @post If taglist is non-null, the new pattern unconditionally replaces the
+ * previous one; if the pattern fails to compile, the stored pattern
becomes
+ * empty and no tags will match until a valid pattern is installed.
+ * For DiagsTagType_Debug, if this is the process-global Diags instance,
+ * DbgCtl::update() is called to resync all registered debug controls
+ * against the current pattern — this occurs regardless of whether taglist
+ * is null.
+ * @par Errors
+ * Compile failures are not signaled to the caller; the stored pattern
+ * becomes empty rather than retaining the previous one.
+ * @par Thread safety
+ * Acquires tag_table_lock. Safe to call concurrently with
+ * emission, but serialized with other reconfiguration methods.
+ */
void activate_taglist(const char *taglist, DiagsTagType mode =
DiagsTagType_Debug);
+ /**
+ * @brief Disable all tags for the given mode.
+ *
+ * @param[in] mode DiagsTagType_Debug or DiagsTagType_Action.
+ * @pre None.
+ * @post No tag matches for mode; activated_tags[mode] is null.
+ * @par Errors
+ * None.
+ * @par Thread safety
+ * Acquires tag_table_lock. Safe to call concurrently with
+ * emission, but serialized with other reconfiguration methods.
+ */
void deactivate_all(DiagsTagType mode = DiagsTagType_Debug);
+ /**
+ * @brief Open the given BaseLogFile for use as a diagnostic log destination.
+ *
+ * Does NOT assign diags_log; the caller is responsible for that assignment
+ * on success. On failure, blf is deleted before returning.
+ *
+ * @param[in] blf Pointer to a constructed but not-yet-opened BaseLogFile,
+ * or nullptr (null is a no-op that returns true). When non-null, ownership
+ * transfers unconditionally: on success the caller must assign blf to
+ * diags_log; on failure blf has been deleted.
+ * @return True if blf was opened successfully (or blf is nullptr); false if
+ * the open failed (blf is deleted before returning false).
+ * @pre blf is null or points to a BaseLogFile that has not yet been opened.
+ * @post On true return: blf (if non-null) is open; caller must assign it to
+ * diags_log. On false return: blf has been deleted; diags_log is
unchanged.
+ * @par Errors
+ * Open failures cause a false return. A log_log_error diagnostic at
+ * LL_Error is emitted only when BASELOGFILE_DEBUG_MODE is enabled
+ * (off by default).
+ * @par Thread safety
+ * Caller MUST serialize with all other reconfiguration
+ * methods. reseat_diagslog() acquires tag_table_lock only for the
+ * pointer swap that follows this call; setup_diagslog() itself is not
+ * called under the lock. Direct callers must provide equivalent
+ * serialization for the pointer swap.
+ */
bool setup_diagslog(BaseLogFile *blf);
+
+ /**
+ * @brief Configure the rolling policy for diags.log.
+ *
+ * @param[in] re Rolling policy (see RollingEnabledValues). NO_ROLLING
+ * disables rolling.
+ * @param[in] ri Rolling interval in seconds, consulted under time-based
+ * policies. A value of -1 disables the time-based threshold.
+ * @param[in] rs Rolling size threshold in megabytes, consulted under
+ * size-based policies. A value of -1 disables the size-based threshold.
+ * @pre None.
+ * @post The three rolling policy fields are overwritten with the supplied
+ * values. No other state is modified.
+ * @par Errors
+ * None. Inputs are stored verbatim without validation.
+ * @par Thread safety
+ * No lock is acquired. The caller must ensure no concurrent
+ * calls to should_roll_diagslog() occur during reconfiguration.
+ */
void config_roll_diagslog(RollingEnabledValues re, int ri, int rs);
+
+ /**
+ * @brief Configure the rolling policy for the output log (traffic.out).
+ *
+ * @param[in] re Rolling policy (see RollingEnabledValues). NO_ROLLING
+ * disables rolling.
+ * @param[in] ri Rolling interval in seconds, consulted under time-based
+ * policies. A value of -1 disables the time-based threshold.
+ * @param[in] rs Rolling size threshold in megabytes, consulted under
+ * size-based policies. A value of -1 disables the size-based threshold.
+ * @pre None.
+ * @post The three rolling policy fields are overwritten with the supplied
+ * values. No other state is modified.
+ * @par Errors
+ * None. Inputs are stored verbatim without validation.
+ * @par Thread safety
+ * No lock is acquired. The caller must ensure no concurrent
+ * calls to should_roll_outputlog() occur during reconfiguration.
+ */
void config_roll_outputlog(RollingEnabledValues re, int ri, int rs);
+
+ /**
+ * @brief Close the current diags.log and reopen it at the configured path.
+ *
+ * Intended for use after an external log rotation tool has renamed or
+ * removed the active diags.log. The implementation:
+ * 1. Flushes the current file's buffered output.
+ * 2. Captures the configured filename from the active BaseLogFile.
+ * 3. Constructs a new BaseLogFile at that filename. The filename is
+ * passed to the OS verbatim — symlinks are re-resolved at each call.
+ * 4. On success: atomically swaps the new file into place under
+ * tag_table_lock and destroys the previous BaseLogFile (closing its
+ * FILE *).
+ * 5. On failure: leaves the previous file in place.
+ *
+ * @return False if diags_log is null or not yet initialized (safe no-op).
+ * True in all other cases, including when the internal reopen fails —
+ * reopen failures are not reflected in the return value.
+ * @pre A Diags instance is active and diags_log is initialized
+ * (is_init() == true). If this precondition is not met, returns false
+ * without performing a reopen — this is the safe no-op path for calls
+ * that arrive before the diagnostics subsystem is initialized.
+ * @post On success: diags_log is a fresh BaseLogFile at the configured
+ * path; the previous BaseLogFile (and its FILE *) is destroyed; all
+ * subsequent emission goes to the new file.
+ * On failure: diags_log is unchanged; the newly allocated BaseLogFile
+ * is deleted before it returns.
+ * @par Errors
+ * Open failures are not signaled via the return value. They are reported
+ * at LL_Error only when BASELOGFILE_DEBUG_MODE is enabled (off by
+ * default); in normal builds the failure is completely silent.
+ * @par Thread safety
+ * The swap in step 4 is performed under tag_table_lock.
+ * Concurrent emission either observes the pre-swap or post-swap log;
+ * no message is lost or written to a destroyed FILE *.
+ * @note When diagnostic output is disabled or redirected to a non-file
+ * sink (e.g., syslog), diags_log is null or uninitialized and the
+ * initialization guard causes an early false return.
+ */
bool reseat_diagslog();
+
+ /**
+ * @brief Roll diags.log if the current rolling policy condition is met.
+ *
+ * Under a size-based policy, the current file's size is compared to the
+ * configured threshold. Under a time-based policy, the elapsed time since
+ * the last roll is compared to the configured interval. Combined policies
+ * evaluate both conditions independently. When a condition is met the
+ * current file is flushed, renamed, and a fresh file is opened at the same
+ * path.
+ *
+ * @return True if the underlying file was renamed; false otherwise. True is
+ * returned even when reopening the fresh file at the original path fails.
+ * @pre None. A null or uninitialized diags_log is a safe no-op that
+ * returns false.
+ * @post On a successful roll the file at the configured path is a fresh,
+ * empty file and emission is directed to it. If renaming succeeded but
+ * reopening did not, the configured path is left absent and emission
+ * continues to the renamed file. With no roll, all state is unchanged.
+ * @par Errors
+ * None signaled. fstat (size-based policy only) and reopen failures
+ * silently suppress replacement; a completed rename is never reversed.
+ * @par Thread safety
+ * tag_table_lock is acquired only during the BaseLogFile
+ * pointer swap. The rolling-condition checks and file operations execute
+ * without a lock; the caller must ensure no concurrent reconfiguration
+ * (see config_roll_diagslog()).
+ */
bool should_roll_diagslog();
+
+ /**
+ * @brief Roll the standard-output redirection file if the current rolling
+ * policy condition is met.
+ *
+ * Under a size-based policy, the current file's size is compared to the
+ * configured threshold. Under a time-based policy, the elapsed time since
+ * the last roll is compared to the configured interval. Combined policies
+ * evaluate both conditions independently. When a condition is met both
+ * stdout_log and stderr_log are flushed, the underlying file is renamed,
+ * and a fresh file is opened at the same path; the process's stdout (and
+ * stderr, when redirected to the same path) are rebound to the new file.
+ * The time-based path also advances the last-roll timestamp.
+ *
+ * @return True if the underlying file was renamed; false otherwise. True is
+ * returned even when reopening the fresh file at the original path fails.
+ * @pre stdout_log and stderr_log are non-null. When a roll occurs,
+ * stdout_log and stderr_log must refer to the same filesystem path. Both
+ * conditions are checked with ink_assert(): violations abort in debug
+ * builds and are undefined behavior (typically a null-pointer crash) in
+ * release builds.
+ * @post On a successful roll the file at the configured path is a fresh,
+ * empty file and the process's stdout and stderr (when sharing the path)
+ * are bound to it. If renaming succeeded but reopening did not, stdout_log
+ * (and stderr_log when sharing the path) are set to null and the
configured
+ * path is left absent; the standard-stream descriptors retain their prior
+ * binding to the renamed file. With no roll, all state is unchanged. An
+ * uninitialized stdout_log returns false without inspecting policy.
+ * @par Errors
+ * None signaled via the return value. fstat (size-based policy only),
+ * rename, and reopen failures are reported at LL_Error only when
+ * BASELOGFILE_DEBUG_MODE is enabled (off by default); in normal builds
+ * they are silent. An fstat failure short-circuits the function and skips
+ * any time-based check.
+ * @par Thread safety
+ * tag_table_lock is acquired only during the BaseLogFile pointer swap and
+ * the dup2() rebinding of the standard stream. The rolling-condition
+ * checks and file operations execute without a lock; the caller must
+ * ensure no concurrent reconfiguration (see config_roll_outputlog()).
+ */
bool should_roll_outputlog();
+ /**
+ * @brief Reseat the named standard stream to a file at the given path.
+ *
+ * @param[in] stream STDOUT or STDERR (see StdStream).
+ * @param[in] file Non-null filesystem path. Symlinks are re-resolved at
+ * each call. An empty string causes an immediate false return without
+ * modifying any state.
+ * @return True on success; false if file is empty, the file could not be
+ * opened, or the resulting FILE * is null.
+ * @pre file must not be null.
+ * @post On success: the new file is open and bound as the named stream;
+ * the previous BaseLogFile is deleted.
+ * On file-open failure: the stream pointer is set to nullptr and the
+ * previous BaseLogFile is not freed.
+ * On empty-string return: no state is modified.
Review Comment:
Out of scope
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
