Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polystack.tech/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This page covers the most common issues encountered when using Monitoring — from alert rules that fail to fire, to dashboards showing no data, to missing or delayed logs.
Prerequisites
  • An active Polystack account with project access
  • For agent and infrastructure-level issues, contact your monitoring administrator. Your administrator can configure this through the deployment console.

​
Common Issues

Cause: The evaluation period has not elapsed, the notification channel is misconfigured, or the alert rule is in a silenced state.Resolution:
  1. Verify the rule’s evaluation period — the condition must persist for the full duration before the alert fires:
    Check alert rule configuration
    monitoring alert rule show <RULE_NAME>
  2. Check Monitor Center > Monitoring (Alert Channels, admin view) to confirm the notification channel is active and credentials are valid
  3. Check Monitor Center > Monitoring (Silences, admin view) — confirm no active silence covers the alert:
    List active silences
    monitoring alert silence list --status active
  4. Verify the metric has data in the time window — navigate to the Dashboards and check whether the metric panel shows values above the threshold
An alert rule evaluating polystack_compute_cpu_utilization > 90 will only fire if the metric is above 90% for the ENTIRE evaluation period. Brief spikes that resolve within the period will not trigger the alert.
Cause: The monitoring agent on the target host is not running, or the host is not registered with Monitoring.Resolution:
Check agent registration
monitoring agent list --status all
Look for hosts with status offline or unknown. If metrics are missing, contact your administrator. They can verify the monitoring agent status through the deployment console.
Cause: Log collector is not configured for the service, the log file path has changed, or the collector is experiencing a backlog.Resolution:
  1. Navigate to Monitor Center > Logging (Log Sources, admin view) and verify the log source configuration for the affected service
  2. Confirm the file path pattern matches the current log file location
  3. Check the collector queue depth:
    Check ingestion queue depth
    monitoring log ingest-status
Log ingestion uses file-based collection. If a service rotates logs to a new path after an update, the collector configuration must be updated to match. Contact your monitoring administrator to update log source configurations. Your administrator can configure this through the deployment console.
Cause: The scrape target is down, the agent is offline, or the metric name has changed after a software update.Resolution:
  1. Check the target health: navigate to Monitor Center > Monitoring (Scrape Targets, admin view) and look for targets in DOWN state
  2. Verify the agent is active for that host:
    Check agent status
    monitoring agent list --node <HOSTNAME>
  3. Search for the metric to verify it exists and find the correct name:
    Search metrics by prefix
    monitoring metric search --prefix polystack_compute_cpu
Cause: The notification channel configuration is invalid, credentials have expired, or the destination is temporarily unreachable.Resolution:
  1. Navigate to Monitor Center > Monitoring (Alert Channels, admin view) and use the Test button to send a test notification
  2. If the test fails, review the channel configuration:
    Check channel configuration
    monitoring alert channel show <CHANNEL_NAME>
  3. For email channels: verify SMTP credentials and server reachability
  4. For webhook channels: verify the URL is accessible from the Monitoring server
  5. For PagerDuty: verify the integration key has not been rotated
Send a test notification immediately after creating or modifying a channel. Do not rely on a real alert event to discover that a channel is broken.

​
Diagnostics Reference

IssueFirst Step
Alert not firingmonitoring alert rule show <RULE_NAME>
Agent offlineContact your administrator to verify agent status via the deployment console
Missing metricmonitoring metric search --prefix <METRIC_PREFIX>
Log ingestion backlogmonitoring log ingest-status
Channel testUse Test button in Dashboard or monitoring alert channel test <NAME>

​
When to Contact Your Administrator

Contact your monitoring administrator if any of the following persist. Your administrator can configure this through the deployment console.
  • A host does not appear in monitoring agent list after restarting the agent service
  • All metrics are missing for multiple hosts simultaneously
  • Log ingestion queue depth has been growing for more than 1 hour
  • TLS certificate errors prevent agent communication
See the Monitoring Admin Guide for administrator-level diagnostics and configuration.

​
Next Steps

Monitoring Admin Guide

Infrastructure-level Monitoring administration and agent configuration

Metrics & Alerts

Review and adjust alert rule configurations

Dashboards

Verify metric availability in dashboard panels

Support

Contact Polystack support for issues requiring platform-level investigation