Bug Reference
https://issues.apache.org/jira/browse/CLOUDSTACK-6256
Branch
4.4
Introduction
An event in cloudstack can be change in state (like create, edit, delete etc) of the resources, an action performed by the user (like login, logout etc ) or policy based events aka alerts. These events hold success or failure details of an event. Events for asynchronous jobs log when a job is scheduled, when it starts, and when it completes. While events for long running synchronous jobs log when it starts and when it completes.
Purpose
Currently the events logged in CloudStack doesn't give detailed information about the event that has occurred. The information provided in each event shown on the cloudstack ui doesn't provide specifics, particularly in case of errors. For example, the message shown on the cloudstack ui is just "Error while starting Vm. Vm Id: <id>" in case of failure to start a vm , which doesn't help much. Hence, the events should be enhanced to include more information to be descriptive enough.
Proposal
I would like to propose some changes to enhance the events to be more informative. Like:
- Instead of just showing resource database id in the event details it should display resource UUID. Since all the cloudstack apis take input as resource uuid it would be helpful to see the same on the ui as well.
- Enhance the events and listEvents API to include the resource UUID so that it can be queried by the resource UUID as well.
- Currently, the event description messages are specified in the *Cmd.java file instead, all of them should be externalize to a resource file. This would be helpful even for internationalization.
- Provide more detailed messages in case of error events. Messages such as "Error while starting VM" are generic to take any action.
Design description and changes
Currently all the cloudstack events are persisted into the cloud database in the event and event_view table.
mysql> desc event_view; mysql> desc event; +--------------+---------------------+------+-----+-----------+-------+ +-------------+---------------------+------+-----+-----------+----------------+ | Field | Type | Null | Key | Default | Extra | | Field | Type | Null | Key | Default | Extra | +--------------+---------------------+------+-----+-----------+-------+ +-------------+---------------------+------+-----+-----------+----------------+ | id | bigint(20) unsigned | NO | | 0 | | | id | bigint(20) unsigned | NO | PRI | NULL | auto_increment | | uuid | varchar(40) | YES | | NULL | | | uuid | varchar(40) | YES | UNI | NULL | | | type | varchar(32) | NO | | NULL | | | type | varchar(32) | NO | MUL | NULL | | | state | varchar(32) | NO | | Completed | | | state | varchar(32) | NO | | Completed | | | description | varchar(1024) | NO | | NULL | | | description | varchar(1024) | NO | | NULL | | | created | datetime | NO | | NULL | | | user_id | bigint(20) unsigned | NO | MUL | NULL | | | level | varchar(16) | NO | | NULL | | | account_id | bigint(20) unsigned | NO | MUL | NULL | | | parameters | varchar(1024) | YES | | NULL | | | domain_id | bigint(20) unsigned | NO | | NULL | | | start_id | bigint(20) unsigned | NO | | 0 | | | created | datetime | NO | MUL | NULL | | | start_uuid | varchar(40) | YES | | NULL | | | level | varchar(16) | NO | MUL | NULL | | | user_id | bigint(20) unsigned | NO | | NULL | | | start_id | bigint(20) unsigned | NO | | 0 | | | archived | tinyint(1) unsigned | NO | | 0 | | | parameters | varchar(1024) | YES | | NULL | | | user_name | varchar(255) | NO | | NULL | | | archived | tinyint(1) unsigned | NO | | 0 | | | account_id | bigint(20) unsigned | NO | | 0 | | +-------------+---------------------+------+-----+-----------+----------------+ | account_uuid | varchar(40) | YES | | NULL | | | account_name | varchar(100) | YES | | NULL | | | account_type | int(1) unsigned | NO | | NULL | | | domain_id | bigint(20) unsigned | NO | | 0 | | | domain_uuid | varchar(40) | YES | | NULL | | | domain_name | varchar(255) | YES | | NULL | | | domain_path | varchar(255) | NO | | NULL | | | project_id | bigint(20) unsigned | YES | | 0 | | | project_uuid | varchar(40) | YES | | NULL | | | project_name | varchar(255) | YES | | NULL | | +--------------+---------------------+------+-----+-----------+-------+
Enhance the events
In order to enhance the events logged in cloudstack
Add a new field error_message and error_type in the event_view table
+---------------+---------------------+------+-----+-----------+-------+ | Field | Type | Null | Key | Default | Extra | +---------------+---------------------+------+-----+-----------+-------+ | error_message | varchar(1024) | YES | | NULL | | | error_type | varchar(255) | YES | | NULL | | +---------------+---------------------+------+-----+-----------+-------+
- Use the existing parameters field (in the event and event_view table) to hold the event parameters. For example, the parameters required for deployVirtualMachine command like the zoneId, serviceOfferingId, templateId would be stored in the parameters field to be queried later.
Add a new field resource_uuid, error_message and error_type in usage_event table
+---------------+---------------------+------+-----+-----------+-------+ | Field | Type | Null | Key | Default | Extra | +---------------+---------------------+------+-----+-----------+-------+ | resource_uuid | varchar(40) | YES | | NULL | | | error_message | varchar(1024) | YES | | NULL | | | error_type | varchar(255) | YES | | NULL | | +---------------+---------------------+------+-----+-----------+-------+
error_message – detailed message describing the cause of failure
error_type – type of errors like resource allocation errors, errors with the physical resource etc.
resource_uuid – uuid of the resources like virtual machine, zone etc.
Enhance the listEvents api
Add the following request parameters to the listEvents api to list all the events by resource uuids
| Parameter Name | Description | Required |
|---|---|---|
| resourceuuid | list all events by resource uuid. To be used with resourcetype parameter. | false |
| resourcetype | list all events by resource type. | false |
Introduce resource UUID in event description
Currently, the resource uuid passed as parameter is translated into internal id while processing the parameters. In order to display the resource uuid's in the event description the uuid need not be translated to internal id.
while (st.hasMoreTokens()) {
...
switch (listType) {
case INTEGER:
listParam.add(Integer.valueOf(token));
break;
case UUID:
if (token.isEmpty())
break;
final Long internalId = translateUuidToInternalId(token, annotation);
listParam.add(internalId);
break;
...
}
}
...
Detailed error messages in events
In case of events logged due to an error occurred while processing a job or change of state of a resource , a detailed error message describing the reason of failure would be logged into the error_message field of the event. Based on who the user is an admin or a normal user relevant error message would be shown to the end user.
How would error_message data be filled?
Currently, the error messages are ignored in case of any exceptions while a job is performed. The event interceptors in case of error log error events with the hard coded description provided in the event files.
public class ActionEventInterceptor implements ComponentMethodInterceptor, MethodInterceptor {
...
@Override
public Object invoke(MethodInvocation invocation) throws Throwable {
...
try {
interceptorData = interceptStart(m, target);
Object result = invocation.proceed();
success = true;
return result;
} finally {
if (success) {
interceptComplete(m, target, interceptorData);
} else {
interceptException(m, target, interceptorData);
}
}
...
A catch block would help to have descriptive error messages, instead of displaying short un-descriptive event descriptions in case of error events.
Externalize the event descriptions strings
The event descriptions are currently hard coded in the java files. These strings could be externalize to a resource bundle like in a message.properties file, and can be processed in the event interceptors before an event is logged.
Overview
Content Tools
Apps