Skip to content
Legend Docs

Link Health Monitoring

Link health monitoring automatically checks the availability of links attached to entities in your Legend instance. This feature helps you identify broken links, track link status over time, and maintain the quality of your organizational knowledge base.

Section titled “Accessing Link Health Monitoring”

To access link health monitoring:

  1. Click your user menu in the top-right corner
  2. Select Admin Panel from the dropdown
  3. Click Link Health in the admin sidebar

Only users in the Admins group can access link health monitoring and configure scan settings. All users can view link health status on entity cards.

Section titled “What Link Health Monitoring Does”

Link health monitoring periodically checks all links attached to entities (landmarks, people, teams) to verify they are accessible. For each link, Legend:

  1. Sends an HTTP HEAD request to the link URL
  2. Records the HTTP status code and response time
  3. Updates the link’s health status
  4. Logs the result for historical tracking

What is checked:

  • All links in the “links” field of entities
  • Links in entity documentation (if configured)
  • Navigation links and quick-access URLs

What is not checked:

  • Internal links between Legend entities
  • Links that are explicitly marked as “do not check”
  • Links on deactivated entities
Section titled “Link Status Types”

Each link has one of four health statuses:

Healthy: The link is accessible and responding normally

  • HTTP status code: 200-299
  • Response time: Under 10 seconds
  • Displayed with a green indicator

Broken: The link is not accessible or returning errors

  • HTTP status code: 400+ or connection failure
  • Response time: Timeout or error
  • Displayed with a red indicator

Unknown: The link status cannot be determined

  • Network errors, DNS failures, or SSL certificate issues
  • The link may be temporarily unavailable
  • Displayed with a gray indicator

Pending: The link has not been checked yet

  • Newly created links that haven’t been scanned
  • Links that are scheduled for the next scan
  • Displayed with a blue indicator

Configuring Scan Settings

Section titled “Configuring Scan Settings”

Administrators can configure how often link health checks run and how many links are checked per scan.

To configure scan settings:

  1. Navigate to Admin Panel > Link Health
  2. Click the Settings button
  3. Adjust the following settings:

Scan Interval: How often automatic scans run

  • Options: Every hour, Every 6 hours, Every 12 hours, Daily, Weekly
  • Default: Daily
  • More frequent scans provide faster detection but use more resources

Rate Limit: How many links are checked per scan

  • Options: 10, 25, 50, 100, 250, 500
  • Default: 50
  • Higher limits complete scans faster but may impact performance
  • Consider your server capacity and network bandwidth

Timeout: How long to wait for a link response

  • Options: 5 seconds, 10 seconds, 15 seconds, 30 seconds
  • Default: 10 seconds
  • Longer timeouts are more accurate but slower

Retry Failed Links: Whether to retry broken links

  • Options: Yes, No
  • Default: Yes
  • When enabled, broken links are rechecked on the next scan
  • Helps detect temporary outages
  1. Click Save to apply the settings
Section titled “Viewing Link Health Status”

The link health dashboard provides an overview of all links and their health status.

Summary statistics:

  • Total links monitored
  • Number of healthy links
  • Number of broken links
  • Number of unknown links
  • Number of pending links
  • Last scan time
  • Next scheduled scan time

Link list: The dashboard displays a list of all monitored links with:

  • Link URL
  • Entity name and type
  • Current status (healthy, broken, unknown, pending)
  • Last checked time
  • Response time (for healthy links)
  • Error message (for broken or unknown links)

Filtering and sorting:

  • Filter by status (healthy, broken, unknown, pending)
  • Filter by entity type (landmark, person, team)
  • Sort by URL, entity name, status, or last checked time
  • Search for specific links or entities

Triggering Manual Scans

Section titled “Triggering Manual Scans”

You can trigger a manual scan at any time to check all links immediately, rather than waiting for the next scheduled scan.

To trigger a manual scan:

  1. Navigate to Admin Panel > Link Health
  2. Click the Scan Now button
  3. Legend begins checking all links immediately
  4. The scan progress is displayed on the dashboard
  5. Results are updated as each link is checked

Manual scan behavior:

  • Scans all links, regardless of when they were last checked
  • Respects the configured rate limit
  • May take several minutes to complete for large instances
  • Does not affect the next scheduled scan time

When to trigger manual scans:

  • After importing a large number of entities with links
  • When investigating reported broken links
  • Before scheduled maintenance or migrations
  • To verify link status after network changes

Viewing Scan Results

Section titled “Viewing Scan Results”

Each scan generates detailed results that are stored for historical tracking.

Scan history:

  • Navigate to Admin Panel > Link Health
  • Click the History tab
  • View a list of all past scans with timestamps and summary statistics
  • Click on a scan to view detailed results

Detailed results: For each scan, you can see:

  • Total links checked
  • Links by status (healthy, broken, unknown)
  • Average response time
  • List of all checked links with their status and response details

Exporting results: You can export scan results to CSV for external analysis or reporting:

  1. Navigate to the scan history
  2. Click the Export button next to a scan
  3. The CSV file includes all link details and status information
Section titled “Understanding Broken Links”

When a link is marked as broken, it means the HTTP request failed or returned an error status code. Common causes include:

404 Not Found: The page or resource no longer exists

  • The URL may have changed
  • The resource may have been deleted
  • The URL may be incorrect

403 Forbidden: Access is denied

  • The resource may require authentication
  • The server may be blocking automated requests
  • IP-based restrictions may be in place

500 Server Error: The server encountered an error

  • The server may be experiencing issues
  • The error may be temporary
  • Contact the resource owner for assistance

Connection Timeout: The server did not respond

  • The server may be down
  • Network issues may be preventing access
  • The URL may be incorrect

SSL Certificate Error: The SSL certificate is invalid or expired

  • The certificate may need to be renewed
  • The certificate may be self-signed
  • The URL may be incorrect

DNS Resolution Failed: The domain name could not be resolved

  • The domain may no longer exist
  • DNS configuration may have changed
  • The URL may be incorrect
Section titled “Fixing Broken Links”

When you identify broken links, take action to fix them:

Update the URL:

  1. Open the entity that contains the broken link
  2. Edit the entity
  3. Update the link URL to the correct address
  4. Save the changes
  5. The link will be rechecked on the next scan

Remove the link:

  1. Open the entity that contains the broken link
  2. Edit the entity
  3. Remove the broken link
  4. Save the changes
  5. The link will no longer be monitored

Mark as “do not check”: If a link should not be monitored (e.g., internal links, links that require authentication):

  1. Open the entity that contains the link
  2. Edit the entity
  3. Add the link to the “do not check” list (if supported)
  4. Save the changes
  5. The link will be excluded from future scans

Contact the resource owner: If the broken link is an external resource you don’t control:

  1. Identify the resource owner or maintainer
  2. Contact them to report the broken link
  3. Request an updated URL or confirmation that the resource still exists
  4. Update the link when you receive a response

Best Practices

Section titled “Best Practices”

Regular Monitoring:

  • Review link health status weekly to catch broken links early
  • Set up alerts for critical links that must remain available
  • Assign responsibility for link maintenance to specific team members

Link Quality:

  • Use stable, permanent URLs when possible
  • Avoid linking to temporary or session-based URLs
  • Test links before adding them to entities
  • Document the purpose of each link in the entity description

Scan Configuration:

  • Start with daily scans and adjust based on your needs
  • Use a rate limit that balances speed and performance
  • Increase timeout for links that are known to be slow
  • Enable retry for broken links to detect temporary outages

Maintenance:

  • Fix or remove broken links promptly
  • Update links when resources move or change URLs
  • Remove links to resources that are no longer relevant
  • Periodically review all links for accuracy and relevance

Troubleshooting

Section titled “Troubleshooting”

Scans not running:

  • Verify automatic scans are enabled in the settings
  • Check that the scan interval is configured correctly
  • Review container logs for scan-related errors
  • Ensure the container has network access to check links

All links showing as broken:

  • Verify the container has outbound network access
  • Check firewall rules to ensure HTTP/HTTPS traffic is allowed
  • Review proxy settings if your environment uses a proxy
  • Test network connectivity from the container

Scans taking too long:

  • Reduce the rate limit to check fewer links per scan
  • Increase the scan interval to run scans less frequently
  • Reduce the timeout to fail faster on slow links
  • Review network performance and latency

False positives (healthy links marked as broken):

  • Increase the timeout to allow more time for slow links
  • Check if the server is blocking automated requests
  • Verify the link is accessible from the container’s network
  • Review error messages for specific issues

False negatives (broken links marked as healthy):

  • Check if the link returns a 200 status but displays an error page
  • Verify the link content is correct (not just the status code)
  • Consider using a more sophisticated health check (if supported)
  • Review the link manually to confirm it’s actually working

Next Steps

Section titled “Next Steps”

After configuring link health monitoring, proceed to Data Directory Structure to understand how Legend stores data, or Environment Variables Reference to review all configuration options.