Working Modes
There are three working modes: online (with or without fallback), local and backup. These modes allow different use cases for different stages of the game development and cycle of life. Enabling any working mode creates a new trace processor for such purpose. In each processor, traces are handled independently and thus, failing traces in one mode do not interact with other modes.
To control the different Working modes, the Xasu tracker uses an architecture that uses the IProcessor interface to interact with them. All of the working modes implement this interface and also it is possible to implement new working modes using this interface. To use new processors, you will have to manually initialize them in the XasuTracker Init function.
The online mode sends batches of enqueued traces to an LRS using the POST /statements API. To send the traces its to support resiliency features such as Retry Pollicies, Circuit Breakers and Fallback modes. The default behaviour will retry any statement request that results in an http error except if it is included the list of handled codes below. For instance, the system will retry any 412/5xx response using an exponential backoff timing up to 5 times, after which the tracker will log the exception and the circuit will open. This circuit will try to close automatically after a period of 15 seconds.
The amount of traces in the batch is dynamic, normally starting with up to 256 traces. The size of the batch can be reduced when an HTTP Error happen if it belongs to the list of handled codes. Once one handled error happens the batch will decrease (by half) until it is accepted or a single trace gets rejected. Once the error is isolated, it is notified to the user. With each succesfull submission, the batch will duplicate in size until it reaches its maximum size again.
The following list of http errors are isolated by the tracker and returned to the user. These cases follow the xAPI-Communication specification, and could retrieve the following errors:
- Bad Request (Status 400): An APIException(400) is thrown when the trace doesn't follow the specification rules, resulting in the trace being rejected by the LRS.
- Conflict (409): An APIException(409) is thrown when the trace id is in conflict with another trace.
- Request Entity Too Large (412): An APIException(412) is thrown when the trace is too large and the LRS rejects it.
To enable the online processor you need to add the following lines to your tracker_config.json file:
"online": "true",
"batck_size": "256",
"lrs_endpoint": "<your-lrs-endpoint>"The online processor can use authorization protocols by adding the following lines. Note that using two different authorization protocols that use redirection is not yet supported in WebGL.
"authorization": "<authorization-name>", // Authorization
"authorization-parameters": { /* Authorization parameters */ }Check the authorization Wiki page to get more information about how to configure the authorization protocol.
The fallback mode is a special working mode for error-prone environments. If the fallback mode is enabled, it will store the traces locally while any circuit is open. Normally, circuits will open when the network fails or the server returns any unhandled status such as 5xx errors.
For the user, when the fallback mode is working the tracker will notify the user that the traces are being sent once they get written in the fallback file. In this fallback file traces are written one per line. This fallback file is located in:
%TEMP%/<Company-Name>/<Game Name>/fallback.log
When any circuit in the processor is closed and the connection is restored or the API is responsive, Xasu will try to send the traces in the fallback to the LRS. If any error happens while sending the fallback, the failing traces will be stored in a special file in the following path:
AppData/LocalLow/<Company-Name>/<Game Name>/failed_traces.log
To enable the fallback mode you need to use the following property in the configuration file along with the rest of the online mode properties:
"fallback": "true"The local mode saves traces in a permanent local file in the selected format. At the current version it is only possible to store the traces in xAPI format. However, the CSV format is one planned feature. Traces in the local mode are stored in the following file:
AppData/LocalLow/<Company-Name>/<Game Name>/traces.log
To enable the local mode and configure the output format include the following configuration lines:
"offline": "true",
"format": "XAPI"The backup mode saves the traces in a temporal local file location for later submission or recollection. When the Xasu tracker is finalized at the end of the game, this backup can optionally be send automatically to an endpoint.
To enable the backup mode include the following configuration lines:
"backup": "true",
"backup-format": "XAPI"To enable the uploading you have to add the following lines:
"backup-endpoint": "<your-backup-endpoint>"Optionally, the backup can use authorization protocols by adding the following lines. Note that using two different authorization protocols that use redirection is not yet supported in WebGL.
"backup-authorization": "<authorization-name>", // Optional authorization
"backup-authorization-parameters": { /* Optional authorization parameters */ }In addition to the normal authorization keywords, the "same" keyword can be used to use the same authorization from the online mode in the backup upload.
"backup-authorization": "same", // Optional authorizationFinally, the backup request (method, headers, content-type, query parameters, etc.) can be configured by using the following configuration lines.
"backup_request_config": {
/* Optional configuration parameters */
"method": "POST", // GET, PUT, REMOVE, etc...
"content_type": "application/json",
"headers": {
"<your-custom-header>": "<your-custom-header-value>",
...
}
"query_parameters": {
"<your-custom-query-param>": "<your-custom-query-param-value>",
...
}
}