gRPC: tasks

Tasks, events and alarms.

`TaskService`

Tasks: long-running operations with state, progress and result.

Method	Request	Response	Description
`GetTask`	`GetTaskRequest`	`Task`	One task by id.
`ListTasks`	`ListTasksRequest`	`ListTasksResponse`	Tasks that match a filter.
`CancelTask`	`CancelTaskRequest`	`Task`	Asks a running or queued task to stop; returns the task.
`WaitTask`	`WaitTaskRequest`	`Task`	Blocks until the task is terminal or `timeout_seconds` elapses.

`EventService`

The event log of the inventory.

Method	Request	Response	Description
`QueryEvents`	`QueryEventsRequest`	`QueryEventsResponse`	Events that match a filter.

`AlarmService`

Alarm states of inventory objects.

Method	Request	Response	Description
`ListAlarms`	`ListAlarmsRequest`	`ListAlarmsResponse`	Alarm states.
`AcknowledgeAlarm`	`AcknowledgeAlarmRequest`	`Empty`	Acknowledges a triggered alarm on an object.

Messages

`Task`

A long-running operation.

Field	Number	Type	Description
`id`	1	`string`	Id of the task.
`description_id`	2	`string`	Message id of what the task does (`task.virtual_machine.power_on`).
`entity`	3	`string`	Id of the object the task works on.
`entity_name`	4	`string`	Name of that object when the task started.
`state`	5	`TaskState`	State of the task.
`progress`	6	`uint32`	Progress in percent, 0 to 100.
`result_json`	7	`string`	Result of a successful task as JSON; empty otherwise.
`error`	8	`ErrorDetail`	Error of a failed task.
`user`	9	`string`	User who started the task.
`chain_id`	10	`string`	Id shared by the task and the events and tasks it caused.
`queued_at`	11	`string`	Time the task was queued, RFC 3339.
`started_at`	12	`string`	Time the task started, RFC 3339; empty while queued.
`completed_at`	13	`string`	Time the task ended, RFC 3339; empty while it runs.
`attempt`	14	`uint32`	Attempt number, 1 for the first run.
`cancel_requested`	15	`bool`	A cancellation was asked for and the task has not ended yet.

`GetTaskRequest`

Reads one task.

Field	Number	Type	Description
`id`	1	`string`	Id of the task.

`ListTasksRequest`

Lists tasks.

Field	Number	Type	Description
`entity`	1	`string`	Only the tasks of this object.
`states`	2	repeated `TaskState`	Only the tasks in these states.
`user`	3	`string`	Only the tasks of this user.
`chain_id`	4	`string`	Only the tasks of this chain.
`page`	5	`PageRequest`	Paging.

`ListTasksResponse`

A page of tasks.

Field	Number	Type	Description
`items`	1	repeated `Task`	The tasks of the page.
`page`	2	`PageInfo`	Store version and cursor of the next page.

`CancelTaskRequest`

Asks a task to stop.

Field	Number	Type	Description
`id`	1	`string`	Id of the task.

`WaitTaskRequest`

Waits for a task to end.

Field	Number	Type	Description
`id`	1	`string`	Id of the task.
`timeout_seconds`	2	`uint32`	Longest wait in seconds; the answer is the task as it is then.

`Event`

One entry of the event log.

Field	Number	Type	Description
`id`	1	`string`	Id of the event.
`event_type`	2	`string`	Event type (`VmPoweredOnEvent`).
`severity`	3	`Severity`	Severity.
`message_key`	4	`string`	Message id the console localises.
`message_args`	5	map<`string`, `string`>	Arguments of the message id.
`entity`	6	`string`	Id of the object the event is about.
`entity_name`	7	`string`	Name of that object when the event happened.
`related`	8	repeated `string`	Ids of further objects involved.
`user`	9	`string`	User whose action caused the event.
`chain_id`	10	`string`	Id of the chain of tasks and events it belongs to.
`task`	11	`string`	Id of the task that caused the event.
`created_at`	12	`string`	Time of the event, RFC 3339.
`attributes`	13	map<`string`, `string`>	Further attributes of the event type.

`QueryEventsRequest`

Queries the event log.

Field	Number	Type	Description
`entity`	1	`string`	Only the events of this object.
`recursive`	2	`bool`	Also the events of the objects under it.
`event_types`	3	repeated `string`	Only these event types.
`user`	4	`string`	Only the events caused by this user.
`chain_id`	5	`string`	Only the events of this chain.
`begin`	6	`string`	Earliest time, RFC 3339.
`end`	7	`string`	Latest time, RFC 3339.
`after_id`	8	`uint64`	Collector cursor: only events with id number greater than this.
`page`	9	`PageRequest`	Paging.

`QueryEventsResponse`

A page of events.

Field	Number	Type	Description
`items`	1	repeated `Event`	The events of the page.
`page`	2	`PageInfo`	Store version and cursor of the next page.

`AlarmState`

The status of an alarm on one object.

Field	Number	Type	Description
`entity`	1	`string`	Id of the object.
`status`	2	`AlarmStatus`	Status.
`since`	3	`string`	Time of the last status change, RFC 3339.
`acknowledged`	4	`bool`	Someone acknowledged the triggered status.

`Alarm`

An alarm definition with its states.

Field	Number	Type	Description
`id`	1	`string`	Id of the alarm.
`name`	2	`string`	Name.
`description`	3	`string`	What the alarm watches.
`scope`	4	`string`	Id of the object the alarm applies to and below.
`enabled`	5	`bool`	The alarm is evaluated.
`trigger_json`	6	`string`	Trigger definition as JSON, the same shape as in the REST API.
`states`	7	repeated `AlarmState`	Status on each object in scope.

`ListAlarmsRequest`

Lists the alarms.

Field	Number	Type	Description
`entity`	1	`string`	Only alarms applicable to this entity (empty = all).

`ListAlarmsResponse`

The alarms.

Field	Number	Type	Description
`items`	1	repeated `Alarm`	Every alarm with its states.

`AcknowledgeAlarmRequest`

Acknowledges a triggered alarm.

Field	Number	Type	Description
`alarm`	1	`string`	Id of the alarm.
`entity`	2	`string`	Id of the object it triggered on.

Enums

`TaskState`

State of a task.

Value	Number	Description
`TASK_STATE_QUEUED`	0
`TASK_STATE_RUNNING`	1
`TASK_STATE_SUCCESS`	2
`TASK_STATE_ERROR`	3
`TASK_STATE_CANCELLED`	4

`Severity`

Severity of an event.

Value	Number	Description
`SEVERITY_INFO`	0
`SEVERITY_WARNING`	1
`SEVERITY_ERROR`	2
`SEVERITY_USER`	3

`AlarmStatus`

Status of an alarm on an object; gray means not evaluated.

Value	Number	Description
`ALARM_STATUS_GRAY`	0
`ALARM_STATUS_GREEN`	1
`ALARM_STATUS_YELLOW`	2
`ALARM_STATUS_RED`	3