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
- Query the query count for InfluxDB Cloud query endpoints
- 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()
Query the query count for InfluxDB Cloud query endpoints
The following query returns query counts for the following query endpoints:
- /api/v2/query: Flux queries
- /query: InfluxQL queries
import "experimental/usage"
usage.from(start: -30d, stop: now())
|> filter(fn: (r) => r._measurement == "query_count")
|> sort(columns: ["_time"])
Compare usage metrics to organization usage limits
The following query compares the amount of data written to and queried from your
InfluxDB Cloud organization to your organization’s rate limits.
It appends a limitReached
column to each row that indicates if your rate
limit was exceeded.
import "experimental/usage"
limits = usage.limits()
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()
|> checkLimit(limit: limits.rate.readKBs)
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])
Was this page helpful?
Thank you for your feedback!
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, use the following resources:
InfluxDB Cloud customers can contact InfluxData Support.