dp3 sh command reference¶
dp3 sh is a shell-oriented client for reading from and writing to a running DP³ API. It formats API responses as JSON or newline-delimited JSON and provides commands for datapoints, entities, control actions, telemetry, and shell completion.
On a deployment host, you can use the generated <APPNAME>sh wrapper in place of dp3 sh. The wrapper supplies the application's configuration directory. Otherwise, select a configuration with --config or DP3_CONFIG_DIR, and use --url when the API is not available through the automatically probed localhost URLs.
usage: dp3 sh [-h] [-c CONFIG] [-u URL] [-t TIMEOUT]
{health,datapoints,entities,entity,control,telemetry,completion}
...
positional arguments:
{health,datapoints,entities,entity,control,telemetry,completion}
health Check whether the API is reachable.
datapoints Post datapoints from JSON input.
entities Return the full entity-type map exposed by the API.
entity Inspect and modify entity data.
control Execute control actions.
telemetry Read operational telemetry.
completion Print shell completion scripts.
options:
-c CONFIG, --config CONFIG
Path to the DP3 configuration directory. Resolution
order: --config, DP3_CONFIG_DIR, ./config.
-u URL, --url URL Base URL of the DP3 API. When omitted, localhost
defaults are probed.
-t TIMEOUT, --timeout TIMEOUT
HTTP timeout in seconds.
health¶
Check whether the configured DP³ API is reachable.
datapoints¶
Post a JSON array of datapoints from a file or standard input. Each datapoint must contain type, id, attr, v, and src; observations and time series also require ISO 8601 t1 and t2 timestamps.
usage: dp3 sh datapoints [-h] [path]
positional arguments:
path Path to a JSON file, or '-' / omitted to read stdin.
entities¶
Return the full entity-type map exposed by the API. Pipe the result through jq keys to print only entity type names.
entity¶
Inspect and modify data for a selected entity type. Use dp3 sh entities to list the available entity types.
list¶
List latest snapshots for entities of type <ETYPE>.
usage: dp3 sh entity <ETYPE> list [-h] [-q FULLTEXT_JSON] [-j FILTER_JSON]
[-a HAS_ATTR] [-s SKIP] [-l LIMIT]
[-F {json,ndjson}]
options:
-q FULLTEXT_JSON, --fulltext-json FULLTEXT_JSON
JSON object with fulltext search filters, for example
`{"name":"router"}`.
-j FILTER_JSON, --filter-json FILTER_JSON
JSON object using MongoDB query syntax.
-a HAS_ATTR, --has-attr HAS_ATTR
Limit results to latest snapshots where the attribute
has data present.
-s SKIP, --skip SKIP Skip this many results before returning data.
-l LIMIT, --limit LIMIT
Return at most this many results.
-F {json,ndjson}, --format {json,ndjson}
Choose JSON or NDJSON output.
count¶
Count latest snapshots for entities of type <ETYPE>. JSON filters use MongoDB query syntax.
usage: dp3 sh entity <ETYPE> count [-h] [-q FULLTEXT_JSON] [-j FILTER_JSON]
[-a HAS_ATTR]
options:
-q FULLTEXT_JSON, --fulltext-json FULLTEXT_JSON
JSON object with fulltext search filters, for example
`{"name":"router"}`.
-j FILTER_JSON, --filter-json FILTER_JSON
JSON object using MongoDB query syntax.
-a HAS_ATTR, --has-attr HAS_ATTR
Limit results to latest snapshots where the attribute
has data present.
raw¶
Browse current raw datapoints for entities of type <ETYPE>.
usage: dp3 sh entity <ETYPE> raw [-h] [-a ATTR] [-r SRC] [-s SKIP] [-l LIMIT]
[-F {json,ndjson}]
options:
-a ATTR, --attr ATTR Limit raw datapoints to one attribute.
-r SRC, --src SRC Limit raw datapoints to one source.
-s SKIP, --skip SKIP Skip this many raw datapoints before returning data.
-l LIMIT, --limit LIMIT
Return at most this many raw datapoints.
-F {json,ndjson}, --format {json,ndjson}
Choose JSON or NDJSON output.
attr-values¶
Get distinct latest values of an attribute across entities of type <ETYPE>.
usage: dp3 sh entity <ETYPE> attr-values [-h] ATTR
positional arguments:
ATTR Attribute to query across the entity type.
id get¶
Get full data for one entity.
usage: dp3 sh entity <ETYPE> id EID get [-h] [-f DATE_FROM] [-t DATE_TO]
options:
-f DATE_FROM, --from DATE_FROM
ISO 8601 lower timestamp bound of the time range.
-t DATE_TO, --to DATE_TO
ISO 8601 upper timestamp bound of the time range.
id master¶
Get the master record for one entity.
usage: dp3 sh entity <ETYPE> id EID master [-h] [-f DATE_FROM] [-t DATE_TO]
options:
-f DATE_FROM, --from DATE_FROM
ISO 8601 lower timestamp bound of the time range.
-t DATE_TO, --to DATE_TO
ISO 8601 upper timestamp bound of the time range.
id snapshots¶
Get snapshots for one entity. Time bounds are ISO 8601 timestamps.
dp3 sh entity <ETYPE> id EID snapshots --from 2024-01-01T00:00:00Z --to 2024-02-01T00:00:00Z --limit 100 --format ndjson
usage: dp3 sh entity <ETYPE> id EID snapshots [-h] [-f DATE_FROM] [-t DATE_TO]
[-s SKIP] [-l LIMIT]
[-F {json,ndjson}]
options:
-f DATE_FROM, --from DATE_FROM
ISO 8601 lower timestamp bound of the snapshot time
range.
-t DATE_TO, --to DATE_TO
ISO 8601 upper timestamp bound of the snapshot time
range.
-s SKIP, --skip SKIP Skip this many snapshots before returning data.
-l LIMIT, --limit LIMIT
Return at most this many snapshots.
-F {json,ndjson}, --format {json,ndjson}
Choose JSON or NDJSON output.
id raw¶
Browse current raw datapoints for one entity.
usage: dp3 sh entity <ETYPE> id EID raw [-h] [-a ATTR] [-r SRC] [-s SKIP]
[-l LIMIT] [-F {json,ndjson}]
options:
-a ATTR, --attr ATTR Limit raw datapoints to one attribute.
-r SRC, --src SRC Limit raw datapoints to one source.
-s SKIP, --skip SKIP Skip this many raw datapoints before returning data.
-l LIMIT, --limit LIMIT
Return at most this many raw datapoints.
-F {json,ndjson}, --format {json,ndjson}
Choose JSON or NDJSON output.
id attr¶
Get or modify one attribute value for one entity.
usage: dp3 sh entity <ETYPE> id EID attr [-h] ATTR {get,set} ...
positional arguments:
ATTR
{get,set}
get Get an entity attribute value.
set Set a current entity attribute value.
get¶
Get one attribute value for one entity.
usage: dp3 sh entity <ETYPE> id EID attr ATTR get [-h] [-f DATE_FROM]
[-t DATE_TO]
options:
-f DATE_FROM, --from DATE_FROM
ISO 8601 lower timestamp bound of the time range.
-t DATE_TO, --to DATE_TO
ISO 8601 upper timestamp bound of the time range.
set¶
Set the current value of one entity attribute from a JSON literal.
usage: dp3 sh entity <ETYPE> id EID attr ATTR set [-h] VALUE_JSON
positional arguments:
VALUE_JSON JSON literal value, for example `"hello"`, `42`, `true`, or
`{"k":1}`.
id ttl¶
Extend TTLs for one entity using a JSON request body.
usage: dp3 sh entity <ETYPE> id EID ttl [-h] -b BODY_JSON
options:
-b BODY_JSON, --body-json BODY_JSON
JSON body describing the TTL update request.
id delete¶
Delete data for one entity.
control¶
Execute operational control actions against the DP³ API.
usage: dp3 sh control [-h]
{make-snapshots,refresh-on-entity-creation,refresh-module-config}
...
positional arguments:
{make-snapshots,refresh-on-entity-creation,refresh-module-config}
make-snapshots Trigger an out-of-order snapshot run.
refresh-on-entity-creation
Re-run entity creation callbacks for an entity type.
refresh-module-config
Reload module configuration.
make-snapshots¶
Trigger an out-of-order snapshot run.
refresh-on-entity-creation¶
Re-run entity-creation callbacks for one entity type.
refresh-module-config¶
Reload configuration for one module.
telemetry¶
Read operational telemetry from DP³ services.
usage: dp3 sh telemetry [-h]
{sources-validity,source-age,entities-per-attr,attribute-bson-sizes,snapshot-summary,metadata,rabbitmq-queues,event-counts}
...
positional arguments:
{sources-validity,source-age,entities-per-attr,attribute-bson-sizes,snapshot-summary,metadata,rabbitmq-queues,event-counts}
sources-validity Show source validity timestamps.
source-age Show source ages.
entities-per-attr Count entities with data present for each attribute.
attribute-bson-sizes
Show cached logical BSON-size statistics for
attributes.
snapshot-summary Show recent snapshot activity summary.
metadata Browse internal metadata records.
rabbitmq-queues Show RabbitMQ queue telemetry.
event-counts Read EventCountLogger counters from Redis.
sources-validity¶
Show the latest datapoint validity timestamp observed for each source.
source-age¶
Show the age of each source in the selected unit.
usage: dp3 sh telemetry source-age [-h] [-u {minutes,seconds}]
options:
-u {minutes,seconds}, --unit {minutes,seconds}
entities-per-attr¶
Count entities with data present for each configured attribute.
attribute-bson-sizes¶
Show cached logical BSON-size statistics for configured attributes.
snapshot-summary¶
Show a summary of recent snapshot activity.
metadata¶
Browse diagnostic records produced by internal periodic processes. Time bounds are ISO 8601 timestamps.
dp3 sh telemetry metadata --module SnapShooter --from 2024-01-01T00:00:00Z --sort oldest --limit 100 --format ndjson
usage: dp3 sh telemetry metadata [-h] [-m MODULE] [-f DATE_FROM] [-t DATE_TO]
[-s SKIP] [-l LIMIT] [-S {newest,oldest}]
[-F {json,ndjson}]
options:
-m MODULE, --module MODULE
Limit records to one module.
-f DATE_FROM, --from DATE_FROM
ISO 8601 lower timestamp bound.
-t DATE_TO, --to DATE_TO
ISO 8601 upper timestamp bound.
-s SKIP, --skip SKIP Skip this many records.
-l LIMIT, --limit LIMIT
Return at most this many records.
-S {newest,oldest}, --sort {newest,oldest}
Select record ordering.
-F {json,ndjson}, --format {json,ndjson}
Choose JSON or NDJSON output.
rabbitmq-queues¶
Show queue sizes, consumers, and message rates for the application.
event-counts¶
Read EventCountLogger counters directly from the configured Redis instance.
usage: dp3 sh telemetry event-counts [-h] -g GROUP -i INTERVAL
[--last | --current | --both]
options:
-g GROUP, --group GROUP
Configured event counter group.
-i INTERVAL, --interval INTERVAL
Configured counter interval.
--last Show the last completed interval (default).
--current Show the current incomplete interval.
--both Show both the last and current intervals.
completion¶
Print an argcomplete registration script for the selected shell. Evaluate the output or source it from your shell startup file.
usage: dp3 sh completion [-h] [-c COMPLETION_COMMANDS]
{bash,zsh,fish,tcsh,powershell}
positional arguments:
{bash,zsh,fish,tcsh,powershell}
Shell name.
options:
-c COMPLETION_COMMANDS, --command COMPLETION_COMMANDS
Command name to register completion for. Repeat to
register multiple commands. Use `dp3` for `dp3 sh` and
`<APPNAME>sh` for wrapper commands.