Skip to content

Latest commit

 

History

History
115 lines (83 loc) · 8.35 KB

README.md

File metadata and controls

115 lines (83 loc) · 8.35 KB
Raw

CFC Error Forwarder

A pure-lua (well, Moonscript) Error tracker for Garry's Mod.

This addon will watch for errors, do a little investigation, and send a message to a Discord channel for your review.

Who is this for?

This is for Server Owners/Operators. This allows server operators to monitor and manage the errors that occur on their server.

Who is this not for?

Addon developers looking for a way to track their errors automatically across all servers - this is not the tool for you.


Notice ⚠️

A full-rewrite of this addon is nearly complete. It has fixes, new features, design reworks, discord ratelimit prevention, reliability improvements, and more.

Please keep an eye out for the update!

You can track its progress (or ask questions) in our support Discord: https://discord.gg/5JUqZjzmYJ


Some nifty features:

  • 🧠 If using source-controlled addons (i.e. git repos in your addons/ dir), err_forwarder will generate a link to github.com, showing you the exact line that errored
  • 🪝 Tracks Serverside and (optionally) Clientside errors, and can send messages to different channels depending on which realm the errors occurred in
  • 📦 Includes basic batching logic so it won't spam your error channel
  • 🔎 Shows you the current values of up to 8 local variables in the stack that threw an error (very useful for debugging!)

Requirements

  • gmsv_reqwest Required
  • gm_luaerror (Optional)
    • Add this module if you want more information about serverside errors, such as locals at the time of error

Installation

Simple

  • You can download the latest release .zip from the Releases tab. Extract that and place it in your addons directory.

Source Controlled

  • You can clone this repository directly into your addons directory, but be sure to check out the lua branch which contains the compiled Lua from the latest release.
  • e.g. git clone --single-branch --branch lua git@github.com:CFC-Servers/cfc_err_forwarder.git

Configuration

  • cfc_err_forwarder_interval: The interval (in seconds) at which errors are parsed and sent to Discord
  • cfc_err_forwarder_server_webhook: The full Discord Webhook URL to send Serverside errors
  • cfc_err_forwarder_client_webhook: The full Discord Webhook URL to send Clientside errors
  • cfc_err_forwarder_client_enabled: A boolean indicating whether or not the addon should even track Clientside errors
  • cfc_err_forwarder_bucket_size: Client -> Server rate limiting bucket size. (Only applies when not using the luaerror dll)

Screenshots

Serverside Error with Locals and Context

DiscordCanary_nmbYDY33PH

Clientside Error with Context

image


Hooks

CFC_ErrorForwarder_PreQueue

Called before an Error is queued to be processed.

Return false to prevent it from being queued.

You may also (carefully) modify the error structure.

Error Structure

With the following code:

-- addons/example/lua/example/init.lua
AddCSLuaFile()
if SERVER then return end

local function exampleFunction()
    print( 5 + {} )
end

hook.Add( "InitPostEntity", "Example", function()
    ProtectedCall( exampleFunction )
end )

The error structure would look like:

Name Type Example Description
branch string "unknown" (Base branch) The game branch where the error occurred. Is either "Not sure yet" if the client errored early, or BRANCH string
count number 1 How many times this error has occurred (Will always be 1 in CFC_ErrorForrwarder_PreQueue)
errorString string "attempt to perform arithmetic on a table value" The actual error message that was produced
fullError string The full, raw, multiline error string with a simplified stack
isClientside boolean true Whether or not this error occurred on a client
isRuntime boolean true "Whether this is a runtime error or not" - taken straight from gm_luaerror
occurredAt number 1704534832 The result of os.time() of when the error occurred
ply Player Player [1][Phatso] The Player who experienced the error, or nil if serverside
plyName string "Phatso" nil if serverside
plySteamID string "STEAM_0:0:21170873" nil if serverside
reportInterval number 60 In seconds, how often the addon is sending errors to Discord
sourceFile string "addons/test/lua/example/init.lua" The file path where the error occurred
sourceLine number 4 The line in the file where the error occurred
stack table { 1 = { currentline = 4, name = "unknown", source = "..." }, ... } A numerically indexed Stack object

CFC_ErrorForwarder_OnReceiveCLError

This hook is only called when the luaerror dll is not installed.

This hook is called in the network receiver that is triggered when a player forwards their error to the server.

Return false to prevent it from being processed.