usage.from() function

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:

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])