EmpowerID Trace Context Documentation

Overview

The EmpowerIDTraceContext class is a logging utility designed to enhance log entries with contextual information about the execution process. It provides developers with the ability to dynamically enrich logs by associating them with specific processes, instances, and source contexts.

This functionality is essential for maintaining robust diagnostics and improving traceability across complex distributed systems.

---

Class Definition

Namespace

TheDotNetFactory.Framework.Diagnostics

Properties

Property	Type	Description
Current	AsyncLocal<EmpowerIDTraceContext>	Holds the current trace context instance.
Process	string	The name of the current process.
SourceContext	string	The name of the source context (e.g., class or module).
InstanceID_1	string	Identifier for the first instance.
InstanceID_1_Name	string	Name associated with the first instance ID.
InstanceID_2	string	Identifier for the second instance.
InstanceID_2_Name	string	Name associated with the second instance ID.
InstanceID_3	string	Identifier for the third instance.
InstanceID_3_Name	string	Name associated with the third instance ID.

---

Methods

SetContext

public static void SetContext(
    string process,
    string instanceID_1 = null,
    string instanceID_1_Name = "instanceID_1",
    string instanceID_2 = null,
    string instanceID_2_Name = "instanceID_2",
    string instanceID_3 = null,
    string instanceID_3_Name = "instanceID_3")

• Description: Sets the context for logging, associating the log entry with the provided process and instance identifiers.
• Parameters:
  • process: Name of the process.
  • instanceID_1: Optional identifier for the first instance.
  • instanceID_1_Name: Optional name for the first instance ID (default: "instanceID_1").
  • instanceID_2: Optional identifier for the second instance.
  • instanceID_2_Name: Optional name for the second instance ID (default: "instanceID_2").
  • instanceID_3: Optional identifier for the third instance.
  • instanceID_3_Name: Optional name for the third instance ID (default: "instanceID_3").

SetContext<T>

public static void SetContext<T>(
    string process,
    string instanceID1 = null,
    string instanceID1Name = "instanceID_1",
    string instanceID2 = null,
    string instanceID2Name = "instanceID_2",
    string instanceID3 = null,
    string instanceID3Name = "instanceID_3")

• Description: Sets the context for logging and automatically associates the log entry with the type of the calling class.
• Parameters:
  • Same as SetContext.
  • Additionally sets SourceContext to typeof(T).FullName.

WriteJson

void writeJsonMsg(Action<JsonWriter> additionalWriter)

• Description: Writes a log message in JSON format, including contextual information from the EmpowerIDTraceContext.
• Parameters:
  • additionalWriter: An action to write additional fields to the JSON log entry.
• Usage: This method is used internally to format log entries with process, instance, and timestamp information, enriched by the current trace context.
• Log Fields Added:
  • eidProcess: Process name from the current trace context.
  • SourceContext: Source context (if available).
  • InstanceID_1, InstanceID_2, InstanceID_3: Instance identifiers (if available).
  • processTime: UTC timestamp when the log was generated.
  • pid: Process ID.
  • processName: Name of the running process.

---

Usage Examples

Basic Context Setting

EmpowerIDTraceContext.SetContext(this.GetType().Name);

Log Output:

{"eidProcess":"HomeController","processTime":"2024-12-20T17:17:15.9155758Z","pid":14684,"processName":"w3wp","source":"The Dot Net Factory","eventType":"Information","id":2169,"data":"ValidateAccountWithPersonPassword: Account LogonName demo3login *(...)"}

Context Setting with Generic Type

EmpowerIDTraceContext.SetContext<ResourceSystem>(
    nameof(RunInventory),
    resourceSystem.ResourceSystemID.ToString(), nameof(resourceSystem.ResourceSystemID),
    resourceSystem.AccountStoreID.ToString(), nameof(resourceSystem.AccountStoreID));

Log Output:

{"eidProcess":"ADDOMAINDEMO3","SourceContext":"TheDotNetFactory.Framework.ResourceSystem","ResourceSystemID":"24","AccountStoreID":"4","ServerName":"UNAQVI-01.thedotnetfactory.internal","processTime":"2024-12-12T17:45:48.0238902Z","pid":18904,"processName":"EmpowerIDWorkerRoleService_WorkerProcess","source":"The Dot Net Factory","eventType":"Verbose","id":100,"data":"SECUREPROXY (...)"}

Advanced Context Setting

EmpowerIDTraceContext.SetContext<RBACUtility>(
    nameof(RunRbacSecurityPersonOrgRoleOrgZoneCompiler),
    currentJob.FriendlyName, "JobName",
    ServerName, nameof(ServerName));

Log Output:

{"eidProcess":"ADDOMAINDEMO3","SourceContext":"TheDotNetFactory.Framework.RBACUtility","JobName":"RBACUtility","ServerName":"UNAQVI-01.thedotnetfactory.internal","processTime":"2024-12-12T17:45:48.0238902Z","pid":18904,"processName":"EmpowerIDWorkerRoleService_WorkerProcess","source":"The Dot Net Factory","eventType":"Verbose","id":100,"data":"SECUREPROXY (...)"}

---

Release Notes

Version 1.0.0

• Initial Release:
  • Introduced EmpowerIDTraceContext class for enhanced logging context.
  • Added support for basic and generic-type context setting.
  • Provided flexibility to associate logs with multiple instance identifiers.
• Logging Enhancements:
  • Enriched log entries with process and instance-specific metadata.
  • Simplified diagnostics with SourceContext auto-population via generic types.
• WriteJson Method:
  • Integrated writeJsonMsg to support structured logging in JSON format.