Activity
========
So far we've learned about regular `structs <structs.html>`_, but activity is
special.
Activity is an event tied to a specific time and topic and has a small amount
of data piggybacked to it.
Anatomy of an event
-------------------
``topic``
This is some freestyle text used to group events to a specific topic. This
must not conflict with other modules unless there's a very good reason.
The topic should look like ``kpcyrd/example:something``, with ``something``
being a meaningful unique identifier for whatever is generating these
events, like a mac address or an account name/id.
The rules around this might become stricter in the future.
``time``
The most important part of the event: The time and date it happened.
``initial``
This value can not be set but might be present in sn0int output. See `Querying events`_.
``uniq`` (optional)
This is an optional feature to deduplicate events. Assuming you're
importing posts by an account, you wouldn't want to store a new event for
each post you already imported. If you set this field to the technical post
id then sn0int would skip the event if it already has an event with the
same ``topic`` and ``uniq`` combination to avoid inserting duplicates.
``latitude`` (optional)
Latitude - if you can tie the event to a specific location.
``longitude`` (optional)
Longitude - if you can tie the event to a specific location.
``radius`` (optional)
The location radius in meters. If the position you got has a precision of
100 meters set this value to ``100``.
``content``
Arbitrary data that you want to attach to the event. This doesn't need to
be a string and can be an arbitrary object that is then stored as json
string.
Logging events
--------------
An ``activity`` event can be logged with ``db_activity``:
.. code-block:: lua
db_activity({
topic='harness/activity-ping:dummy',
time=sn0int_time(),
content={
a='b',
foo={
bar=1337,
},
msg='ohai',
},
})
Logging an event that has a location attached could look like this:
.. code-block:: lua
db_activity({
topic='harness/activity-ping:dummy',
time=sn0int_time(),
latitude=40.726662,
longitude=-74.036677,
radius=50,
content={
a='b',
foo={
bar=1337,
},
msg='ohai',
},
})
Making sure an event is not logged twice can be done with ``uniq``:
.. code-block:: lua
-- create the first event
db_activity({
topic='harness/activity-ping:dummy',
time=sn0int_time(),
uniq='12345',
content='ohai',
})
-- this does nothing because we already have an event with this topic+uniq combination
db_activity({
topic='harness/activity-ping:dummy',
time=sn0int_time(),
uniq='12345',
content='ohai',
})
-- this creates a new event because uniq is different
db_activity({
topic='harness/activity-ping:dummy',
time=sn0int_time(),
uniq='6789',
content='ohai',
})
-- this also creates a new event because topic is different
db_activity({
topic='harness/activity-ping:something-else',
time=sn0int_time(),
uniq='6789',
content='ohai',
})
Querying events
---------------
There is a commandline interface that can be used to query all events we've
logged. To get everything (sorted by time)::
sn0int activity
To limit the output to a specific topic::
sn0int activity -t harness/activity-ping:dummy
To limit it to a specific time frame::
# everything since
sn0int activity --since 2020-01-13T04:20:00
# everything until
sn0int activity --until 2020-01-13T04:20:00
# both
sn0int activity --since yesterday --until today
When using ``--since`` you might also want to know the previous state and use
it as an initial value. Consider this example::
2020-01-13 14:30:00 # user goes offline
2020-01-13 23:59:00 # user goes online
2020-01-14 09:30:00 # user goes idle
2020-01-14 14:20:00 # user goes offline
If we're running a query like ``sn0int activity --since 2020-01-14T00:00:00``
the program consuming the output wouldn't know that the user is initially
online because we're only getting this data::
{"id":8,"topic":"foo/bar:asdf","time":"2020-01-14T09:30:00","content":{"state":"idle"}}
{"id":9,"topic":"foo/bar:asdf","time":"2020-01-14T14:20:00","content":{"state":"offline"}}
We can tweak this with ``sn0int activity --initial --since
2020-01-14T00:00:00`` to include one more event that we only use to populate
the intial state::
{"id":7,"initial":true,"topic":"foo/bar:asdf","time":"2020-01-13T23:59:00","content":{"state":"online"}}
{"id":8,"topic":"foo/bar:asdf","time":"2020-01-14T09:30:00","content":{"state":"idle"}}
{"id":9,"topic":"foo/bar:asdf","time":"2020-01-14T14:20:00","content":{"state":"offline"}}
Visualization
-------------
There is no visualization built in, there may be external frontends for this in
the future. You're very welcome to write one!