Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

[Script Update] APIHeartBeat -- A visual cue that the API is running.

1634617184

Edited 1688834820
The Aaron
Roll20 Production Team
API Scripter
Update v0.5.2 &nbsp;-- Added option to suppress the startup announcement for API running. (Thanks&nbsp; Cat ) Update v0.5.1&nbsp; -- Added the option for a Clock in the HeartBeat Macro, Uptime Measurement, and Run Interval History (Thanks&nbsp; Martijn S. ) The clock can be toggled on in the help settings, just like Latency: Time is shown in 24-hour format, there is an hour offset setting in the configuration.&nbsp; No, I'm not going to support Daylight Savings Time or 12-hour clocks. =D Uptime is shown in the Histogram output at the bottom with the other statistics: The format is&nbsp; Days:Hours:Minutes:Seconds. &nbsp; Optimistic, I know. =D History is shown by running the command: !api-heartbeat --history And shows the start and stop times, as well as the duration for runs of the sandbox: The top left date is the oldest recorded start date, the top right is the current date.&nbsp; Date dividers are based on start times. New configuration settings: Show Time &nbsp;-- toggles the clock on and off. Hour Offset &nbsp;-- adjusts for your timezone. Interval History Size &nbsp;-- how many measurements to keep for the history page. APIHeartBeat has been completely rewritten with a new method of keeping tabs on the API! It creates a macro which you can add to your macro toolbar. On an interval, it updates the macro so that you know the API is running. First it has a spinner, which is a sequence of icons that runs in a cycle to show that the API is running.&nbsp; Next is a latency measurement that gives you a rough idea of how busy the API is.&nbsp; The latency is measured in milliseconds.&nbsp; There are 3 different spinners which can be configured in the help: Additionally, you can turn off the latency if you just want a small icon showing you activity: If you click the macro button, or run: !api-heartbeat --histogram You will be presented with a histogram of activity in the API.&nbsp; It keeps the last 600 measurements from the current running sandbox. There isn't much data available to the API, but this should give at least a general feeling for how busy things are.&nbsp; If nothing else, you can look at it while running various scripts to see if they seem to have an impact.&nbsp; The two measurements are: Callback Latency (red) -- This is the number of milliseconds between calling setTimeout() with a 0 delay and receiving the callback.&nbsp; If there isn't much going on, it should be nearly instantaneous.&nbsp; If there are a lot of asynchronous tasks waiting (or the next async task isn't relinquishing control quickly), it will be higher. Interval Latency (green) -- This is a measure of how close the calls into APIHeartBeat are to the requested 1 second (or 200ms for Developer Mode) interval.&nbsp; If there is a lot going on in general (API commands running that aren't asynchronous or are blocking other work), it will be higher. These are kind of poor metrics really, but it's about all we've got. =D When APIHeartBeat starts up, it will issue a message to the GM letting them know the API has started and the Ready event has been issued: You can issue this event (and so can players) to check the API is running with: !api-heartbeat --check Developer Mode measures the API's activity every 200ms instead of every second.&nbsp; This puts a little more burden on the API, but gives better feedback about scripts while you're developing them.&nbsp; Generally, you'd want to leave this off while gaming, but perhaps turn it on while tinkering with scripts (both writing them and trying them out). Here's the Help: APIHeartBeat v0.5.0 APIHeartBeat provides visual feedback that the API is running. Commands !api-heartbeat [--help | --check | --histogram] --help &nbsp;-- Displays this help and configuration options. --check &nbsp;-- Displays a simple message to show that the API is running. --histogram &nbsp;-- Displays a histogram of the last 600 measurements as well as some statistical information about how the API has been running. Description APIHeartBeat creates a macro that is shared with all players. The title on the macro cycles through various images and data while the API is running. It is intended that players or the GM can add the macro to their macro bar allowing them to keep an eye on whether the API is running. Additionally, clicking the macro button with present data about the health of the API. Configuration options are also in the help: Link to the prior forum thread:&nbsp; <a href="https://app.roll20.net/forum/permalink/1567329/" rel="nofollow">https://app.roll20.net/forum/permalink/1567329/</a> This should be in the 1-click next week, or you can get it now from my repo. Git:&nbsp; <a href="https://github.com/shdwjk/Roll20API/blob/master/APIHeartBeat/APIHeartBeat.js" rel="nofollow">https://github.com/shdwjk/Roll20API/blob/master/APIHeartBeat/APIHeartBeat.js</a> Support my work on If you use my scripts, want to contribute, and have the spare bucks to do so , go right ahead. However, please don't feel like you must contribute just to use them! I'd much rather have happy Roll20 users armed with my scripts than people not using them out of some sense of shame. Use them and be happy, completely guilt-free! Disclaimer: This Patreon campaign is not affiliated with Roll20; as such, contributions are voluntary and Roll20 cannot provide support or refunds for contributions.
I wonder if this will help us figure out what exactly is going on when the sandbox is randomly restarting.&nbsp;&nbsp;
1634639949

Edited 1634640058
Wow that's a nice feature. One question, I tried to put it as "tokenaction" as my macrto bar is already pretty full... but in token action it doesn"'t seem to be animated.&nbsp; My bad ? Edit : Also when i have it in my macro bar at the bottom of the screen, i cannot move it to another macro bar portion, as the update of the animation seems to stop the moving manoeuver
Lionel V. said: Wow that's a nice feature. One question, I tried to put it as "tokenaction" as my macrto bar is already pretty full... but in token action it doesn"'t seem to be animated.&nbsp; My bad ? Edit : Also when i have it in my macro bar at the bottom of the screen, i cannot move it to another macro bar portion, as the update of the animation seems to stop the moving manoeuver I was able to move it by removing the script briefly, then moving the macro to the spot, then reinstalling the script.&nbsp;&nbsp;
DM Eddie said: I wonder if this will help us figure out what exactly is going on when the sandbox is randomly restarting.&nbsp;&nbsp; Working on my prep for campaign this morning with this running and witnessed one of the elusive sandbox restarts that have no error attached and this heartbeat api pauses the arrow rotation for about 10 seconds and no api functions work but the sandbox appears normal, no error, no nothing, then suddenly the api sandbox restarts and when I fire the button for this heartbeat it acts as though its just been started and doesn't show what happened prior to the sandbox restart.&nbsp; So this api does indeed give us an early warning of when the api is hanging/crashing.&nbsp;&nbsp;
1634649947
David M.
Pro
API Scripter
Groovy! This is a lot more subtle than the previous version. A tip for others: If you want to move the location of the macrobar button, you will need to disable the script temporarily unless you can drag really fast, as the icon refresh seems to remove focus from the button.
1634651501
The Aaron
Roll20 Production Team
API Scripter
Token Actions don't change unless you deselect and reselect a token, so they won't be suitable.&nbsp; I should probably add a start and stop command to make placing the button easier. Probably adding a counter for how long since the API last started would make sense. Any other feature suggestions?
1634651954
keithcurtis
Forum Champion
Marketplace Creator
API Scripter
This will help with those silent crashes. Great concept!
David M. said: Groovy! This is a lot more subtle than the previous version. A tip for others: If you want to move the location of the macrobar button, you will need to disable the script temporarily unless you can drag really fast, as the icon refresh seems to remove focus from the button. Yup that works perfectly like that (disabling the script while you're moving it) thanks guys&nbsp;
1634679362

Edited 1634680197
As an extra feature i can think of a 'last updated' indicator, probably the time of the last update. So you can see the when the sandbox last send something. The nice thing about this version (as opposed to the old one that changes the GMs' color) is that it only should create load on the GMs computer (or the person that installs the macro's) and it does not intrude gameplay. Cheers!
1634681375
The Aaron
Roll20 Production Team
API Scripter
You're talking about on the button face?&nbsp; I could probably add that as a feature.&nbsp; The API sees time in PT I believe, so I'd likely have to have a timezone configurable. (Well, probably I'd just do an offset from UTC...)
1634681453
The Aaron
Roll20 Production Team
API Scripter
It probably still has some load as it's constantly changing the macro button title.&nbsp; I could detect when the macro is in someone's bar and only update it if that's the case, but I figure in that case, you'd likely just disable the script.
1634709810
The Aaron
Roll20 Production Team
API Scripter
Update v0.5.1 -- Added the option for a Clock in the HeartBeat Macro, Uptime Measurement, and Run Interval History (Thanks&nbsp; Martijn S. ) The clock can be toggled on in the help settings, just like Latency: Time is shown in 24-hour format, there is an hour offset setting in the configuration.&nbsp; No, I'm not going to support Daylight Savings Time or 12-hour clocks. =D Uptime is shown in the Histogram output at the bottom with the other statistics: The format is Days:Hours:Minutes:Seconds. &nbsp; Optimistic, I know. =D History is shown by running the command: !api-heartbeat --history And shows the start and stop times, as well as the duration for runs of the sandbox: The top left date is the oldest recorded start date, the top right is the current date.&nbsp; Date dividers are based on start times. New configuration settings: Show Time -- toggles the clock on and off. Hour Offset -- adjusts for your timezone. Interval History Size -- how many measurements to keep for the history page. That's all for now, let me know if you have any other suggestions!
With only this script as the new script from the last sessions I ran live, I noticed enough additional delay on api response times that I wound up deleting this script mid session and performance immediately improved.&nbsp; To be fair, I also deleted the old api heartbeat script for the same reason.&nbsp; Maybe its cause I have alot of scripts running but most noteably group init had a delay, group check/apply damage was lagged, and combat master had a delay for when it applied its buttons all while this was running.&nbsp; It didn't cause crashes, but it just added a slight delay to everything.&nbsp;&nbsp;
I am so glad The Aaron is not working for the CCP.
1634740297
The Aaron
Roll20 Production Team
API Scripter
Did you have it set to Developer Mode, or regular? &nbsp;I'll try it with GroupInit and see if I get similar results. &nbsp;Maybe adding a low update speed option (like every 5 seconds) would Stull give a heartbeat without too much overhead. &nbsp;Was the button showing the latency for you? And what about the histogram? DM Eddie said: With only this script as the new script from the last sessions I ran live, I noticed enough additional delay on api response times that I wound up deleting this script mid session and performance immediately improved.&nbsp; To be fair, I also deleted the old api heartbeat script for the same reason.&nbsp; Maybe its cause I have alot of scripts running but most noteably group init had a delay, group check/apply damage was lagged, and combat master had a delay for when it applied its buttons all while this was running.&nbsp; It didn't cause crashes, but it just added a slight delay to everything.&nbsp;&nbsp;
1634740576

Edited 1634741108
I'm excited to try this new Heartbeat script out!&nbsp; I wanted something a little more visually grabbing for the spinners, so I played around with some different emoji sets and thought I may as well share what I came up with: Colored hearts Colored circles Colored squares Rotation between hearts, circles, and squares (I thought changing shape and color might be helpful for colorblind folks) Small to large black squares Spinning arrows (using regular html arrows instead of emojis - a little easier for me to see) Heart emojis Small/large heart emoji 'heartbeat' - I found this one is the one that works the best for me. It looks like the Roll20 forums don't like the emojis, so I just put the code into GitHub: <a href="https://github.com/kinchj/Roll20API/blob/main/API%20Heartbeat%20Additions" rel="nofollow">https://github.com/kinchj/Roll20API/blob/main/API%20Heartbeat%20Additions</a> I also removed the '!-' from the start of the macroname (personal preference) but realized that for several of those sets it means that when the macroname changes, it will move around in the Collection Macro list (macros are sorted alphabetically based on their UTC/html entity number). Then I tried using just a single space in front of the macro, but that causes issues with actually calling the macro.... I'm guessing that's why The Aaron put that at the start of the macro.&nbsp; Luckily my preferred small/large heart 'Heartbeat' characters don't cause that problem.
1634765825

Edited 1634765845
The Aaron said: Did you have it set to Developer Mode, or regular? &nbsp;I'll try it with GroupInit and see if I get similar results. &nbsp;Maybe adding a low update speed option (like every 5 seconds) would Stull give a heartbeat without too much overhead. &nbsp;Was the button showing the latency for you? And what about the histogram? DM Eddie said: With only this script as the new script from the last sessions I ran live, I noticed enough additional delay on api response times that I wound up deleting this script mid session and performance immediately improved.&nbsp; To be fair, I also deleted the old api heartbeat script for the same reason.&nbsp; Maybe its cause I have alot of scripts running but most noteably group init had a delay, group check/apply damage was lagged, and combat master had a delay for when it applied its buttons all while this was running.&nbsp; It didn't cause crashes, but it just added a slight delay to everything.&nbsp;&nbsp; The button itself rotated just fine, the histogram had no issues but I also only have your first release installed.&nbsp; It wasn't running developer mode.&nbsp; I had 8 players and myself in the session, it was live and we played on a tuesday night past US primetime into the early morning hours and we didn't have connection lag, infact the players were fine.&nbsp; It was the response time of all api macros like group init, group check, marching order.&nbsp; They all just behaved with a delay to them.&nbsp; I did notice a bunch of spikes in the histogram, noteably with my dragonheist city map, I had everything in the GM layer added with a blue statusmarker so I could tell what was in the GM layer, I selected all and used tokenmod to unblue them all and that task took a very long time and the histogram showed that as an 8 second timeout before it finished. I have 2 scripts that are misbehaving and I have never been able to solve them.&nbsp; First I have a "handled graphic movement" message that constantly pops up that I believe is Combatmaster, some sort of debug setting the author left on I believe, and then CRL, I have had unbelievable difficulty getting this thing setup way back when and the only way I can get it to work causes an error every single time a player rolls an "atkdmg" and "atk" template.&nbsp; My templates fire fine, the CRL behaves fine, but the script fires some error constantly on every template roll that warns me of something but doesn't actually fail what I need it to do so I just let it go, spamming the sandbox slightly with text but I assume neither issue are detrimental as they are just feeding debug messages when they are called upon.&nbsp;&nbsp;
1634766324
The Aaron
Roll20 Production Team
API Scripter
Good info, I'll try and duplicate that.&nbsp; That message is from CombatMaster.&nbsp; It's happening because debug is set to true in the current version.&nbsp; You could edit the script and turn that off on line 17, if you wanted to. No idea on CRL, if you get the exact log message again, feel free to send it to me and I'll see if I can track it down.
1634796369
Victor B.
Pro
Sheet Author
API Scripter
you can go here&nbsp; <a href="https://github.com/vicberg/CombatMaster" rel="nofollow">https://github.com/vicberg/CombatMaster</a>, &nbsp;and download latest as a script.&nbsp; Make sure to disable anything one clkick.&nbsp; Set debug to false.&nbsp; Not sure why debug would be interfering.&nbsp;&nbsp;
Okay....this seems to have a hiccup for me, because I'm "special".&nbsp; :-) When I activate it, it looks like this: It looks like the special arrow icons are missing for some reason.&nbsp; I don't see anything here or in the help file showing that I need to import them or do something else special.&nbsp; Anyone have any ideas?
1635654380
The Aaron
Roll20 Production Team
API Scripter
Hmm. They're Unicode. What OS/Browser?
1635683160

Edited 1635683441
Windows 10.&nbsp; Tried both Firefox and Chrome. This is what I see. I tried a few different unicode browser test pages; they appear to work.
1635685814
The Aaron
Roll20 Production Team
API Scripter
Hmm. If you import the script instead of using the one-click, does it work?
Huh. It appears so. I now have the spinning arrow.&nbsp; Why would that be?
1635696008

Edited 1635696034
The Aaron
Roll20 Production Team
API Scripter
Must be something with the script Import process that breaks multi-byte characters. I'll make an update to build the characters from their integer value and get that committed.&nbsp;
1635951908
timmaugh
Pro
API Scripter
The Aaron said: Must be something with the script Import process that breaks multi-byte characters. I'll make an update to build the characters from their integer value and get that committed.&nbsp; That's the problem I had with the torii signature glyph in all of my scripts. I was using certain unicode characters that were being eaten by the one-click install process. I had to go reconfigure it to use other characters.
1635955741
keithcurtis
Forum Champion
Marketplace Creator
API Scripter
Same with the Reporter script.
Thanks for the info on importing the script manually.&nbsp; I have used previous versions of the script and am very happy with the update.&nbsp; This is fantastic!&nbsp;
Much improved over the old version, and I like that my players can check if the API is running if they log in between sessions to fuss with their characters. Great work, and thank you!&nbsp;
1637406531

Edited 1637406771
Like to share my observation. With the new version of the script, as opposed to the old version that updates the player color, my players complain more about lag, updates not arriving, slow rolls. As a GM, with the macro being updated every second experience rock solid experience. Get the distinct feeling that constant changing of the player color has a positive influence on the longevity of the firebase connection and/or the priority of the Games apiscript on the api server.
1637449688
The Aaron
Roll20 Production Team
API Scripter
Hmmm. I'll have to investigate that.&nbsp;
1641969440

Edited 1641969587
GiGs
Pro
Sheet Author
API Scripter
I just had a weird problem. I added the script, and had a similar problem to Anthony earlier - the macro name was not showing up with the rotating arrow. So I deleted the script, and imported it. There was no difference, then I realised it still had the same macro, so i deleted it. And now the script started adding a new macro every couple of seconds, leading to this: [REDACTED: roll20 software lost the image. But I had 10 ~10 macros all very identical, with images similar to anthonies above, but no colour and fewer numbers at the end) Thats what the macro looked like in the token bar too btw. So I disabled the script again, deleted all the macros, and clicked Add Script (by mistake, I meant to Import it again). I looked back in the campaign, and no macro had been added. So I deleted te script yet again, then Imported it, and finally got a working tokenbar script with a rotating arrow. It still has less details than the earlier pic though, it looks like this: Though the arrow is rotating, and the number changes sometimes . It stays the same for several seconds.