Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add badges #1119

Merged
merged 27 commits into from
May 7, 2022
Merged

Add badges #1119

merged 27 commits into from
May 7, 2022

Conversation

jensneuber
Copy link
Contributor

@jensneuber jensneuber commented Jan 3, 2022

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:
image

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

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

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>
image

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

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>

image

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

image

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

image

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

image

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

image

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:
image

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)

image

@jensneuber jensneuber changed the title add badges Add badges Jan 3, 2022
@jensneuber jensneuber mentioned this pull request Jan 4, 2022
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
Copy link
Contributor Author

jensneuber commented Jan 4, 2022

@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
Copy link

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

@jensneuber
Copy link
Contributor Author

jensneuber commented Jan 4, 2022

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

server/config.js Outdated
module.exports = {
args,
demoMode
demoMode,
badgeConstants
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
badgeConstants
badgeConstants,

Copy link
Contributor Author

@jensneuber jensneuber Jan 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

downLabel = "Down",
upColor = badgeConstants.defaultUpColor,
downColor = badgeConstants.defaultDownColor,
style = "flat",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@jensneuber jensneuber Jan 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Collaborator

chakflying commented Jan 5, 2022

image
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
Copy link
Owner

louislam commented Jan 5, 2022

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
Copy link
Contributor Author

@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.

@louislam louislam linked an issue Jan 5, 2022 that may be closed by this pull request
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
server/routers/api-router.js Outdated Show resolved Hide resolved
@jensneuber
Copy link
Contributor Author

jensneuber commented Jan 7, 2022

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!

# Conflicts:
#	server/util-server.js
@louislam louislam merged commit e488e2d into louislam:master May 7, 2022
@louislam
Copy link
Owner

louislam commented May 7, 2022

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
Copy link
Contributor Author

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
Copy link
Contributor

MrEddX commented Jun 22, 2022

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
Copy link
Contributor Author

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
Copy link

t3cneo commented Oct 23, 2022

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
Copy link
Contributor Author

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
Copy link

t3cneo commented Oct 25, 2022

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
Copy link

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
Copy link
Collaborator

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

@GOATpotts
Copy link

Okay I got it, thanks.

@wortkrieg
Copy link

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
Copy link

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

@cypher-grignote
Copy link

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.

image

@louislam louislam mentioned this pull request Jan 17, 2024
17 tasks
mccrossen added a commit to mccrossen/uptime-kuma-wiki that referenced this pull request Feb 25, 2024
mccrossen added a commit to mccrossen/uptime-kuma-wiki that referenced this pull request Feb 25, 2024
louislam pushed a commit to louislam/uptime-kuma-wiki that referenced this pull request Apr 5, 2024
* 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 <[email protected]>

* delete counting badges

Co-authored-by: Frank Elsinga <[email protected]>

* Tip Open Badge Generator

Co-authored-by: Frank Elsinga <[email protected]>

* Delete Screenshots

* Reorder whole content

* Delete Example Image

* Update Badge.md

delete ref pull

Co-authored-by: Frank Elsinga <[email protected]>

* Update Badge.md

delete headline open Badge Generator

Co-authored-by: Frank Elsinga <[email protected]>

* Update Badge.md

Change Sentence about the predefined or custom color

Co-authored-by: Frank Elsinga <[email protected]>

* Update Badge.mf

Change the appearance of all examples

Co-authored-by: Frank Elsinga <[email protected]>

* Update Badge.md

delete file inline Table of content

Co-authored-by: Frank Elsinga <[email protected]>

* Update Badge.md

Correction of the tables with examples

* Update Badge.md

Correct Markdown Typo

Co-authored-by: Frank Elsinga <[email protected]>

---------

Co-authored-by: Frank Elsinga <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Badges