history

Usage

fugue [global options] history [options] (<FID> | <alias>)

Arguments

<FID> | <alias>
FID or alias of the target process

Options

Global options are detailed here.

-s | --start <start_time>
Start time of job or event. Includes only jobs or events started or updated after a specific time. Format: "mm/dd/YYYY HH:MM"
-e | --end <end_time>
End time of job or event. Includes only jobs or events started or updated before a specific time. Format: "mm/dd/YYYY HH:MM"
--json
Emit output as JSON. The JSON flag displays command output in JSON format, which is useful for automation.
--help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Definition

The history command displays a detailed list of the most recent jobs or events, for a specified process. The list includes events, which are single commands for a process and dry-run jobs.

Jobs and processes

Processes consume Conductor compute time during jobs, where process data is reviewed and acted upon as necessary at regular intervals. Each job can potentially represent some change in the managed infrastructure, although most jobs are simply inspection and require no action. Jobs for multiple processes may be running at any given time.

How and whether jobs are emitted is dependent on process state. Valid process states are Running, Suspended, and Killing. Running is the most common state, where the process may be building architecture, monitoring configuration, or otherwise doing what it’s intended to do. Processes which are Killing are being cleaned up by the current job, and processes which are Suspended do not emit jobs until they are reactivated with a resume command.

For more information about the Fugue process model, see Processes.

Output

Sample history output for a composition aliased mycomposition:

History Report for user/xxxxxxxxxxxx - Thu Nov 9 2017 2:25pm
mycomposition (2ee1bf6b-a505-4d30-af75-1aa90bef5cac)

Type    Started    Work             User     Done As     Last Job Id       Last Updated    Status     Description
------  ---------  --------------   ------   ---------   ----------------  --------------  ---------  --------------
Job     2:25pm     SYSTEM                                1510255512 (1)
Event   2:24pm     FUGUE PROPERTY   alice    alice                                         SUCCEEDED  EventReceived
Job     1:04pm     SYSTEM                                1510255486 (162)  2:24pm          SUCCEEDED  JobSucceeded
Job     1:03pm     RESUME                                1510250614 (1)    1:03pm          SUCCEEDED  JobSucceeded
Event   1:03pm     FUGUE RESUME     bob      bob                                           SUCCEEDED  EventReceived
Event   1:01pm     FUGUE SUSPEND    bob      bob                                           SUCCEEDED  EventReceived
Job     1:01pm     SYSTEM                                1510250509 (1)    1:01pm          HALTED     HaltedBySignal
Job     12:59pm    SYSTEM                                1510250464 (5)    1:01pm          SUCCEEDED  JobSucceeded
Job     12:58pm    RUN                                   1510250317 (1)    12:58pm         SUCCEEDED  JobSucceeded
Event   12:58pm    FUGUE RUN        alice    alice                                         SUCCEEDED  EventReceived

The history table includes the following details:

Type

Type of job or event. Possible values:

Job
A job is a single action within a process (e.g. actions initiated by the Conductor as the result of a command or default operations).
Event
An event is a single user command for a process. Currently supported are: run, update, suspend, resume, kill, and property.
Started
Timestamp of when the job or event was started.
Work

A subcategory for Type, the description of the action performed or recorded on a given process. --dry-run will be indicated as (dry). Possible values:

SYSTEM
A system job.
RUN
A run job.
UPDATE
An update job.
RESUME
A resume job.
KILL
A kill job.
FUGUE RUN
A fugue run command received by the Conductor.
FUGUE UPDATE
A fugue update command received by the Conductor.
FUGUE SUSPEND
A fugue suspend command received by the Conductor.
FUGUE RESUME
A fugue resume command received by the Conductor.
FUGUE KILL
A fugue kill command received by the Conductor.
FUGUE PROPERTY
A fugue property command received by the Conductor.
User
Name of the user that performed the action.
Done As
Name of the user whose permissions were used to perform the action. See RBAC Delegation for details.
Last Job ID
ID for the job with the number of repetitions for the given job (e.g. 1509731616 (32))
Last Updated
Timestamp of when the job or event was most recently updated.
Status

Status of job or event. Possible values:

IN PROGRESS
Job is in progress.
SUCCEEDED
Job or event has successfully completed.
FAILED
Job or event has failed.
HALTED
Job has timed out or has been interrupted by a user-issued suspend command.
Description

Details about the job or event. If job completed successfully, JobSucceeded is displayed. If the event took place as expected (e.g. the command was received and accepted), EventReceived is displayed. If a job is in progress, field is blank. If job or event did not complete successfully, an error message is displayed. Example errors (not an exhaustive list):

  • UnknownServiceError
  • ApiVersionNotFoundError
  • EndpointConnectionError
  • ConnectionClosedError

Examples

Emitting history output as JSON

To emit the history of all jobs for a process as JSON, use the --json option:

fugue history --json <FID | alias>

Example output (edited for length - only includes the first 2 items for event_history and job_history):

{
    "event_history": [
        {
            "account_id": "fugue-1510249007313",
            "correlation_id": "76e3df17-dbde-454f-b8ad-fbbd44d3d20f",
            "description": "EventReceived",
            "dry_run": false,
            "event_type": "FUGUE RUN",
            "fid": "2ee1bf6b-a505-4d30-af75-1aa90bef5cac",
            "principal": "root",
            "processed": 1510250299,
            "status": "SUCCEEDED",
            "status_code": 201
        },
        {
            "account_id": null,
            "correlation_id": "524380c4-d6c9-4eac-b58a-16aba4fb6a69",
            "description": "EventReceived",
            "dry_run": false,
            "event_type": "FUGUE SUSPEND",
            "fid": "2ee1bf6b-a505-4d30-af75-1aa90bef5cac",
            "principal": "root",
            "processed": 1510250509,
            "status": "SUCCEEDED",
            "status_code": 200
        },

       "job_history": [
        {
            "correlation_id": "76e3df17-dbde-454f-b8ad-fbbd44d3d20f",
            "count": 1,
            "description": "JobSucceeded",
            "dry_run": false,
            "fid": "2ee1bf6b-a505-4d30-af75-1aa90bef5cac",
            "id": 1510250310,
            "job_status": "SUCCEEDED",
            "job_type": "RUN",
            "last_job_id": "1510250317 (1)",
            "last_updated": 1510250317,
            "message": "SUCCESS",
            "start_time": 1510250310,
            "status_code": 200
        },
        {
            "correlation_id": null,
            "count": 5,
            "description": "JobSucceeded",
            "dry_run": false,
            "fid": "2ee1bf6b-a505-4d30-af75-1aa90bef5cac",
            "id": 1510250460,
            "job_status": "SUCCEEDED",
            "job_type": "SYSTEM",
            "last_job_id": "1510250464 (5)",
            "last_updated": 1510250464,
            "message": "SUCCESS",
            "start_time": 1510250341,
            "status_code": 200
        }

JSON-formatted history output

The following fields are returned with fugue history --json <FID | alias>, and are grouped under “event:sub:history” and “job:sub:history”.

The fields for “event:sub:history” include:

account_id
The account the process is running in, default account if empty.
correlation_id
GUID correlating to the user command for which the job or event was created.
description
Details about the event.
dry_run
Whether job or event is a dry-run.
event_type
Name of the Fugue command issued.
fid
Fugue ID of the process.
principal
Name of the user that issued the command.
processed
Unix timestamp of when the event occurred.
status
Status of the event.
status_code
HTTP status code of the event.

The fields for “job:sub:history” include:

correlation_id
GUID correlating to the user command for which the job was created.
count
Total of system jobs represented by this job entry. All successful system jobs are collapsed into a single entry.
description
Details about the job.
dry_run
Whether job is a dry-run.
fid
Fugue ID of the process.
id
Unique ID for a group of identical jobs run in succession (same as Row Id in normal history output).
job_status
Status of job.
job_type
Type of job.
last_job_id
Last ID for the job.
last_updated
Unix timestamp of when the job was most recently updated.
message
Content of most recent internal message, if applicable; either SUCCESS, SUCCEEDED, or an error message.
start_time
Unix timestamp of when the job was started.
status_code
Numerical status code for a job.

Returning Job History For a Specific Period of Time

To retrieve job history for a specific period of time, use the -s | --start and -e | --end options, formatted as "mm/dd/YYYY HH:MM".

For example, given the following history output:

History Report for user/xxxxxxxxxxxx  - Thu Nov 9 2017 3:52pm
mycomposition (2ee1bf6b-a505-4d30-af75-1aa90bef5cac)



Type    Started    Work             User     Done As     Last Job Id       Last Updated    Status     Description
------  ---------  --------------   ------   ---------   ----------------  --------------  ---------  --------------
Job     3:52pm     SYSTEM                                1510260739 (1)
Event   2:24pm     FUGUE PROPERTY   alice    alice                                         SUCCEEDED  EventReceived
Job     1:04pm     SYSTEM                                1510260709 (336)  3:51pm          SUCCEEDED  JobSucceeded
Job     1:03pm     RESUME                                1510250614 (1)    1:03pm          SUCCEEDED  JobSucceeded
Event   1:03pm     FUGUE RESUME     bob      bob                                           SUCCEEDED  EventReceived
Event   1:01pm     FUGUE SUSPEND    bob      bob                                           SUCCEEDED  EventReceived
Job     1:01pm     SYSTEM                                1510250509 (1)    1:01pm          HALTED     HaltedBySignal
Job     12:59pm    SYSTEM                                1510250464 (5)    1:01pm          SUCCEEDED  JobSucceeded
Job     12:58pm    RUN                                   1510250317 (1)    12:58pm         SUCCEEDED  JobSucceeded
Event   12:58pm    FUGUE RUN        alice   alice                                          SUCCEEDED  EventReceived

This example displays only jobs that were started or updated after 1:30 p.m. November 9, 2017:

fugue history -s "11/09/2017 13:30" mycomposition

Which produces this output:

History Report for  user/xxxxxxxxxxxx- Thu Nov 9 2017 3:55pm
mycomposition (2ee1bf6b-a505-4d30-af75-1aa90bef5cac)


Type    Started    Work             User     Done As     Last Job Id       Last Updated    Status     Description
------  ---------  --------------   ------   ---------   ----------------  --------------  ---------  --------------
Job     3:52pm     SYSTEM                                1510260920 (6)    3:55pm          SUCCEEDED  JobSucceeded
Event   2:24pm     FUGUE PROPERTY   alice    alice                                         SUCCEEDED  EventReceived
Job     1:04pm     SYSTEM                                1510260741 (337)  3:52pm          SUCCEEDED  JobSucceeded

This example displays only jobs that were started or updated before 1:30 p.m. November 9, 2017:

fugue history -e "11/09/2017 13:30" mycomposition

Which produces this output:

History Report for user/xxxxxxxxxxxx- Thu Nov 9 2017 3:59pm
mycomposition (2ee1bf6b-a505-4d30-af75-1aa90bef5cac)


Type    Started    Work             User     Done As     Last Job Id       Last Updated    Status     Description
------  ---------  --------------   ------   ---------   ----------------  --------------  ---------  --------------
Job     1:04pm     SYSTEM                                1510261130 (350)  3:58pm          SUCCEEDED  JobSucceeded
Job     1:03pm     RESUME                                1510250614 (1)    1:03pm          SUCCEEDED  JobSucceeded
Event   1:03pm     FUGUE RESUME     root     root                                          SUCCEEDED  EventReceived
Event   1:01pm     FUGUE SUSPEND    root     root                                          SUCCEEDED  EventReceived
Job     1:01pm     SYSTEM                                1510250509 (1)    1:01pm          HALTED     HaltedBySignal
Job     12:59pm    SYSTEM                                1510250464 (5)    1:01pm          SUCCEEDED  JobSucceeded
Job     12:58pm    RUN                                   1510250317 (1)    12:58pm         SUCCEEDED  JobSucceeded
Event   12:58pm    FUGUE RUN        root     root                                          SUCCEEDED  EventReceived