Skip to content

Evaluate trace request

This operation documents the library's deprecated trace pipeline. Its public entry points still evaluate enablement flags and build a fully populated TraceInfoStruct, but the private sink they ultimately call performs no write at all, so a successful trace request produces work without any observable output.

Field Value
Operation ID LOG-OP-004
Trigger Caller invokes clsLogTrace.MethodBegin(...), clsLogTrace.MethodEnd(...), or clsLogTrace.MethodMessage(...).
Inputs Optional state objects and, for MethodMessage(...), a message string.
Outputs No durable output.
Primary components clsLogTrace.IsEnabled, clsLogTrace.UserTraceEnabled, clsLogTrace.GetBasicTraceInfo, clsLogTrace.WriteMessage
Entry point SAIF.Framework.Logging/clsLogTrace.vb

Steps

  1. Evaluate the gate IsEnabled Or UserTraceEnabled before any trace metadata is allocated (BR-002).
  2. IsEnabled returns the shared flag directly for web callers.
  3. Non-web callers additionally treat the presence of TRACEON in System.Environment.CommandLine as an enablement signal.
  4. UserTraceEnabled succeeds only for web requests where clsSecurityPrincipal.Instance.IsAuthenticated is True and the configured TraceUser string contains the current username.

Origin: The current-user check in step 1.3 delegates to clsSecurityPrincipal, documented in Principal identity initialization (SAIF.Framework.Security). 2. When the gate evaluates to False, return immediately without gathering any trace data (BR-002). 3. Build a baseline TraceInfoStruct in GetBasicTraceInfo(). - Stamp TraceDate = Now and clear DataText. - For web calls, populate machine, application, page, and environment values from HttpContext, create clsSecurityPrincipal(Platform.Web), copy HttpContext.Session.SessionID into TraceID, and copy the username. - For non-web calls, populate application and environment data from Process.MainModule, set PageName = "WINFORMS", lazily create m_TraceID when it is still empty, and use clsSecurityPrincipal.CurrentThreadUser as the user name. - On failure: swallow the exception and return whatever fields were already populated (BR-005). 4. Identify the calling method through clsLogCommon.GetCallingMethodInfo(), set the class, assembly, and method names, rewrite .ctor to NEW, assign MethodPosition (BEGIN, END, or MESSAGE), and serialize any supplied message or data through GetStateInfo(...). 5. Call the private WriteMessage(...) method. It contains no sink logic whatsoever, so the operation completes without writing anything to a file or the SOAP endpoint, even though the trace gate has already passed (BR-002).

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Trace request]) --> Gate{IsEnabled or UserTraceEnabled?}
    Gate -->|No| EndSkip([Return without trace])
    Gate -->|Yes| Context[Build TraceInfoStruct]
    Context --> Caller[Resolve calling method]
    Caller --> NoOp[Call empty WriteMessage]
    NoOp --> EndOk([Return without output])

Failure and edge-case behavior

  • Non-web callers can still force the gate open by adding TRACEON to the process command line, but doing so has no visible effect because the sink remains a no-op (BR-002).
  • Context-gathering failures inside GetBasicTraceInfo() are swallowed, so trace callers never receive an exception from metadata capture itself (BR-005).
  • PageOutputEnabled remains a public property but is not consulted by any active write path in this library — it has no effect on the outcome of this operation.

Sources

  • SAIF.Framework.Logging/clsLogTrace.vb
  • SAIF.Framework.Logging/TraceInfoStruct.vb
  • SAIF.Framework.Logging/clsLogCommon.vb
  • SAIF.Framework.Security/clsSecurityPrincipal.vb