Introduction

Purpose

This is functional specification for Syslog Enhacements feature of Cloudstack.

References

https://issues.apache.org/jira/browse/CLOUDSTACK-712

Useful Links

Brief Introduction to Syslog

Use cases

Syslog messages can be used by remote Syslog managers   to diagnose issues in managed software/systems like Cloudstack CloudStack and can act accordingly. This is similar to alerts that we see on dashboard of CloudstackCloudStack.

1. Admin will set the IP of remote Syslog hosts through Cloudstack CloudStack configuration file, log4j-cloud.xml and those remote Syslog Hosts  will start getting Syslog alert messages then.
2. Admin can  delete the Syslog Hosts by removing them from configuration file

Feature Specifications

With this feature the plan is to generate Syslog messages for all the supported alerts in CloudStack. This feature will be in sync with the SNMP feature(proposed) on the alerts/events that will be generated bythe by the CloudStack system. Currently CloudStack generates following alerts/events, these events/alerts are persistent in the CloudStack database and exposed via CS API/UI.

...

1. alertType
2. message
3. podId
4. dataCenterId
5. clusterId

Message structure for Syslog messages will be as follows

Date severity_level Management_Server_IP_Address/Name  alertType:: value dataCenterId:: value  podId:: value  clusterId:: value  message:: value

...

For this feature, we will be using log4j library with Apache License

Severity Level Categorization

Below Alert Types are categorized as CRITICAL

1. host
2. userVmState 
3. domainRouterVmState
4. consoleProxyVmState
5. storageIssueSystemVms
6. ssvmStopped
7. usageServerResult
8. usageServerStatus
9. domainRouterMigrate
10. consoleProxyMigrate
11. routingConnection

while all others are categorized as WARN

Architecture and Design description

This feature will be implemented as plugin. This feature will use the log4j Appender to get the required alerts and will generate the Syslog  messages from that. SyslogAppender of log4j will be used to send the Syslog messages

Classes

We will add following classes

• AlertsSyslogAppender contains mainly two methods
  • append(LoggingEvent) : sends the Syslog message to the configured Syslog Hosts using SyslogAppender class
  • setSyslogAppenders() : sets the Syslog Appenders  to whom for each different Syslog Host

Changes in log4j-cloud.xml

To configure multiple Syslog Hosts following appender in log4j-cloud.xml will be added

...

   <logger name="com.cloud.alert.AlertManagerImpl" additivity="false">
      <level value="WARN"/>
      <appender-ref ref="SYSLOG"/>
      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="FILE"/>
      <appender-ref ref="ALERTSYSLOG"/>
   </logger>
   <logger name="com.cloud.usage.UsageAlertManagerImpl" additivity="false">
      <level value="WARN"/>
      <appender-ref ref="SYSLOG"/>
      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="FILE"/>
      <appender-ref ref="ALERTSYSLOG"/>
   </logger>

UI flow

There will be no UI/API in this feature