Sign in Start free

Monitor the certificates of hosts you call

Every outbound HTTPS host your API calls is checked once a day, with its full chain, and you are alerted before a certificate expires or a renewal breaks.

This page as Markdown

When a vendor’s TLS certificate expires, or they renew it and forget the intermediate, every call your API makes to them starts failing. Certificate monitoring watches for that. Every outbound HTTPS host your API calls is added automatically, its certificate and the full chain the server sends are checked about once a day, and you are alerted before the certificate expires or when a renewal goes wrong.

There is nothing to install or turn on. Monitoring starts with the first HTTPS call your API makes to a host.

Before you begin

  • Plan: your plan includes Certificate monitoring. A plan can limit how many hosts are monitored at once.
  • SDK: hosts are found from the outbound calls the SDK records (see Outbound requests), and from http.out spans when APM is installed. A span counts only when it says the call was HTTPS, which older SDK versions don’t record.
  • Roles: anyone on the team can see certificates and re-check a host. Adding a host, pausing, ignoring, resuming, Always monitor, the vendor contact and the reminders are for account owners and admins.

How hosts are found

The first time your API makes an HTTPS call to a host, the host is added to the list and checked within seconds. After that, it is checked again about every 24 hours.

  • Only public hostnames. IP addresses, single-label names and internal names (under .local, .internal, .svc and similar) are never added.
  • Ports. Traffic adds port 443 and any port from 1024 up. System service ports (SSH, mail and the like) are never checked because of traffic alone.
  • The 30-day window. A host is monitored while it has had a request in the last 30 days. After 30 quiet days it shows as Not monitored and is no longer checked; the next request brings it back. Turn on Always monitor to keep checking a host your API calls rarely, such as a vendor used once a quarter.

Certificates are account-wide: one host’s certificate serves every bucket that calls it.

The Certificates page

Select Certificates in the All buckets menu (choose All buckets at the top of any bucket’s sidebar). The list shows each host with its status, its chain status, when the certificate expires, the issuer, when it was last checked, the last request to it and the vendor you saved for it. The soonest expiry is first.

Filter the list with the buttons above it:

Filter Shows
Monitored Every host being checked (the default).
Expiring in 7 days Certificates that expire within a week.
Expired / Invalid Certificates that have expired, or that clients reject.
Chain issues Hosts whose chain has a problem (see Chain analysis).
Can’t reach Hosts our network could not connect to.
Always monitor Every host with Always monitor on, including paused ones.
Paused or ignored Hosts an admin paused or ignored.
Over plan limit Hosts not checked because the account is over its plan’s limit.
Not monitored (no requests in 30 days) Hosts outside the 30-day window.

Turn on Group by certificate to see one row per certificate with every host that serves it. Many hosts often share one certificate, and alerts are sent per certificate, not per host.

Statuses

Status Meaning
Valid The certificate is trusted and not close to expiry.
Expiring It expires soon.
Expired It has expired.
Invalid Clients reject it, for example because the name doesn’t match.
Can’t reach from our network Three checks in a row could not connect. Vendors often allow only their customers’ addresses, so this never alerts. Expiry alerts keep working from the last certificate seen.
Not checked yet The first check hasn’t run.

Add a host by hand

Hosts your API calls are added on their own. Add one by hand to watch it before any traffic reaches it, or to keep a rarely called vendor monitored.

Open Add host

On the Certificates page, select Add host.

Enter the host

Enter the Hostname, such as api.vendor.com, and the Port. Hosts added by hand can use port 443, 8443, 4443, 9443 or 10443. Other ports are added from your traffic.

Choose Always monitor

Tick Always monitor to keep checking the host even without requests. Otherwise a host added by hand counts as called on the day you add it, so it is monitored for 30 days and then only while it gets traffic.

Select Add

The certificate is checked within 15 minutes.

A host added by hand counts toward your plan’s monitored host limit, like any other.

One host’s details

Select a host to see:

  • Chain: each certificate in the chain, from the server’s certificate up to the root, and where it came from: Sent by server, Extra download (the server didn’t send it, so a client has to fetch it) or In trust store.
  • What is wrong, and the fix: each problem found, in plain words, with what the vendor should do about it.
  • History: a row each time the certificate, its chain or its status changed.
  • Certificate: the common name, the other names it is valid for, the issuer, the validity dates, whether the hostname matches, the signature, the TLS version, the address checked, the serial, the SHA-256 fingerprint and when the next check is due.
  • Where it is used: when the host was first seen and last called, and the other hosts on the same certificate.
  • Vendor contact: the vendor’s name, a contact (email, URL or phone), their status page and notes. These are included in alerts about the host, so whoever is on call knows who to tell.

The buttons at the top:

Button What it does
Re-check now Checks the certificate straight away. Within 5 minutes of the last check, it shows the last result instead.
Always monitor Keeps checking the host without requests.
Pause Stops checks and alerts until you resume it.
Ignore Stops checks and alerts, and traffic won’t add the host again.
Resume Starts checking a paused, ignored or over-limit host again. A host with no requests in 30 days needs Always monitor to be resumed.
Remove Deletes a host you added by hand.

Chain analysis

Each check records exactly what the server sends, builds the chain a standard client builds against the Mozilla trust store, and names anything missing. When an intermediate certificate is missing, the page names it and shows the address the certificate authority publishes it at.

Chain status Meaning
Complete A complete, correctly ordered chain to a trusted root.
Out of order The certificates arrive in the wrong order. Most clients cope; some older ones don’t.
Incomplete An intermediate certificate isn’t sent. Browsers often cope, but many API clients fail.
Wrong intermediate A new certificate was installed with an old or unrelated intermediate.
Untrusted root The chain doesn’t lead to a root clients trust by default, such as a private certificate authority.
Intermediate expired / Intermediate expiring An intermediate expires before the certificate itself, or already has.
Not a server certificate The certificate isn’t issued for TLS servers.
Weak A certificate is signed with SHA-1 or MD5, or uses a key below 2048-bit RSA or 256-bit EC.

A server that only speaks TLS 1.3 encrypts the chain it sends, so the chain is rebuilt from the handshake. Its order and any extra certificates can’t be judged, and the page says so.

When one of your API’s outbound calls fails with a certificate error, the host is re-checked straight away (at most once an hour per host).

Alerts

Certificate alerts are incidents like any other, sent through your alert routing. Until you set up routes, the default route emails account owners and admins, so the 7-day warning reaches someone without any setup.

There is one alert per problem per certificate, listing every host that serves it, never one per host. Each alert says what to ask the vendor and includes the vendor contact you saved.

Alert When Severity
Expiry 7 days before the certificate, or an intermediate in its chain, expires Warning, then critical at 1 day and once expired
Reminder 30 and 14 days before expiry, when turned on Info, sent in the digest
Chain A chain problem appears on a host Critical when it appeared after the host’s first check. Warning when it was there from the first check (it evidently works for you), or when the chain is only weak
Invalid Clients reject the certificate for a reason the chain doesn’t explain Critical

An alert resolves on its own when the certificate is renewed or the chain is fixed, or when the host is paused, ignored, removed or stops getting traffic.

Early reminders

The 7-day warning and the 1-day critical alert are always on. The earlier reminders are optional:

  1. On the Certificates page, find the Expiry alerts card.
  2. Tick 30 days before expiry, 14 days before expiry, both or neither.

Only owners and admins can change reminders. They apply to the whole account.

Plan limits

Your plan sets how many hosts can be monitored at once. A downgrade is never refused because of monitored hosts. Once it takes effect, the hosts with the oldest traffic beyond the limit show as Over plan limit and are no longer checked (hosts with Always monitor are the last to be limited). When there is room again, after an upgrade or once other hosts go quiet, they come back on their own, most recently called first.