This topic describes the SOFA Tracer utility classes.
Virtual log context utility class
Tracer provides the DummyContextUtil class to manage the virtual log (dummy log) context.
When you create a virtual log context with DummyContextUtil, you must call the corresponding destroy method. We recommend that you place the call to the destroy method in a finally block.
Create a virtual log context
Definition: public static void createDummyLogContext() throws Exception
Description: Creates a virtual log context and sets it to the thread context. If a log context already exists in the current thread context, this method throws an exception.
Clear a virtual log context
Definition: public static void clearDummyLogContext() throws Exception
Description: Clears the current virtual log context. If the log context in the current thread context is not a DummyLogContext, this method throws an exception.
You can set the end-to-end stress testing marker by calling the clearDummyLogContext class, as shown in the following code:
DummyContextUtil.createDummyLogContext();
DummyContextUtil.addPenetrateAttribute(PenAttrKeyEnum.LOAD_TEST_MARK,"T");
DummyContextUtil.clearDummyLogContext();Tracer context utility class
The TracerContextUtil class provides a unified method to retrieve the traceId. It also provides APIs to retrieve and set pass-through data. You can use the class as follows:
Retrieve the TraceId from the current Tracer context
Example:
String traceId =TracerContextUtil.getTraceId();If the current Tracer context is empty, this method returns an empty string.
If the current Tracer context is not empty but the traceId is empty, this method returns an empty string.
If the current Tracer context is not empty and the traceId is not empty, this method returns the traceId.
Description
To retrieve a TraceId, a TracerContext must exist. A TracerContext is created in the following two scenarios: SOFA MVC system: A TracerContext is created at the entry point of each access. To activate the Tracer feature for MVC requests, set mvc_toolbox_plugin=ACTIVE in the sofa-config configuration file to activate the MVC plugin. SOFA CORE system: A TracerContext is created when a middleware component, such as a Remote Procedure Call (RPC), is first called.
Add a custom tag to a trace
For custom business scenarios, you can call the Tracer class in your business class to set custom tags and their values. The following code provides an example:
public void handlerXxx(Map<String,String> request){
SofaTraceContext ctx =SofaTraceContextHolder.getSofaTraceContext();
SofaTracerSpan span = ctx.getCurrentSpan();
// Explicitly depending on Tracer can be intrusive. Encapsulate it properly.
if(span !=null){
// Add the parameter to the custom tag: xxx_phone
span.setTag("xxx_phone", request.get("phone"));
}
// Process business logic
// ...
}For more information about custom tags, see Add custom business tags.
Set pass-through data
Example:
TracerContextUtil.putPenetrateAttribute("Hello","World");Description:
If the specified key or value is null, a TracerException is thrown.
If the current Tracer context is empty, a TracerException is thrown.
If you add pass-through data and the total data volume exceeds the maximum limit (currently 1024 characters), a TracerException is thrown.
Notes
The key for this interface is shared across the entire site. Ensure that the key does not conflict with other keys. Note that Tracer reserves the uid and mark fields as keys.
Obtain pass-through data from Tracer
Example:
TracerContextUtil.getPenetrateAttribute("Hello");If the current Tracer context is not empty and the pass-through data retrieved for the key is null, the method returns an empty string.
If the current Tracer context is not empty and the pass-through data retrieved for the key is not null, the method returns the pass-through data.
If the key is null, an exception is thrown.
If the current Tracer context is empty, an exception is thrown.
You can clone the Tracer log context of the current thread
If a business system uses its own thread pool to process tasks, developers may need to retrieve the current thread's Tracer log context and set it for a subthread. In versions of Tracer earlier than 1.0.15, developers used the API to directly retrieve the parent thread's Tracer context and set it for the subthread. This caused the parent and subthreads to share the same Tracer log context, which meant that modifications in one thread could affect the other.
Tracer 1.0.15 provides an API to clone the Tracer log context of the current thread. You can use this API to copy the context from a parent thread and set it in a subthread. This ensures that threads do not affect each other. The following code shows an example:
AbstractLogContext abstractLogContext =TracerContextUtil.cloneLogContext();If the current thread does not have a Tracer log context, this method returns null.
If the current thread has a Tracer log context, this method returns a clone of that context.
End-to-end utility class
The LoadTestUtil class provides a static method to determine if end-to-end stress testing is enabled.
public static boolean isLoadTestMode()
Description: Determines whether the current mode is end-to-end stress testing. This method returns true if, and only if, a log context can be retrieved from the current thread context and its stress testing mark is T.
When end-to-end stress testing is enabled, log files are written to the ${logging.path}/logs/tracelog/shadow/ directory. The pass-through data field in the log files also contains the mark=T identifier.