[UDF] Rollbar Error Reporting v0.2

[EmilyLove]

What is Rollbar?

Rollbar provides real-time error alerting & debugging tools for developers. Learn more about it at https://rollbar.com/product/

Demo: https://rollbar.com/demo/demo/

Screenshot:

Spoiler

Instructions: (RollbarTest.au3)

expandcollapse popup

; Include RollbarSDK
#include "RollbarSDK.au3"

;Turns on ConsoleWrite debugging override.
;Global $Rollbar_Debug=False

; Initialize RollbarSDK with the project's API key.
; Parameters ....:  $__Rollbar_sToken   - [Required] Go to https://rollbar.com/<User>/<ProjectName>/settings/access_tokens/ for your project. Use the token for post_server_item.
_Rollbar_Init("eaa8464a4082eeabd9454465b8f0c0af")

; Write code that causes an error you want to catch, then call

; _Rollbar_Send
; Parameters ....:  $__Rollbar_sErrorLevel      - [Required] Must be one of the following values: Debug, Info, Warning, Error, Critical.
;                   $__Rollbar_sMessage         - [Required] The message to be sent. This should contain any useful debugging info that will help you debug.
;                   $__Rollbar_sMessageSummary  - [Optional] A string that will be used as the title of the Item occurrences will be grouped into. Max length 255 characters. If omitted, Rollbar will determine this on the backend.
_Rollbar_Send("Debug", "This is an debug message. If you received this, you were successful!", "Debug Message")
_Rollbar_Send("Info", "This is a test message. If you received this, you were successful!", "Info Message")
_Rollbar_Send("Warning", "This is an warning message. If you received this, you were successful!", "Warning Message")
_Rollbar_Send("Error", "This is an error message. If you received this, you were successful!", "Error Message")
_Rollbar_Send("Critical", "This is an critical message. If you received this, you were successful!", "Critical Message")
_Rollbar_Send("Info", "This is a test message. If you received this, you were successful!") ;No Message

; Rollbar_Send's helper functions
; Parameters ....:  $__Rollbar_sMessage         - [Required] The message to be sent. This should contain any useful debugging info that will help you debug.
;                   $__Rollbar_sMessageSummary  - [Optional] A string that will be used as the title of the Item occurrences will be grouped into. Max length 255 characters. If omitted, Rollbar will determine this on the backend.
_Rollbar_SendDebug("This is an debug message. If you received this, you were successful!", "Debug Message")
_Rollbar_SendInfo("This is a test message. If you received this, you were successful!", "Info Message")
_Rollbar_SendWarning("This is an warning message. If you received this, you were successful!", "Warning Message")
_Rollbar_SendError("This is an error message. If you received this, you were successful!", "Error Message")
_Rollbar_SendCritical("This is an critical message. If you received this, you were successful!", "Critical Message")

; Usable Example
Local $sImportantFile = "C:\NOTAREALFILE_1234554321.txt"
Switch FileExists($sImportantFile)
    Case True
        MsgBox(0, "Example Script", "An important file was found. Continuing...")
    Case Else
        _Rollbar_SendCritical('An important file was missing. Halting... File: "' & $sImportantFile & '"', 'Important file "' & $sImportantFile & '" is missing.')
EndSwitch

Notes: Please comment your feedback, advice, & suggestions below. While this is only a proof of concept, I will expand its feature set for everyone to use. 

Right now, it is fully functional but not tested in production.

 

 

Changelog:

RollbarSDK.au3

RollbarTest.au3

v0.2

Spoiler

https://www.autoitscript.com/forum/topic/198704-rollbar/?do=findComment&comment=1427145

This update contains massive script breaking changes.

Added:

• Multilingual support. See #CONSTANTS# section.
  Note: I won't be able to provide translations.

Changed/Fixed:

• All functions and variables have been renamed to align with UDF best practices.

 

 

v0.1.1

Spoiler

https://www.autoitscript.com/forum/topic/198704-rollbar/?do=findComment&comment=1426743

This update contains script breaking changes. See RollbarInit (2 Parameters ==> 1)

Added:

• Main Function: RollbarInit_Ask (Asks for user permission to send automatic bug reports, saves preference in ScriptName_Debug.ini) (For devs who respect user privacy)
• Helper Function: Rollbar_CreateItem (same as RollbarCreateItem)
• Helper Function: Rollbar_Send (same as RollbarCreateItem)
• Helper Function: Rollbar_SendDebug (Rollbar_Send as Debug)
• Helper Function: Rollbar_SendInfo (Rollbar_Send as Info)
• Helper Function: Rollbar_SendWarning (Rollbar_Send as Warning)
• Helper Function: Rollbar_SendError (Rollbar_Send as Error)
• Helper Function: Rollbar_SendCritical (Rollbar_Send as Critical)
• ConsoleWrite Debugging Override: $Rollbar_Debug = True / False

Changed/Fixed:

• Split RollbarCreateItem into 2 functions: RollbarCreateItem & RollbarSendItem
• ConsoleWrite Debugging is now Opt-In on compiled builds only. 
• Decreased number of parameters for RollbarInit.
• Cleaned up some comments
• RollbarCreateItem & RollbarSendItem now properly sets a reasonably expectable return value (True when successful, False when failed)

Removed:

• Removed optional write token.

 

Edited June 21, 2019 by BetaLeaf

[mLipok]

Thanks  for sharing.

Will look closer.

Edited April 27, 2019 by mLipok

[EmilyLove]

4 minutes ago, mLipok said:

Thanks  for sharing.

Will look closer.

Thanks for checking it out. Let me know what you think and what I can do to improve it.

[guinness]

I like where this is going and I have some suggestions, which you don't have to agree with

• Rename RollbarCreateItem to Rollbar_Send
  • I understand what you are trying to convey, by having the API item as part of the name, but "CreateItem" in this case is also sending data to Rollbar
• Create help functions e.g.
  • Rollbar_SendDebug
  • Rollbar_SendInfo
  • ....
• Writing to the console should be opt-in and not on by default, either by using a flag or by asking for a logging function
• RollbarCreateItem is quite big, and can be broken down into smaller functions
• Validation of the API token would be good

Keep it up!

[EmilyLove]

Thanks for the feedback. Rest assured, I will use your feedback to improve the SDK. I'm working on it now.

[EmilyLove]

5 hours ago, guinness said:

Validation of the API token would be good

How do you recommend I handle this when it fails? 

I feel that before a production release that the developer should make sure the API keys are working. You can already tell from ConsoleWrite messages if the key is working or not. I don't think it would be a good idea to let user's know API key is broken or even ask them to fill it in. This should all be handled by the developer. I don't even think it is a good idea to warn the user that API keys are invalid. Advice?

[EmilyLove]

Updated to v0.1.1

This update contains script breaking changes. See RollbarInit (2 Parameters ==> 1)

Added:

• Main Function: RollbarInit_Ask (Asks for user permission to send automatic bug reports, saves preference in ScriptName_Debug.ini) (For devs who respect user privacy)
• Helper Function: Rollbar_CreateItem (same as RollbarCreateItem)
• Helper Function: Rollbar_Send (same as RollbarCreateItem)
• Helper Function: Rollbar_SendDebug (Rollbar_Send as Debug)
• Helper Function: Rollbar_SendInfo (Rollbar_Send as Info)
• Helper Function: Rollbar_SendWarning (Rollbar_Send as Warning)
• Helper Function: Rollbar_SendError (Rollbar_Send as Error)
• Helper Function: Rollbar_SendCritical (Rollbar_Send as Critical)
• ConsoleWrite Debugging Override: $Rollbar_Debug = True / False

Changed/Fixed:

• Split RollbarCreateItem into 2 functions: RollbarCreateItem & RollbarSendItem
• ConsoleWrite Debugging is now Opt-In on compiled builds only. 
• Decreased number of parameters for RollbarInit.
• Cleaned up some comments
• RollbarCreateItem & RollbarSendItem now properly sets a reasonably expectable return value (True when successful, False when failed)

Removed:

• Removed optional write token.

Edited May 4, 2019 by BetaLeaf

[user4157124]

Some suggestions:

- https://www.autoitscript.com/wiki/Best_coding_practices
- https://www.autoitscript.com/wiki/UDF-spec
- Remove AutoIt3Wrapper directives from UDF (even if just AU3Check; remove on release or add to RollbarTest.au3 instead).
- Replace .ini operations by a 2D array (set from function like _Rollbar_Set($iAttr, $nValue) ).
- Remove MsgBox() -calls and saving as .ini or move to separate function (so main script controls MsgBox(), .ini file path and choice to load or not; configuration, permission and GUI-notification being calling/including script's responsibility, UDF itself to be concerned with maintaining valid internal state only).
- Accept output from dedicated error logger function/UDF instead (or split into separate UDF's). Error loggers ideally enable registering custom functions on Exit, for COM Object errors, for custom date/time format and item output (console, file, Beep(), etc.), and auto-elevate level if @error (level error), if @extended (level debug), or if @exitCode (level critical/fatal), inclusion of @ScriptLineNumber, transparently passing @error/@extended, etc.; which (along with other error-logger's functionality) although necessary, seems out of scope for a Rollbar transmission UDF specifically.
- Rollbar_Send...() et al. seem redundant; single function could accept level parameter as int (using Enum instead of quoted str has SciTE suggest auto-completion too). Generally error level depends on outcome logged; naming functions after parameters introduces hard coded specificity as (unless used with Call() ) it's valid within pre-defined (foreseen) context only (specific If/Else branch for example).
- Hard coded text messages don't sit well with German, French, Russian, etc. AutoIt communities (of consideration if widespread adoption is a goal).

[EmilyLove]

On 5/5/2019 at 11:18 AM, user4157124 said:

Replace .ini operations by a 2D array (set from function like _Rollbar_Set($iAttr, $nValue) ).

Do you have a specific use case in mind? The only reason to set Ini is to save user preference rather or not they want to allow or disallow automatic bug reporting. I don't see a good reason to create a function just to set values once.

On 5/5/2019 at 11:18 AM, user4157124 said:

Remove MsgBox() -calls and saving as .ini or move to separate function (so main script controls MsgBox(), .ini file path and choice to load or not; configuration, permission and GUI-notification being calling/including script's responsibility, UDF itself to be concerned with maintaining valid internal state only).

Can you please be a bit clearer so I can better understand what you are requesting?

On 5/5/2019 at 11:18 AM, user4157124 said:

Accept output from dedicated error logger function/UDF instead (or split into separate UDF's). Error loggers ideally enable registering custom functions on Exit, for COM Object errors, for custom date/time format and item output (console, file, Beep(), etc.), and auto-elevate level if @error (level error), if @extended (level debug), or if @exitCode (level critical/fatal), inclusion of @ScriptLineNumber, transparently passing @error/@extended, etc.; which (along with other error-logger's functionality) although necessary, seems out of scope for a Rollbar transmission UDF specifically.

This is too jumbled for me to understand. Can you please be a bit clearer so I can better understand what you are requesting?

On 5/5/2019 at 11:18 AM, user4157124 said:

Rollbar_Send...() et al. seem redundant; single function could accept level parameter as int (using Enum instead of quoted str has SciTE suggest auto-completion too). Generally error level depends on outcome logged; naming functions after parameters introduces hard coded specificity as (unless used with Call() ) it's valid within pre-defined (foreseen) context only (specific If/Else branch for example).

[Rejected]  Rollbar_Send is redundant, however, as you said, "Generally error level depends on outcome logged". This allows devs to be more flexible.
[Rejected]  ErrorLevel must be a string, because Rollbar REST API expects a string. I cannot send as int.

On 5/5/2019 at 11:18 AM, user4157124 said:

https://www.autoitscript.com/wiki/Best_coding_practices
https://www.autoitscript.com/wiki/UDF-spec
Remove AutoIt3Wrapper directives from UDF (even if just AU3Check; remove on release or add to RollbarTest.au3 instead).
Hard coded text messages don't sit well with German, French, Russian, etc. AutoIt communities (of consideration if widespread adoption is a goal).

Done and coming soon in v0.2

 

@user4157124 If I misunderstood anything, please clarify by being clear and concise. 

Edited May 9, 2019 by BetaLeaf
Clarification

[EmilyLove]

I just updated my previous comment. I posted too early by accident (hotkey). If you are currently replying, please review the edits before submitting your comment.

[EmilyLove]

Updated to v0.2
Now aligned with UDF best practices!

This update contains massive script breaking changes.

Added:

• Multilingual support. See #CONSTANTS# section.
  Note: I won't be able to provide translations.

Changed/Fixed:

• All functions and variables have been renamed to align with UDF best practices.

 

RollbarSDK.au3 RollbarTest.au3

[user4157124]

"Do you have a specific use case in mind?"

UDF settings in general (the individual global vars). Including script should decide how to configure UDF (and where to get settings from). File path is hard-coded currently (location requires administrative rights to modify if used in compiled script installed to \Program Files\). Array enables setting options like:

Func Rollbar_Set($iAttr, $nValue)
$__g_aRollbar_Opt[$iAttr] = $nValue
...
EndFunc


"Can you please be a bit clearer so I can better understand what you are requesting?"

UDF accepts user choices and outputs information, but including script should control presentation (MsgBox(), GUI, etc.). Including this UDF to scripts compiled as console for example, forces display of GUI elements (mixes logic and presentation; scripts can't control its behavior).

"This is too jumbled for me to understand. Can you please be a bit clearer so ..."

Too concise probably. Error loggers require quite some functionality to be considered useful (but most of that seems out of scope for this UDF). Some users posted dedicated error logging UDF's; yours could take their output as input.

"This allows devs to be more flexible."

Design choice being (opinion based, current way is fine too):

Rollbar_SendWarning('Msg')
Rollbar_SendError('Msg')

or:

Rollbar_Send($ROLLBAR_LVL_WARNING, 'Msg')
Rollbar_Send($ROLLBAR_LVL_ERROR, 'Msg')


"... Rollbar REST API expects a string."

That's what UDF's are for (to make sure what gets input is output as required). Example (no out of bounds -check):

Func Rollbar_Send($iLevel, $sMsg = '')
Local $aLevel = ['trace', 'debug', 'info', 'warning', 'error', 'fatal']
Local $sLevel = $aLevel[$iLevel]
...
EndFunc


2D arrays are ideal for localization:

Enum $ROLLBAR_LANG_EN, $ROLLBAR_LANG_DE, ..., $ROLLBAR_LANG__ENUM
Enum $ROLLBAR_TEXT_TEST, ..., $ROLLBAR_TEXT__ENUM
Global $__g_aRollbar_Txt[$ROLLBAR_TEXT__ENUM][$ROLLBAR_LANG__ENUM]
$__g_aRollbar_Txt[$ROLLBAR_TEXT_TEST][$ROLLBAR_LANG_EN] = 'Example text.'
$__g_aRollbar_Txt[$ROLLBAR_TEXT_TEST][$ROLLBAR_LANG_DE] = 'Beispieltext.'

$g_iLang = $ROLLBAR_LANG_EN
MsgBox($MB_OK, @ScriptName, $__g_aRollbar_Txt[$ROLLBAR_TEXT_TEST][$g_iLang])

Edited May 9, 2019 by user4157124

[EmilyLove]

@user4157124 Thank you for clarifying. I'll work on it a bit later today or tomorrow. I spend all day working on v0.2 yesterday and I'm only one guy haha. I did have a few more questions.

You mentioned that my design decisions are opinion based. You have an opinion as well. I'd like to hear it. Get your perspective on things. Mind discussing this with me?

You also mentioned that I have a hard coded path. Which path are you talking about? I'm pretty sure the only file being written to is the SCRIPTNAMENOEXT_Debugging.ini and the only reason I write this file is to save user preference when _Rollbar_Init_Ask is used. Using _Rollbar_Init won't ask the user, which means no saved ini file, and force it on. I can't see your use case having any relevance here. Your set variables would be lost when the app is closed. Can you provide a use case for this?

I'm going to look up these error reporting UDFs you mentioned. Did you have any specific ones in mind?

Is there a best practices page for regarding localization in autoit? You are clearly more knowledgeable regarding this topic, so I'd like to take this opportunity to learn something new. 

[user4157124]

I meant my design suggestion is opinion based (function level name vs. level parameter). Seeing different settings (onoff/debug -state, file path, API key) I suggested formalization (set -function could do what _Init, _Init_Ask, $__G_Rollbar_bDebug and hard coded .ini file path do). Availability throughout runtime has no particular advantage to that specific option no. MsgBox() -choice and IniRead() is nice to have, but generally including script's responsibility.

The .ini file is referenced relative to @ScriptDir, so when C:\Program Files\MBP\MyBigProgram.exe (compiled AutoIt script having #include "RollbarSDK.au3") wants to let RollbarSDK do its IniWrite(), then MyBigProgram.exe needs admin rights (because @ScriptDir is a folder in C:\Program Files). That is the hard coded path (despite @ScriptDir being relative). It is distinct from @WorkingDir additionally (line 48).

I am not aware of documented localization best-practices for AutoIt (but wouldn't differ from other languages). Simply returning @error (not generating messages) enables including script to relate as required.
May be as simple as $sError = $aError[@error][$iLang] (if @error from _Rollbar_SendItem() is of Enum instead of HTTP code). Or as formal as separate text files (so changes require restart/reload rather than recompile). Also, StringFormat('HTTP Status %i - %s', $iCode, $sMsg) may save a few constants.

Error loggers :
https://www.autoitscript.com/forum/topic/195862-loga-a-logging-library/
https://www.autoitscript.com/forum/topic/195882-errorlogau3-udf-a-logging-library/

I use another (not sure how it compares, may release if anyone cares).

[mLipok]

3 hours ago, user4157124 said:

I use another (not sure how it compares, may release if anyone cares).

Would be nice to take a look...

[EmilyLove]

@user4157124
Both of those error loggers don't  seem to really offer anything different than what I already offer with Rollbar UDF. You can easily create a variable to hold the message and send it to both Rollbar UDF and your error logger of choice. 

5 hours ago, user4157124 said:

The .ini file is referenced relative to @ScriptDir, so when C:\Program Files\MBP\MyBigProgram.exe (compiled AutoIt script having #include "RollbarSDK.au3") wants to let RollbarSDK do its IniWrite(), then MyBigProgram.exe needs admin rights (because @ScriptDir is a folder in C:\Program Files). That is the hard coded path (despite @ScriptDir being relative). It is distinct from @WorkingDir additionally (line 48).

When you #Include "RollbarSDK.au3" and use _Rollbar_Init_Ask, then it will write to @ScriptDir. This ensures that the user preference for automatic reporting (either enabled or disabled) can always be found. @ScriptDir ensures that the ini file writes to the same directory as the program that included it. This has a couple of added benefits/protections: 

1) If you install your program to a protect folder that needs admin to read/write, then you should also probably protect the user preference. If you want to disable this, you can simply change the permissions (Windows ACL) of the ini file to allow Users or Everyone to read/write the file. This gives the end user a degree of control from limited users on their systems. (A guest account, maybe malicious, might find it a good idea to disable logging so they don't get reported, and a sysadmin might want to prevent this from happening) 
2) For multiple projects, this ensures that each program's preference is easily identifiable.
3) A badly written UDF that changes the working directory would cause unintended side effects when trying to save the user preference
(saving in the wrong directory, but shouldn't effect reading the file back in this case, just harder to find because it isn't where you expect it to be).
4) Prevents the end user from setting a different working directory (from a desktop shortcut, for example) and causing unintended side effects when trying to save the user preference.

5 hours ago, user4157124 said:

Also, StringFormat('HTTP Status %i - %s', $iCode, $sMsg) may save a few constants.

I didn't know about this. I'll take a look into this and implement it.

P.S. This was all meant to be a Proof-Of-Concept and not so much a UDF. It was my mistake to label it a UDF. I'm not super excited to continue working on this project and would rather work on the next project on my list. I will still continue to work on it, as long as there is interest and people make suggestions or requests. If I am too slow to get your request out, then the source code (RollbarSDK.au3) is there and anyone can continue my work under the MIT license. All I really care about is being credited for my work. Just include my name somewhere and we're good. My MIT License

[user4157124]

No need to rename (it's a UDF, good one too). And serves a purpose.

@WorkingDir was not a suggestion; line 48 describes @ScriptDir as "Working Directory". The predefined path isn't a problem (non asking function available too) but illustrates limitations introduced by a solution implemented on different level/scope than it affects.

@mLipok

Could do something like :

expandcollapse popup

#AutoIt3Wrapper_AU3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7
#include "auerlo.au3"
#include "RollbarSDK.au3"

Main()

Func Main()
    Local $aArray

    _AUERLO_Set($AUERLO_OPT_LOGSTD,     True)
    _AUERLO_Set($AUERLO_OPT_LVLSTD,     $AUERLO_LVL_ALL)
    _AUERLO_Set($AUERLO_OPT_LOGCUSTOM,  True)
    _AUERLO_Set($AUERLO_OPT_LVLCUSTOM,  $AUERLO_LVL_WARNING)
    _AUERLO_Set($AUERLO_OPT_FUNCCUSTOM, __AUERLO_OutputRollbar)
    _AUERLO_Set($AUERLO_OPT_FUNCEXIT,   Default)
    _AUERLO_Set($AUERLO_OPT_FUNCCOM,    Default)
    _AUERLO_Set($AUERLO_OPT_TIMEUTC,    True); Consistency on collective deployment.

    _Rollbar_Init('RollbarAPIkeyhere')
    _AUERLO_Log()

    For $i1 = $AUERLO_LVL_TRACE To $AUERLO_LVL_FATAL

        _AUERLO_Log('Message #' & $i1 + 1, $i1)

    Next

    _AUERLO_Read($aArray)
    _AUERLO_View($aArray)

;   Exit
EndFunc

Volatile Func __AUERLO_OutputRollbar($aData)
    Local       $aLvl[$AUERLO_LVL__ENUM]
                $aLvl[$AUERLO_LVL_TRACE]   = 'Debug'
                $aLvl[$AUERLO_LVL_DEBUG]   = 'Debug'
                $aLvl[$AUERLO_LVL_INFO]    = 'Info'
                $aLvl[$AUERLO_LVL_WARNING] = 'Warning'
                $aLvl[$AUERLO_LVL_ERROR]   = 'Error'
                $aLvl[$AUERLO_LVL_FATAL]   = 'Critical'
    Local Const $sLvl = $aLvl[ $aData[$AUERLO_ATR_LEVEL] ], _
                $sMsg = $aData[$AUERLO_ATR_DATETIME] & ($__g_aAUERLO_OptCur[$AUERLO_OPT_TIMEUTC] ? 'UTC' : 'loc') _
                      & $aData[$AUERLO_ATR_MESSAGE] ? ' - ' : '' _
                      & $aData[$AUERLO_ATR_MESSAGE], _
                $sCat = __AUERLO_GetTxtLevel($aData[$AUERLO_ATR_LEVEL]); Or other category -determining function.
    Local Const $iRet = _Rollbar_CreateItem($sLvl, $sMsg, $sCat)

;   _AUERLO_Log('_AUERLO_AuerloToRollbar()'); Infinite regress on _Rollbar_CreateItem() @error?

    Return SetError(@error, @extended, $iRet)
EndFunc

 

Edited May 19, 2019 by user4157124

[EmilyLove]

On 5/14/2019 at 11:25 AM, user4157124 said:

No need to rename (it's a UDF, good one too). And serves a purpose.

@WorkingDir was not a suggestion; line 48 describes @ScriptDir as "Working Directory". The predefined path isn't a problem (non asking function available too) but illustrates limitations introduced by a solution implemented on different level/scope than it affects.

On your suggestion, I renamed it back to UDF.

I see what you mean about line 48. This clarified my confusion. With my current level of understanding, I don't know how to get a running program's working directory. I use @scriptdir because it will always be the same folder as the rollbar enabled program. Since most programs usually have a working directory of the executable file, I figured it was good enough. If you know how to get a running program's working directory, please enlighten me.

Sorry for the late reply. I have been battling some crippling/suicidal depression. I had to step away from things and take care of myself for a bit. I'm good now though. 

 

If you have any suggestions or feedback for me, I'd be more than happy to tackle them.