JSON databases state history

Contents

JSON databases state history
- Setup
- EAPI methods

Setup

Use the template EVA_DIR/share/svc-tpl/svc-tpl-db-json.yml:

# Event-to-JsonDB service
command: svc/eva-db-json
bus:
  path: var/bus.ipc
config:
  # database URI
  db: postgres://USER:PASSWORD@HOST/DB
  # event buffer time-to-live, seconds
  buf_ttl_sec: null
  # periodically submit all item states
  interval: null
  # do not submit remote disconnected items (useful for zfrepl or similar)
  # ignore real-time events
  skip_disconnected: false
  ignore_events: false
  # keep records (seconds)
  keep: 604800
  # automatically cleanup obsolete OIDs (can be slow)
  #cleanup_oids: true
  # event queue size
  queue_size: 8192
  # panic on critical errors in X seconds after happened (0 - panic immediately)
  panic_in: 0
  # database pool size
  #pool_size: 2 (default = workers)
  # item OIDs / OID masks
  oids:
    - "#"
  oids_exclude: []
  # enable EVA ICS PostgreSQL extension support (experimental)
  #eva_pg: true
  # by default null values (status) are written into the database
  oids_exclude_null: []
user: nobody

Create the service using eva-shell:

eva svc create eva.db.json1 /opt/eva4/share/svc-tpl/svc-tpl-db-json.yml

or using the bus CLI client:

cd /opt/eva4
cat DEPLOY.yml | ./bin/yml2mp | \
    ./sbin/bus ./var/bus.ipc rpc call eva.core svc.deploy -

(see eva.core::svc.deploy for more info)

EAPI methods

See EAPI commons for the common information about the bus, types, errors and RPC calls.

state_announce

Description	Replays state log rows as state bus publishes (same query as state_log). Note: kind chooses ST/LOC (loc) or ST/RAR (rar); default rar.
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
i	String	Item OID, supports ending masks (e.g. sensor:group/#)	yes
t_start	f64	Beginning timestamp (default: last 24 hours) (alias: s)	no
t_end	f64	Ending timestamp (default: now) (alias: e)	no
limit	u32	Limit records to (alias: n)	no
xopts	Map<String, String>	Extra: offset=N (alias: o)	no
kind	String	loc \| rar (default: rar): publish under local or remote-archive state topic prefix	no
publish_for	String/Vec<String>	Required; bus client id(s); empty list sends nothing (alias: for)	yes

state_history

Description	Gets item state history
Parameters	required
Returns	State history payload

Parameters
Name	Type	Description	Required
i	String	Item OID	yes
t_start	f64	Beginning timestamp (default: last 24 hours)	no
t_end	f64	Ending timestamp (default: now)	no
limit	u32	Limit records to	no
prop	String	Property: status or value (default: both)	no
compact	bool	Pack data in arrays according to type	no
xopts	Map<String, String>	Extra: path=JSON path, e.g. $.value.temp[0]	no

Return payload example:

[
    {
        "status": 1,
        "t": 1652059860.0424938,
        "value": 15
    },
    {
        "status": 1,
        "t": 1652059865.045223,
        "value": "something"
    },
    {
        "status": 1,
        "t": 1652059870.0452943,
        "value": {"key": "value"}
    },
    {
        "status": 1,
        "t": 1652059875.0443518,
        "value": [1, 2, 3]
    }
]

state_log

Description	Gets item state log
Parameters	required
Returns	State log payload (includes OIDs, as other svcs may support get-by-mask)

Parameters
Name	Type	Description	Required
i	String	Item OID, supports ending masks (e.g. sensor:group/#)	yes
t_start	f64	Beginning timestamp (default: last 24 hours)	no
t_end	f64	Ending timestamp (default: now)	no
limit	u32	Limit records to	no

Return payload example:

[
    {
        "oid": "sensor:tests/temp",
        "status": 1,
        "t": 1652060175.0443184,
        "value": 15
    },
    {
        "oid": "sensor:tests/temp",
        "status": 1,
        "t": 1652060180.046056,
        "value": "something"
    },
    {
        "oid": "sensor:tests/temp",
        "status": 1,
        "t": 1652060185.0454304,
        "value": {"key": "value"}
    }
]

state_push

Description	push item states into db, (payload: single item state or list). skips existing states
Parameters	required
Returns	nothing

Parameters
Name	Type	Description	Required
oid	String	Item OID (alias: i)	yes
status	i16	Item status (alias: s)	yes
value	Any	Item value (alias: v)	no
t	f64	Timestamp, seconds since epoch (required, no default; key must be ‘t’, not ‘set_time’)	yes

Return payload example:

{"oid": "sensor:tests/temp", "status": 1, "value": 15.0, "t": 1652060175.044}