Add badges #1119

jensneuber · 2022-01-03T15:31:20Z

Description

Status, ping and uptime badges, generated in node-js, no internet access required (based on badge-maker aka. shields.io)

This PR adds three API endpoints returning a SVG graphic for a given (public) monitor:

Status
<kuma-url>/api/badge/:monitorID/status e.g. <kuma-url>/api/badge/1/status returning sth like:

Ping
<kuma-url>/api/badge/:monitorID/ping/:duration e.g. <kuma-url>/api/badge/1/ping returning sth like:

Uptime
<kuma-url>/api/badge/:monitorID/uptime/:duration e.g. <kuma-url>/api/badge/1/uptime/24 returning sth like:

Status badge

There are options to customize the status badge's appearance: upLabel = Up, downLabel = Down, upColor, downColor:

<kuma-url>/api/badge/<monitorId>/status?upLabel=<upLabel>&downLabel=<downLabel>

<kuma-url>/api/badge/<monitorId>/status?upColor=white&downColor=black

Ping and uptime badge

There are options to customize the ping and uptime badge's text: labelPrefix, label, labelSuffix = h, prefix, suffix = ms / %, color, labelColor:

<kuma-url>/api/badge/<monitorId>/ping/24?labelPrefix=<labelPrefix>&label=<label>&labelSuffix=<labelSuffix>&prefix=<prefix>&suffix=<suffix>

<kuma-url>/api/badge/<monitorId>/uptime/24?labelPrefix=<labelPrefix>&label=<label>&labelSuffix=<labelSuffix>&prefix=<prefix>&suffix=<suffix>

The given time interval has to be in 'hours', but customizing options allow for a different display:
<kuma-url>/api/badge/1/uptime/720?label=30&labelSuffix=d

The default uptime badge's color is based on the uptime percentage:

but can be overwritten with predefined color or any other color in HEX code:

See https://shields.io/#colors for predefined colors.

Different badge styles as defined by https://shields.io/#styles are also supported. (thx @throwabird / comment )

<kuma-url>/api/badge/<monitorId>/status?style=flat-square

Use of the following options to enable them: flat (default), flat-square, plastic, for-the-badge, social:

Type of change

User Interface (?)
New feature (non-breaking change which adds functionality)
This change requires a documentation update

Checklist

My code follows the style guidelines of this project
I ran ESLint and other linters for modified files
I have performed a self-review of my own code and test it
I have commented my code, particularly in hard-to-understand areas
My changes generate no new warnings
My code needed automated testing. I have added them (this is optional task)

Screenshots (if any)

… uptime-badges

server/routers/api-router.js

jensneuber · 2022-01-04T11:56:15Z

@Saibamen Thx for your feedback!
I updated the code and added some features: status and ping badges, as well as color options for the uptime badge.

throwabird · 2022-01-04T12:18:28Z

Quick Quesion: Will the Uptime Kuma API support all the url parameters from shields.io? for example https://shields.io/#styles ?

jensneuber · 2022-01-04T12:39:06Z

Quick Quesion: Will the Uptime Kuma API support all the url parameters from shields.io? for example shields.io/#styles ?

Shouldn't be a problem, ~~though it's not implemented yet.~~ done

Saibamen · 2022-01-04T13:38:43Z

server/config.js

 module.exports = {
    args,
-    demoMode
+    demoMode,
+    badgeConstants


Suggested change

badgeConstants

badgeConstants,

Is a dangling comma sth you would like to see everywhere ( multiline )?
I was trying to stick to the current code style ... and will adjust my code :)

Saibamen · 2022-01-04T13:39:49Z

server/routers/api-router.js

+        downLabel = "Down",
+        upColor = badgeConstants.defaultUpColor,
+        downColor = badgeConstants.defaultDownColor,
+        style = "flat",


style = "flat", is repeated 3 times in this file

Well, there are several code blocks that share similarities / repeat themselves.
Would you like to see a constant here as well or a more sophisticated routing approach in which 'ping' and 'uptime' share a route? Since style is a query parameter it has to be repeated in every 'badge'-route.

chakflying · 2022-01-05T03:05:16Z

Looks like we need some rounding on the percentage

This also has the unfortunate effect of tying the use of badges to the status page, i.e. the user has to add the monitor to the status page to be able to use it, which would be pretty confusing. But I'm not sure how we should handle this either. Should there be a setting for whether a monitor needs to be public for badges to work? Or should we change how setting a monitor as public is handled?

Thinking about this, since it's only a badge and doesn't give any information about what it's monitoring, maybe it's not that bad to have it available for all monitors by default?

louislam · 2022-01-05T06:33:55Z

Really nice!

However, since monitors could be private, granting a permission is needed.

My idea would be that badges could be generated or revoked on demand.

jensneuber · 2022-01-05T07:14:16Z

@chakflying Thanks for your feedback!
@louislam Thanks ❤️

[ chakflying ] Or should we change how setting a monitor as public is handled?

What about a checkbox on the monitors settings page, enabling badges or, more general, enabling public availability. This could effect metrics as well, since those are bound to the status page as well ( afaik ) and could / would be overridden once the monitor appears on the status page.

server/routers/api-router.js

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

jensneuber · 2022-01-07T10:48:49Z

How would you like to progress with this PR?
Do you think it is required to implement a new logic / ui to set a monitor public?
Or can we merge this PR as is ( managing public availability by adding the monitor to the status page) and deal with this requirement in a different PR? I would be happy to help with that!

… uptime-badges

# Conflicts: # server/util-server.js

louislam · 2022-05-07T05:44:26Z

Thank you so much, it is so solid.

My next steps will be adding your description in the wiki.

For the maybe next next release, badge gui generator should be added into status page editor, so users don't need to check the wiki.

jensneuber · 2022-05-07T14:22:33Z

For the maybe next next release, badge gui generator should be added into status page editor, so users don't need to check the wiki.

Great Idea! Maybe I can help.
I wanted to have a look into Vue anyway, since I am more of a React guy so far.

MrEddX · 2022-06-22T20:04:22Z

Great functionality!

@jensneuber Мaybe the URL example for 30 days uptime percentage that is shown in the example:

<kuma-url>/api/badge/1/720?label=30&labelSuffix=d

should be:

<kuma-url>/api/badge/1/uptime/720?label=30&labelSuffix=d

jensneuber · 2022-06-24T07:15:53Z

should be:
<kuma-url>/api/badge/1/uptime/720?label=30&labelSuffix=d

You are absolutely right! Thanks for noticing and letting me know

t3cneo · 2022-10-23T20:33:24Z

Hi guys, I'm not sure to understand how this works... Is the badge supposed to be update over time to reflect what's on the dashboard?
On my setup it seems to be generated when the url is called and is not updated over time, is it the expected behaviour?

jensneuber · 2022-10-24T10:15:28Z

This is expected behavior.

A badge is an image and includes no further logic to update.
The badge could be wrapped in a short piece of JS code to auto update, though.

t3cneo · 2022-10-25T07:43:13Z

Oh ok
I thought the svg would be generated everytime the url is called thus reflecting the given metric, wrong understanding of the feature sorry. Thanks for your feedback

GOATpotts · 2023-09-26T13:54:59Z

How do you change the status pages to show the badges in the UI? I see the settings option next to the monitor, and then the badge generator, however I cannot seem to find a way to make the badge show instead of the default percentage.

chakflying · 2023-09-26T14:06:37Z

There is no such option. The badges are designed to be displayed externally.

GOATpotts · 2023-09-26T14:07:16Z

Okay I got it, thanks.

wortkrieg · 2023-11-20T08:53:42Z

Great one. Is it a Bug or by design, that those badges don't work with Groups? I only see 'N/A' in the label when trying to access the status of a monitor group.

MikesTooLz · 2023-11-27T15:31:37Z

Can we get an option that returns a png instead of html?

cypher-grignote · 2024-01-17T14:01:32Z

How do you change the status pages to show the badges in the UI? I see the settings option next to the monitor, and then the badge generator, however I cannot seem to find a way to make the badge show instead of the default percentage.

You can display it in the status page description or footer using markdown.

For example : ![Services](https://status.page.com/api/badge/5/status?style=for-the-badge) but I didn't find how to modify the first label.

from this pull louislam/uptime-kuma#1119

* migrate badge documentation from pull into wiki from this pull louislam/uptime-kuma#1119 * Update badges documentation resolve comments from CommanderStorm * Update Badge.md * Apply suggestions from code review Co-authored-by: Frank Elsinga <frank@elsinga.de> * delete counting badges Co-authored-by: Frank Elsinga <frank@elsinga.de> * Tip Open Badge Generator Co-authored-by: Frank Elsinga <frank@elsinga.de> * Delete Screenshots * Reorder whole content * Delete Example Image * Update Badge.md delete ref pull Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update Badge.md delete headline open Badge Generator Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update Badge.md Change Sentence about the predefined or custom color Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update Badge.mf Change the appearance of all examples Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update Badge.md delete file inline Table of content Co-authored-by: Frank Elsinga <frank@elsinga.de> * Update Badge.md Correction of the tables with examples * Update Badge.md Correct Markdown Typo Co-authored-by: Frank Elsinga <frank@elsinga.de> --------- Co-authored-by: Frank Elsinga <frank@elsinga.de>

jensneuber added 4 commits January 3, 2022 15:48

add badges

35360e2

Merge branch 'master' of https://github.com/louislam/uptime-kuma into…

8b59976

… uptime-badges

a little documentation

1c5bce8

minor fixes

d74404e

jensneuber changed the title ~~add badges~~ Add badges Jan 3, 2022

jensneuber mentioned this pull request Jan 4, 2022

Badges #447

Closed

Saibamen suggested changes Jan 4, 2022

View reviewed changes

server/routers/api-router.js Outdated Show resolved Hide resolved

server/routers/api-router.js Outdated Show resolved Hide resolved

server/routers/api-router.js Outdated Show resolved Hide resolved

server/routers/api-router.js Outdated Show resolved Hide resolved

jensneuber added 2 commits January 4, 2022 12:21

add ping, status badge

3625915

PR feedback

7abbf42

add shields.io 'style' parameter

f455e3a

Saibamen reviewed Jan 4, 2022

View reviewed changes

jensneuber added 2 commits January 4, 2022 16:00

PR feedback + remove redundant code + add a test

6acc954

PR feedback

28c0e16

louislam linked an issue Jan 5, 2022 that may be closed by this pull request

Badges #447

Closed

clean uptime percentage display

df8f93f

Saibamen reviewed Jan 5, 2022

View reviewed changes

jensneuber and others added 5 commits January 5, 2022 15:25

PR feedback: remove spaces in comments

a9d264c

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

PR feedback: remove spaces in parenthesis

faf6719

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

PR feedback: remove spaces in parenthesis

4990425

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

PR feedback: remove spaces in parenthesis

43f8fc7

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

PR feedback: remove spaces in parenthesis

f00ec4d

Co-authored-by: Adam Stachowicz <saibamenppl@gmail.com>

Merge branch 'master' of https://github.com/louislam/uptime-kuma into…

28be32f

… uptime-badges

Merge branch 'master' into uptime-badges

4e32585

# Conflicts: # server/util-server.js

louislam merged commit e488e2d into louislam:master May 7, 2022

fbartels mentioned this pull request May 27, 2022

Ability to add status badges for specified websites #1084

Closed

1 task

rezzorix mentioned this pull request May 27, 2022

Badges: API showing N/A only #1700

Closed

2 tasks

jensneuber mentioned this pull request Jun 1, 2022

Feat: Badges generator #1712

Closed

6 tasks

Tealk mentioned this pull request Jan 17, 2023

Add badges maintenance label #2625

Closed

1 task

shukon mentioned this pull request Jan 25, 2023

Status Badge shows wrong message text when label is set #2673

Closed

2 tasks

kiznick mentioned this pull request Mar 10, 2023

Feat: Badge Generator #2915

Merged

7 tasks

aoudiamoncef mentioned this pull request Jun 28, 2023

Add provider table massalabs/docs#95

Merged

gs97ahn mentioned this pull request Aug 18, 2023

How can I figure out the monitorID #3597

Closed

2 tasks

Zir0h mentioned this pull request Oct 27, 2023

[feature] Add Tzkt status to the indexer warning teia-community/teia-ui#327

Open

louislam mentioned this pull request Jan 17, 2024

2.0.0 Checklist #4171

Closed

17 tasks

CommanderStorm mentioned this pull request Feb 17, 2024

v2.0.0-Release <- Read this for performance problems #4500

Open

16 tasks

mccrossen added a commit to mccrossen/uptime-kuma-wiki that referenced this pull request Feb 25, 2024

migrate badge documentation from pull into wiki

211d952

from this pull louislam/uptime-kuma#1119

mccrossen added a commit to mccrossen/uptime-kuma-wiki that referenced this pull request Feb 25, 2024

migrate badge documentation from pull into wiki

8fd9ec1

from this pull louislam/uptime-kuma#1119

mccrossen mentioned this pull request Feb 25, 2024

migrate badge documentation from pull into wiki louislam/uptime-kuma-wiki#83

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add badges #1119

Add badges #1119

jensneuber commented Jan 3, 2022 •

edited

Loading

jensneuber commented Jan 4, 2022 •

edited

Loading

throwabird commented Jan 4, 2022

jensneuber commented Jan 4, 2022 •

edited

Loading

Saibamen Jan 4, 2022

jensneuber Jan 4, 2022 •

edited

Loading

Saibamen Jan 4, 2022

jensneuber Jan 4, 2022 •

edited

Loading

chakflying commented Jan 5, 2022 •

edited

Loading

louislam commented Jan 5, 2022 •

edited

Loading

jensneuber commented Jan 5, 2022

jensneuber commented Jan 7, 2022 •

edited

Loading

louislam commented May 7, 2022

jensneuber commented May 7, 2022

MrEddX commented Jun 22, 2022

jensneuber commented Jun 24, 2022

t3cneo commented Oct 23, 2022

jensneuber commented Oct 24, 2022

t3cneo commented Oct 25, 2022

GOATpotts commented Sep 26, 2023

chakflying commented Sep 26, 2023

GOATpotts commented Sep 26, 2023

wortkrieg commented Nov 20, 2023

MikesTooLz commented Nov 27, 2023

cypher-grignote commented Jan 17, 2024

Add badges #1119

Add badges #1119

Conversation

jensneuber commented Jan 3, 2022 • edited Loading

Description

Status badge

Ping and uptime badge

Type of change

Checklist

Screenshots (if any)

jensneuber commented Jan 4, 2022 • edited Loading

throwabird commented Jan 4, 2022

jensneuber commented Jan 4, 2022 • edited Loading

Saibamen Jan 4, 2022

Choose a reason for hiding this comment

jensneuber Jan 4, 2022 • edited Loading

Choose a reason for hiding this comment

Saibamen Jan 4, 2022

Choose a reason for hiding this comment

jensneuber Jan 4, 2022 • edited Loading

Choose a reason for hiding this comment

chakflying commented Jan 5, 2022 • edited Loading

louislam commented Jan 5, 2022 • edited Loading

jensneuber commented Jan 5, 2022

jensneuber commented Jan 7, 2022 • edited Loading

louislam commented May 7, 2022

jensneuber commented May 7, 2022

MrEddX commented Jun 22, 2022

jensneuber commented Jun 24, 2022

t3cneo commented Oct 23, 2022

jensneuber commented Oct 24, 2022

t3cneo commented Oct 25, 2022

GOATpotts commented Sep 26, 2023

chakflying commented Sep 26, 2023

GOATpotts commented Sep 26, 2023

wortkrieg commented Nov 20, 2023

MikesTooLz commented Nov 27, 2023

cypher-grignote commented Jan 17, 2024

jensneuber commented Jan 3, 2022 •

edited

Loading

jensneuber commented Jan 4, 2022 •

edited

Loading

jensneuber commented Jan 4, 2022 •

edited

Loading

jensneuber Jan 4, 2022 •

edited

Loading

jensneuber Jan 4, 2022 •

edited

Loading

chakflying commented Jan 5, 2022 •

edited

Loading

louislam commented Jan 5, 2022 •

edited

Loading

jensneuber commented Jan 7, 2022 •

edited

Loading