feat: enhance configuration files with detailed comments for better clarity (#3706)

Author: icey-yu

config/alertmanager.yml

@@ -1,34 +1,36 @@
+# Global Alertmanager runtime and SMTP settings.
 global:
-  resolve_timeout: 5m
-  smtp_from: alert@openim.io
-  smtp_smarthost: smtp.163.com:465
-  smtp_auth_username: alert@openim.io
-  smtp_auth_password: YOURAUTHPASSWORD
-  smtp_require_tls: false
-  smtp_hello: xxx
+  resolve_timeout: 5m # Wait time before an alert is considered resolved when no further updates are received.
+  smtp_from: alert@openim.io # Sender address displayed in alert emails.
+  smtp_smarthost: smtp.163.com:465 # SMTP relay endpoint in host:port format.
+  smtp_auth_username: alert@openim.io # SMTP authentication username (commonly the same as smtp_from).
+  smtp_auth_password: YOURAUTHPASSWORD # SMTP authorization token or app password.
+  smtp_require_tls: false # Set to true when your SMTP provider requires STARTTLS.
+  smtp_hello: xxx # HELO/EHLO identity presented to the SMTP server.
 
 templates:
-  - /etc/alertmanager/email.tmpl
+  - /etc/alertmanager/email.tmpl # Go template file used to render HTML email content.
 
+# Root routing tree for all incoming alerts.
 route:
-  group_by: [ 'alertname' ]
-  group_wait: 5s
-  group_interval: 5s
-  repeat_interval: 5m
-  receiver: email
+  group_by: [ 'alertname' ] # Alerts sharing this label value are batched into one notification.
+  group_wait: 5s # Initial delay before sending the first notification for a new alert group.
+  group_interval: 5s # Minimum interval between notifications for the same alert group.
+  repeat_interval: 5m # Reminder interval while an alert group remains firing.
+  receiver: email # Default receiver when no child route matches.
   routes:
     - matchers:
-        - alertname = "XXX"
-      group_by: [ 'instance' ]
+        - alertname = "XXX" # Example matcher; replace with a real alert name or remove this route.
+      group_by: [ 'instance' ] # Override grouping for this specific route.
       group_wait: 5s
       group_interval: 5s
       repeat_interval: 5m
       receiver: email
 
 receivers:
-  - name: email
+  - name: email # Receiver name referenced by route.receiver.
     email_configs:
-      - to: 'alert@example.com'
-        html: '{{ template "email.to.html" . }}'
-        headers: { Subject: "[OPENIM-SERVER]Alarm" }
-        send_resolved: true
+      - to: 'alert@example.com' # Recipient mailbox for alert notifications.
+        html: '{{ template "email.to.html" . }}' # Rendered with the template declared in email.tmpl.
+        headers: { Subject: "[OPENIM-SERVER]Alarm" } # Custom email subject line.
+        send_resolved: true # Also send a notification when the alert recovers.

config/email.tmpl

@@ -1,3 +1,6 @@
+{{/* OpenIM Alertmanager email template.
+This template renders both firing and resolved alerts.
+Each alert entry reads labels and annotations from Prometheus rule definitions. */}}
 {{ define "email.to.html" }}
 {{ if eq .Status "firing" }}
     {{ range .Alerts }}

config/instance-down-rules.yml

@@ -1,41 +1,42 @@
+# Default Prometheus alert groups for OpenIM.
 groups:
-  - name: instance_down
+  - name: instance_down # Fires when a monitored target remains unreachable.
     rules:
       - alert: InstanceDown
-        expr: up == 0
-        for: 1m
+        expr: up == 0 # The built-in "up" metric is 0 when the latest scrape fails.
+        for: 1m # Trigger only if the condition remains true for more than 1 minute.
         labels:
-          severity: critical
+          severity: critical # Used by Alertmanager for routing and notification priority.
         annotations:
           summary: "Instance {{ $labels.instance }} down"
-          description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 1 minutes."
+          description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 1 minute."
 
-  - name: database_insert_failure_alerts
+  - name: database_insert_failure_alerts # Detects failures when persisting messages to Redis or MongoDB.
     rules:
       - alert: DatabaseInsertFailed
-        expr: (increase(msg_insert_redis_failed_total[5m]) > 0) or (increase(msg_insert_mongo_failed_total[5m]) > 0)
-        for: 1m
+        expr: (increase(msg_insert_redis_failed_total[5m]) > 0) or (increase(msg_insert_mongo_failed_total[5m]) > 0) # Any positive increase indicates write failures occurred in the last 5 minutes.
+        for: 1m # Avoid firing on very short spikes.
         labels:
           severity: critical
         annotations:
           summary: "Increase in MsgInsertRedisFailedCounter or MsgInsertMongoFailedCounter detected"
-          description: "Either MsgInsertRedisFailedCounter or MsgInsertMongoFailedCounter has increased in the last 5 minutes, indicating failures in message insert operations to Redis or MongoDB,maybe the redis or mongodb is crash."
+          description: "Either MsgInsertRedisFailedCounter or MsgInsertMongoFailedCounter increased in the last 5 minutes, indicating message insert failures to Redis or MongoDB and a possible backend outage."
 
-  - name: registrations_few
+  - name: registrations_few # Operational early-warning rule for unusually low login/registration activity.
     rules:
       - alert: RegistrationsFew
-        expr: increase(user_login_total[1h]) == 0
+        expr: increase(user_login_total[1h]) == 0 # No successful login/registration events observed in 1 hour.
         for: 1m
         labels:
           severity: info
         annotations:
           summary: "Too few registrations within the time frame"
           description: "The number of registrations in the last hour is 0. There might be some issues."
 
-  - name: messages_few
+  - name: messages_few # Operational early-warning rule for unusually low messaging activity.
     rules:
       - alert: MessagesFew
-        expr: (increase(single_chat_msg_process_success_total[1h])+increase(group_chat_msg_process_success_total[1h])) == 0
+        expr: (increase(single_chat_msg_process_success_total[1h])+increase(group_chat_msg_process_success_total[1h])) == 0 # No successful single or group messages observed in 1 hour.
         for: 1m
         labels:
           severity: info

config/openim-api.yml

@@ -8,7 +8,7 @@ api:
 
 
 prometheus:
-  # Whether to enable prometheus
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # autoSetPorts indicates whether to automatically set the ports
   autoSetPorts: true

config/openim-msggateway.yml

@@ -9,7 +9,7 @@ rpc:
   ports:
 
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # List of ports that Prometheus listens on; these must match the number of rpc.ports to ensure correct monitoring setup
   # It will only take effect when autoSetPorts is set to false.

config/openim-msgtransfer.yml

@@ -1,5 +1,5 @@
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # autoSetPorts indicates whether to automatically set the ports
   autoSetPorts: true

config/openim-push.yml

@@ -28,7 +28,7 @@ circuitBreaker:
   request: 500 # Request threshold; circuit breaker evaluation occurs when reached
 
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: false
   # List of ports that Prometheus listens on; these must match the number of rpc.ports to ensure correct monitoring setup
   # It will only take effect when autoSetPorts is set to false.

config/openim-rpc-auth.yml

@@ -11,7 +11,7 @@ rpc:
   ports:
 
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # List of ports that Prometheus listens on; these must match the number of rpc.ports to ensure correct monitoring setup
   # It will only take effect when autoSetPorts is set to false.

config/openim-rpc-conversation.yml

@@ -11,7 +11,7 @@ rpc:
   ports:
 
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # List of ports that Prometheus listens on; these must match the number of rpc.ports to ensure correct monitoring setup
   # It will only take effect when autoSetPorts is set to false.

config/openim-rpc-friend.yml

@@ -11,7 +11,7 @@ rpc:
   ports:
 
 prometheus:
-  # Enable or disable Prometheus monitoring
+  # Enable Prometheus metrics exposure for this service; set to true to allow scraping.
   enable: true
   # List of ports that Prometheus listens on; these must match the number of rpc.ports to ensure correct monitoring setup
   # It will only take effect when autoSetPorts is set to false.