What is a Log Enhancer?
Log Enhancers are instrumentation instructions that allow the Contrast agent to log additional parameters and data in the application without requiring any source code changes. To use Log Enhancers Protect should be enabled for your environment.
How do Log Enhancers work?
Using deep security instrumentation techniques, a user can specify the API and parameter to log, and the Contrast agent adds this information to the security.log file as part of it's Protect logging.
We call the Java method toString, that every Java object has, to stringify the object. What that method outputs is dependent on whether the class in question has implemented the method. In some instances, the default behaviour of toString may not be overridden, which effectively means the fully qualified class name and the object’s memory address will be printed. It's recommended that you use an object that has overridden toString to ensure the output is meaningful and useful.
How can I configure a Log Enhancer?
More information on how to configure a Log Enhancer can be found in our documentation here:
Add or edit log enhancers
Take note of the following differences in the documented process in regards to the Format field:
- Each placeholder should be wrapped in double braces.
- {{Pn}} index begins at 1.
{{O}}: Print the stringified version of the Object on which this call is made. If the method is static, this may be null or empty.
{{Pn}}: Print the given parameter at index n. Note that n starts from 1.
{{P1}}: Print the the first parameter into the message.
{{R}}: Print the return value of the function.
Example Usage of a Log Enhancer
The following example uses a sample application Spring PetClinic - https://github.com/spring-projects/spring-petclinic .
We want to log the return value of the function used to find the Pet Owner by their last name, which is called when the "Find Owner" button is pressed:
Owner Information is returned based on the above search:
To log this information we need to identify the API function called to return the data:
https://github.com/spring-projects/spring-petclinic/blob/main/src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java
Having identified the findByLastName function, the Log Enhancer can now be configured in TeamServer:
Save the new Log Enhancer and restart your application.
Now when the above "Find Owner" search is performed in the application we will see the following output to the Contrast security log:
Aug 05 2020 10:08:45.546+0100 123.456.7.89 CEF:0|Contrast Security|Contrast Agent Java|3.7.6.16040|SECURITY|FindByLastName: [[Owner@600f4386 id \= 7, new \= false, lastName \= 'Black', firstName \= 'Jeff', address \= '1450 Oak Blvd.', city \= 'Monona', telephone \= '6085555387']]|INFO|lei=8684 src=0:0:0:0:0:0:0:1 spt=8082 request=/owners requestMethod=GET app=Spring PetClinic outcome=success