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

Data model


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`.


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.

An event type for the currently active webbrowser tab.

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


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



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

    app: string,
    title: string,



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

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