Custom events

Call the server-side exports#

Use exports['XenLogs'] from another server resource. The export records the calling resource as the source and uses custom_log as the event name. Category and structured data describe the action.

-- Call after your server validates and completes the purchase.
exports['XenLogs']:log('economy', 'Vehicle purchased', {
    vehicle = 'sultan',
    price = 25000,
    payment = 'bank'
})

exports['XenLogs'].log('economy', 'Vehicle purchased', {
  vehicle: 'sultan',
  price: 25000,
  payment: 'bank',
});

Export reference#

log(category, message, data?)
logWarn(category, message, data?)
logError(category, message, data?)
logDebug(category, message, data?)

logPlayer(category, playerSource, message, data?)
logPlayerError(category, playerSource, message, data?)

• category: a string such as economy, inventory, admin, or custom. An empty category falls back to custom.
• message: a readable description of the completed action.
• data: an optional Lua table or JavaScript object with JSON-serializable fields.
• playerSource: the player's current numeric server ID. Player exports attempt to attach the player's license identifier and name.
• log and logPlayer use info severity; the other export names select warn, error, or debug as indicated.

-- playerSource must be a validated player ID from your server handler.
exports['XenLogs']:logPlayer('economy', playerSource, 'Reward paid', {
    amount = 500,
    reason = 'delivery_completed'
})

exports['XenLogs']:logPlayerError('economy', playerSource, 'Payment rejected', {
    reason = 'insufficient_funds'
})

Create a small test resource#

Create resources/xenlogs-example/ with these two files. This is a small resource you create yourself; the XenLogs download does not include an additional hooks resource.

fx_version 'cerulean'
game 'gta5'

dependency 'XenLogs'
server_script 'server.lua'

RegisterCommand('xenlogs-test', function(source)
    if source ~= 0 then return end

    exports['XenLogs']:log('custom', 'Installation test', {
        resource = GetCurrentResourceName(),
        test = true
    })
end, true)

ensure XenLogs
ensure xenlogs-example

After loading the resources, run xenlogs-test in the server console. Open Logs for the correct server and look for Installation test with source xenlogs-example and event custom_log. Allow a short batching delay.

Write useful, bounded events#

• Log after server-side validation and state changes. A client request alone is not proof an action succeeded.
• Capture source into a local variable before asynchronous work in a Lua event handler, then pass that saved player ID.
• Include stable fields such as item, amount, transaction ID, and reason. Avoid entire framework player objects.
• Keep payloads small. Serialized data longer than 8,192 characters is replaced with truncation metadata and a preview.
• Do not include API keys, passwords, or authentication tokens. Avoid using message or _playerName as custom data keys because they can replace generated fields.
• Put calls in your editable server scripts or a dedicated server-side hooks resource. Start that resource after XenLogs.