Cellular Utilization

Remote Manager generates cellular utilization reports that can categorize devices cell plan use.

The device reports cellular utilization in a set of metric streams. On a DAL (Digi Accelerated Linux) device, the cellular utilization metric streams must be enabled using Monitoring -> Device Health -> Enable device metric samples upload configuration setting.

For a DAL (Digi Accelerated Linux) device, the monitored metric streams are

  • metrics/cellular/M/simS/carrier
  • metrics/cellular/M/simS/provider
  • metrics/cellular/M/simS/rx/bytes
  • metrics/cellular/M/simS/tx/bytes

Where the M is the modem number and S is the sim number.

Use the v1/reports API to get a list of all available reports or a specific status report.

URI

http://<hostname>/ws/v1/reports/cellular_utilization

Formats

Method Formats Description Parameters
GET /ws/v1/reports/cellular_utilization Get a list of detailed cellular utilization information for devices. cursor, end_time, groupby, orderby, query, size, start_time
GET /ws/v1/reports/cellular_utilization/bulk Get a CSV list of detailed cellular utilization information for devices. end_time, groupby, orderby, query, start_time, fields
GET /ws/v1/reports/cellular_utilization/summary Get a list of summarized cellular utilization information for devices. end_time, groupby, orderby, query, start_time
GET /ws/v1/reports/cellular_utilization/summary/bulk Get a CSV list of summarized cellular utilization information for devices. end_time, groupby, orderby, query, start_time, fields

Parameters

Name Type Description
cursor string Specify the cursor (returned in the last page of results) to resume paging through results.
end_time timestamp Specify the end time (exclusive) in ISO 8601 or epoch (long) or relative time (matching the form [-+]N[dhms] where d is days, h is hours, m is minutes, s is seconds, and -1d means one day ago, while +1d means one day from now).
fields string Comma-separated list of fields to return for bulk API
groupby string The groupby parameter behaves similarly for detail and summary APIs.
orderby string Specify the field to order by, optionally followed by asc or desc for ascending or descending sort.
query string Specify the device query to summarize. The query language is similar to SQL Query sntax:SQL-like conditions using AND, OR, and parenthesis to group expressionsVarious condition operators on numeric and text valuesSingle quoted text literals: ‘TheText’Text escape for quote character is the quote: ‘isn’’t difficult’Numeric literals support 0x prefix for hexEnumerated values (like connection_status) are treated as textCase insensitive comparisonsTimestamp field conditions are not supported.
size integer Specify the size of the page to return.
start_time timestamp Specify the start time (inclusive) in ISO 8601 or epoch (long) or relative time (matching the form [-+]N[dhms] where d is days, h is hours, m is minutes, s is seconds, and -1d means one day ago, while +1d means one day from now).

Query Parameters

The following query parameters have some unique behavior relative to other APIs.

groupby

Detail APIs

For the /ws/v1/reports/cellular_utilization and /ws/v1/reports/cellular_utilization/bulk APIs, specify none, device, carrier, or provider fields in the groupby parameter.

By default, and with the none value, when generating a detail report for each device, the cellular utilization is shown and there is no specific grouping. Grouping by none can generate a detail report with many rows for each device, depending on which combination of modem, sim, carrier, and provider were used when the traffic was generated.

Grouping by device fields generates a detail report with a single bytes_sent, bytes_received and total values for each device regardless which modem, sim, carrier, or provider was used for the traffic. The modem, sim, carrier and provider fields are not included in the report.

Similarly, grouping by carrier or provider fields generates a detail report with a single bytes_sent, bytes_received and total values for each carrier or provider used by a devce regardless which modem or sim was used for the traffic. The modem, sim, and the other provider or carrier fields are not included in the report.

For none or when groupby is not specified, example data is shown below (shown as a table instead of json or csv):

name   device_id                            device_type     group      firmware_version   provider  carrier    modem  sim   bytes_sent  bytes_received  total
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           AT&T      AT&T       1      1     1000000     2000000         3000000
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           AT&T      Sprint     1      1     2000000     4000000         6000000
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           AT&T      AT&T       2      1     3000000     6000000         9000000

For device, the data above would be grouped as (shown as a table instead of json or csv):

name   device_id                            device_type     group      firmware_version   bytes_sent  bytes_received  total
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           6000000     12000000        18000000

For carrier, the data above would be grouped as (shown as a table instead of json or csv):

name   device_id                            device_type     group      firmware_version   carrier   bytes_sent  bytes_received  total
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           AT&T      4000000     8000000         12000000
Bus42  00000000-00000000-000000FF-FF123456  Digi TX64       NorthWest  23.6.1.0           Sprint    2000000     4000000         6000000

Summary APIs

For the /ws/v1/reports/cellular_utilization/summary and /ws/v1/reports/cellular_utilitization/summary/bulk APIs, specify modem, sim, carrier, provider, device_type, firmware_version, group to summarize utilization across devices.

Query fields

Build query conditions using the following fields for cellular utilization.

See v1 API Query Language for detailed information on building API queries.

  • bytes_received - The number of bytes sent in the interval
  • bytes_sent - The number of bytes sent in the interval
  • carrier - The reported network carrier of the traffic
  • customer_id - The id of the account owning the device
  • device_id - The device ID of the device that recorded the traffic
  • device_type - The type of the device
  • firmware_version - The current firmware version of the device
  • group - The current group that the device is stored in
  • modem - The modem number of the traffic
  • name - The current name of the device
  • provider - The reported sim provider of the traffic
  • sim - The sim number of the traffic
  • total - The total number of bytes sent and received in the interval