You can use the following methods to pass data to a SAS EventMessage object:

  • staticParam()

  • varParam() or varParams()

  • threadSafeParam()

Static parameters

The staticParam() method allows a 32-bit integer value in the EventMessage object to be sent to the SAS server. In the SAS mini-bundle, you can get the corresponding enum value and format SAS EventMessage details with meaningful information.

Whenever possible, use staticParam() instead of varParam(), as the size of the resulting EventMessage object is much smaller and therefore requires less memory, CPU usage, and network bandwidth. This is important because unlike most logging APIs that offer a log level hierarchy to modulate the log verbosity, SAS tracing sends every SAS event to the server regardless of the level specified in the SAS mini-bundle.

The cumulative effect of using varParam() calls in place of staticParam() calls can have a sizeable impact on system performance. Therefore, pack as much fixed data into the mini-bundle as is practical to minimize the amount of data to be sent to the server. Encoding data in an enum value and decoding it to text in the bundle helps ensure this and allows the application to scale efficiently.

Consider refactoring code to use staticParam() if:

  • The varParam() method is used to send a string from a finite set of strings (typically for debugging).

  • The varParam() method is used to format fixed strings with variable data.

    Either define these strings in full inside the mini-bundle or separate the constant text into the mini-bundle and divide the variable data into static parameters and variable-length parameters appropriately. If this becomes too complex, for example if you are passing differently formatted data at different locations in your code to a single event, consider using separate events.

The staticParam() method allows parameters to be passed in as int, Integer, or EnumParameter.

Variable-length parameters

If you cannot define the data being passed to SAS as an enum or the length of the data varies, use the varParam() or the varParams() method. These methods accept object parameters, allowing for flexibility in the data passed to the EventMessage. The varParams() method behaves similarly to varParam() but allows two or three objects to be passed in as parameters. You can achieve the same result by chaining multiple varParam() calls together.

The varParam() method handles parameters passed to it differently depending on their types:

  • null: Encodes as a zero-length byte array.

  • byte[]: Copies directly into the message.

  • java.nio.ByteBuffer: Unsupported. Coerces to a zero-length byte array. In this case, use threadSafeParam(byte[]) instead.

  • java.lang.String: Encodes as UTF-8 and copies into the message.

  • Any other type: Calls Object#toString() and then proceeds as for java.lang.String.

For the implementation of EncodeableParameter, the method calls EncodeableParameter#encode(ByteBuffer) and copies bytes written to stream into the message, while for the implementation of MarshalableParameter, the method calls MarshalableParameter#marshal() and copies the returned byte[] into the message.

Don’t use the varParam() method for parameters that implement EnumParameter. It will automatically add the parameter as a static parameter, with a debug message logged. Use the staticParam(EnumParameter) method for enum parameters instead.

Thread safety

Data passed as parameters is only copied or marshalled into the relevant EventMessage object when the report() method is invoked. Therefore, don’t modify the parameters passed to the EventMessage object before invoking the report() method.

Additionally, parameters passed using the threadSafeParam(byte[]) method will not be copied even after the report() method is invoked. This means that if a value you want to pass as a parameter may be subsequently modified, and you already have defensively copied it, you should use the threadSafeParam(byte[]) method to put the defensive copy in the event. This allows the SAS API to be more efficient, by not making its own defensive copy when the report() method is invoked.

Different from the above, the staticParam(), varParam(), and varParams() methods convert the following types of parameters when they are added:

  • null: Convert to an empty byte array.

  • ByteBuffer: Convert to an empty byte array.

  • EnumParameter: Convert to its integer value.

Check isEnabled() on the trail object before marshalling. The isEnabled() method returns a boolean value, which is true if SAS tracing is enabled on the SAS facility that the trail object was created from. By wrapping the code responsible for marshalling the object conditioned on the isEnabled() method, you can achieve further reduction in memory and CPU usage.

Previous page Next page