"Fossies" - the Fresh Open Source Software Archive

Member "netdata-v1.26.0/web/api/badges/README.md" (14 Oct 2020, 20585 Bytes) of package /linux/misc/netdata-v1.26.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

Netdata badges

Badges are cool!

Netdata can generate badges for any chart and any dimension at any time-frame. Badges come in SVG and can be added to any web page using an <IMG> HTML tag.

Netdata badges are powerful!

Given that Netdata collects from 1.000 to 5.000 metrics per server (depending on the number of network interfaces, disks, cpu cores, applications running, users logged in, containers running, etc) and that Netdata already has data reduction/aggregation functions embedded, the badges can be quite powerful.

For each metric/dimension and for arbitrary time-frames badges can show min, max or average value, but also sum or incremental-sum to have their volume.

For example, there is a chart in Netdata that shows the current requests/s of nginx. Using this chart alone we can show the following badges (we could add more time-frames, like today, yesterday, etc):

Similarly, there is a chart that shows outbound bandwidth per class, using QoS data. So it shows kilobits/s per class. Using this chart we can show:

The right one is a volume calculation. Netdata calculated the total of the last 86.400 seconds (a day) which gives kilobits, then divided it by 8 to make it KB, then by 1024 to make it MB and then by 1024 to make it GB. Calculations like this are quite accurate, since for every value collected, every second, Netdata interpolates it to second boundary using microsecond calculations.

Let's see a few more badge examples (they come from the Netdata registry):


So, every single line on the charts of a Netdata dashboard, can become a badge and this badge can calculate average, min, max, or volume for any time-frame! And you can also vary the badge color using conditions on the calculated value.


How to create badges

The basic URL is http://your.netdata:19999/api/v1/badge.svg?option1&option2&option3&....

Here is what you can put for options (these are standard Netdata API options):

  <a href="#">
     <img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu"></img>
  </a>

Which produces this:

  <a href="#">
     <img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&dimensions=system%7Cnice"></img>
  </a>

Which produces this:

  <a href="#">
     <img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&after=-60"></img>
  </a>

Which produces the average of last complete minute (XX:XX:00 - XX:XX:59):

While this is the previous minute (one minute before the last one, again aligned XX:XX:00 - XX:XX:59):

  <a href="#">
     <img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=system.cpu&before=-60&after=-60"></img>
  </a>

It produces this:

These are options dedicated to badges:

<embed src="BADGE_URL" type="image/svg+xml" height="20" />

Another way is to use javascript to auto-refresh them. You can auto-refresh all the Netdata badges on a page using javascript. You have to add a class to all the Netdata badges, like this <img class="netdata-badge" src="..."/>. Then add this javascript code to your page (it requires jquery):

<script>
    var NETDATA_BADGES_AUTOREFRESH_SECONDS = 5;
    function refreshNetdataBadges() {
      var now = new Date().getTime().toString();
      $('.netdata-badge').each(function() {
        this.src = this.src.replace(/\&_=\d*/, '') + '&_=' + now;
      });
      setTimeout(refreshNetdataBadges, NETDATA_BADGES_AUTOREFRESH_SECONDS * 1000);
    }
    setTimeout(refreshNetdataBadges, NETDATA_BADGES_AUTOREFRESH_SECONDS * 1000);
</script>

A more advanced badges refresh method is to include http://your.netdata.ip:19999/refresh-badges.js in your page.


Escaping URLs

Keep in mind that if you add badge URLs to your HTML pages you have to escape the special characters:

character name escape sequence
`` space (in labels and units) %20
# hash (for colors) %23
% percent (in units) %25
< less than %3C
> greater than %3E
\ backslash (when you need a /) %5C
| pipe (delimiting parameters) %7C

FAQ

Is it fast?

On modern hardware, Netdata can generate about 2.000 badges per second per core, before noticing any delays. It generates a badge in about half a millisecond!

Of course these timing are for badges that use recent data. If you need badges that do calculations over long durations (a day, or more), timing will differ. Netdata logs its timings at its access.log, so take a look there before adding a heavy badge on a busy web site. Of course, you can cache such badges or have a cron job get them from Netdata and save them at your web server at regular intervals.

Embedding badges in github

You have 2 options a) SVG images with markdown and b) SVG images with HTML (directly in .md files).

For example, this is the cpu badge shown above:

[![A nice name](https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25)](https://registry.my-netdata.io/#apps_cpu)
<a href="https://registry.my-netdata.io/#apps_cpu">
    <img src="https://registry.my-netdata.io/api/v1/badge.svg?chart=users.cpu&dimensions=root&value_color=grey:null%7Cgreen%3C10%7Cyellow%3C20%7Corange%3C50%7Cblue%3C100%7Cred&label=root%20user%20cpu%20now&units=%25"></img>
</a>

Both produce this:

auto-refreshing badges in github

Unfortunately it cannot be done. Github fetches all the images using a proxy and rewrites all the URLs to be served by the proxy.

You can refresh them from your browser console though. Press F12 to open the web browser console (switch to the console too), paste the following and press enter. They will refresh:

var len = document.images.length; while(len--) { document.images[len].src = document.images[len].src.replace(/\?cacheBuster=\d*/, "") + "?cacheBuster=" + new Date().getTime().toString(); };

analytics