167 lines
5.1 KiB
ReStructuredText
167 lines
5.1 KiB
ReStructuredText
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!
|