3 Badge
Marcel Debray edited this page 2024-04-05 06:28:05 +02:00

(Version >= 1.16.0)

Description

status, ping, uptime, avg-response, cert-exp and response-badges are generated locally. The server does this for all monitors which have been added to status pages and have thus been published. The design is based on badge-maker aka. shields.io.

These are the endpoints that return an SVG graphic for a given (public) monitor:

Badge Type URL scheme URL example Graphic example
status <kuma-url>/api/badge/:monitorID/status <kuma-url>/api/badge/1/status image
uptime <kuma-url>/api/badge/:monitorID/uptime:duration <kuma-url>/api/badge/1/uptime image
ping <kuma-url>/api/badge/:monitorID/ping:duration <kuma-url>/api/badge/1/ping image
avg-response <kuma-url>/api/badge/:monitorID/avg-response:duration <kuma-url>/api/badge/1/avg-response image
cert-exp <kuma-url>/api/badge/:monitorID/cert-exp <kuma-url>/api/badge/1/cert-exp image
response <kuma-url>/api/badge/:monitorID/response <kuma-url>/api/badge/1/response image

Tip

We have an Badge Generator integrated which makes this configuration more interactive.

You can use said generator via:

  • navigating to a status page in edit mode

  • Clicking on the settings icon

    image

  • Clicking on the Open Badge Maker-button

    image

  • filling out the form to create your own badge

    image

Badge Type Options

Status badge

There are options to customize the status badge's appearance:

  • upLabel,Default value: Up
  • downLabel, Default value: Down
  • upColor
  • downColor

Examples

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

Ping, uptime, avg-response and response badge

There are options to customize the ping, uptime, avg-response and response badge's text:

  • labelPrefix
  • label
  • labelSuffix, Default: value: uptime, ping & avg-response image= h
  • prefix
  • suffix, Default value: uptime= %, ping, avg-response & response= ms
  • color
  • labelColor

Examples

Badge Url
image <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>
<kuma-url>/api/badge/<monitorId>/avg-response/24?labelPrefix=<labelPrefix>&label=<label>&labelSuffix=<labelSuffix>&prefix=<prefix>&suffix=<suffix>

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

Badge Duration at ping, uptime and avg-response

The given time interval at Badge Duration (in hours) has to be in 'hours', but customizing options allow for a different display:

Example

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

Certificate Expire badge

There are the same options like ping, uptime and avg-response and additional to customize the cert-exp badge's text:

  • upColor
  • downColor
  • warnDays
  • downDays

Badge Styles

The different badge styles as defined by https://shields.io/#styles. (thx @throwabird / comment )

  • flat (default)
  • flat-square
  • plastic
  • for-the-badge
  • social

Example

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