Activity

So far we’ve learned about regular structs, 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:

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:

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:

-- 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!