usage.from() function
The usage.from()
function is experimental and subject to change at any time.
By using this function, you accept the risks of experimental functions.
usage.from()
returns usage data from an InfluxDB Cloud organization.
Use usage.from()
to monitor your InfluxDB Cloud organization’s usage and identify
anomalies or rate limiting.
import "experimental/usage"
usage.from(
start: -30d,
stop: now(),
host: "",
orgID: "",
token: "",
raw: false,
)
Usage data schema
InfluxDB Cloud usage data is reported and reset every five minutes.
- storage_usage_bucket_bytes (measurement)
- gauge (field): Number of bytes on disk associated with a bucket.
- bucket_id (tag): Bucket ID.
- org_id (tag): Organization ID.
- http_request (measurement)
- req_bytes (field): Total number of bytes in HTTP request bodies per endpoint and status code.
- resp_bytes (field): Total number of bytes in HTTP response bodies per endpoint and status code.
- org_id (tag): Organization ID.
- endpoint (tag): InfluxDB Cloud API endpoint.
- status (tag): HTTP status code.
- query_count (measurement)
- req_bytes (field): Number of queries executed.
- endpoint (tag): InfluxDB Cloud API endpoint.
- orgID (tag): Organization ID.
- status (tag): HTTP status code.
Parameters
start
(Required) Earliest time to include in results.
stop
(Required) Latest time to include in results.
host
InfluxDB Cloud region URL.
Default is ""
.
If an empty string, the function uses the host that the query is executed from.
orgID
InfluxDB Cloud organization ID.
Default is ""
.
If an empty string, the function uses the ID of the organization that executes the query.
token
InfluxDB Cloud API token.
Default is ""
.
If an empty string, the function uses an API token associated with the user that executes the query.
The API token must be an All-Access token.
raw
Return raw, high resolution usage data instead of downsampled usage data.
Default is false
.
usage.from()
can query the following time ranges:
Data resolution | Maximum time range |
---|---|
raw | 1 hour |
downsampled | 30 days |
Examples
- Query downsampled usage data for your InfluxDB Cloud organization
- Query raw usage data for your InfluxDB Cloud organization
- Query downsampled usage data for a different InfluxDB Cloud organization
- Query number of bytes in requests to the /api/v2/write endpoint
- Query number of bytes returned from the /api/v2/query endpoint
- Compare usage metrics to organization usage limits
Query downsampled usage data for your InfluxDB Cloud organization
import "experimental/usage"
usage.from(start: -30d, stop: now())
Query raw usage data for your InfluxDB Cloud organization
import "experimental/usage"
usage.from(start: -1h, stop: now(), raw: true)
Query downsampled usage data for a different InfluxDB Cloud organization
import "experimental/usage"
import "influxdata/influxdb/secrets"
token = secrets.get(key: "INFLUX_TOKEN")
usage.from(
start: -30d,
stop: now(),
host: "https://cloud2.influxdata.com",
orgID: "x000X0x0xx0X00x0",
token: token,
)
Query number of bytes in requests to the /api/v2/write endpoint
import "experimental/usage"
usage.from(start: -30d, stop: now())
|> filter(fn: (r) => r._measurement == "http_request")
|> filter(fn: (r) => r._field == "req_bytes")
|> filter(fn: (r) => r.endpoint == "/api/v2/write")
|> group(columns: ["_time"])
|> sum()
|> group()
Query number of bytes returned from the /api/v2/query endpoint
import "experimental/usage"
usage.from(start: -30d, stop: now())
|> filter(fn: (r) => r._measurement == "http_request")
|> filter(fn: (r) => r._field == "resp_bytes")
|> filter(fn: (r) => r.endpoint == "/api/v2/query")
|> group(columns: ["_time"])
|> sum()
|> group()
Compare usage metrics to organization usage limits
import "experimental/usage"
checkLimit = (tables=<-, limit) => tables
|> map(fn: (r) => ({r with _value: r._value / 1000, limit: int(v: limit) * 60 * 5}))
|> map(fn: (r) => ({r with limitReached: r._value > r.limit}))
read = usage.from(start: -30d, stop: now())
|> filter(fn: (r) => r._measurement == "http_request")
|> filter(fn: (r) => r._field == "resp_bytes")
|> filter(fn: (r) => r.endpoint == "/api/v2/query")
|> group(columns: ["_time"])
|> sum()
|> group()
write = usage.from(start: -30d, stop: now())
|> filter(fn: (r) => r._measurement == "http_request")
|> filter(fn: (r) => r._field == "req_bytes")
|> filter(fn: (r) => r.endpoint == "/api/v2/write")
|> group(columns: ["_time"])
|> sum()
|> group()
|> checkLimit(limit: limits.rate.writeKBs)
union(tables: [read, write])
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Flux and this documentation. To find support, the following resources are available:
InfluxDB Cloud customers can contact InfluxData Support.