---
title: Evaluate trace request
summary: Evaluate the obsolete trace gates, assemble trace metadata, and discard it through the no-op sink.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-07-30
library: SAIF.Framework.Logging
reference_type: package
operation_id: LOG-OP-004
trigger: Caller invokes clsLogTrace.MethodBegin(...), MethodEnd(...), or MethodMessage(...)
---

# 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](../business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert)).
   - `IsEnabled` returns the shared flag directly for web callers.
   - Non-web callers additionally treat the presence of `TRACEON` in `System.Environment.CommandLine` as an enablement signal.
   - `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/operations/principal-identity-initialization.md) (`SAIF.Framework.Security`).
2. When the gate evaluates to `False`, return immediately without gathering any trace data ([BR-002](../business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert)).
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](../business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller)).
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](../business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert)).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
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](../business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert)).
- Context-gathering failures inside `GetBasicTraceInfo()` are swallowed, so trace callers never receive an exception from metadata capture itself ([BR-005](../business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller)).
- `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.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

## Sources
- `SAIF.Framework.Logging/clsLogTrace.vb`
- `SAIF.Framework.Logging/TraceInfoStruct.vb`
- `SAIF.Framework.Logging/clsLogCommon.vb`
- `SAIF.Framework.Security/clsSecurityPrincipal.vb`