Permalink
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (70 sloc) 2.92 KB

Data model

Buckets

The fundamental datacontainer in ActivityWatch, a bucket contains events and common metadata for those events (such as which type of events they are, where they were collected, and by what).

It is recommended to have one bucket per watcher and host. A bucket should always receive data from the same source.

For example, if we want to write a watcher that should track the currently active window we would first have it create a bucket named 'example-watcher-window_myhostname' and then start reporting events to that bucket (using heartbeats).

bucket = {
  "id": "aw-watcher-test_myhostname",
  "created": "2017-05-16T13:37:00.000000",
  "name": "A short but descriptive human readable bucketname",
  "type": "com.example.test",       // Type of events in bucket
  "client": "example-watcher-test", // Identifier of client software used to report data
  "hostname": "myhostname",         // Hostname of device where data was collected
}

For information about the "type" field, see examples at :ref:`event types`.

Events

The event model used by ActivityWatch is pretty simple, here is the JSON representation:

event = {
  "timestamp": "2016-04-27T15:23:55Z",  // ISO8601 formatted timestamp
  "duration": 3.14,                     // Duration in seconds
  "data": {"key": "value"},  // A JSON object, the schema of this depends on the event type
}

It should be noted that all timestamps are stored as UTC. Timezone information (UTC offset) is currently discarded.

The content in the "data" field could be any JSON object, but it is recommended that every event in a bucket should follow some format depending on the buckettype so the data is easy to analyze.

Event types

To separate different types of data in ActivityWatch there is the event type. A buckets event type specified the schema of the events in the bucket.

By creating standards for watchers to use we enable easier transformation and visualization.

web.tab.current

An event type for the currently active webbrowser tab.

{
    url: string,
    title: string,
    audible: bool,
    incognito: bool,
}

app.editor.activity

An event type for tracking the currently edited file.

{
    file: string,     // full path to file
    project: string,  // full path of cwd
    language: string, // name of language of the file
}

currentwindow

Note

There are suggestions to improve/change this format (see :issue:`201`)

{
    app: string,
    title: string,
}

afkstatus

Note

There are suggestions to improve/change this format (see :issue:`201`)

{
    status: string   // "afk" or "not-afk"
}